Skip to content

armgit / kiln

Public Imported from GitHub
0

Build and revise procedural 3D assets with your coding agent. Local MCP server, CLI and TypeScript engine with rendered review, editable source and GLB export.

feat: add host model-call cost admission (#39)

Matthew Kissinger65b9fe435970
diff --git a/src/agent/call-budget.ts b/src/agent/call-budget.ts
index 38148440..ba1f4f7c 100644
--- a/src/agent/call-budget.ts
+++ b/src/agent/call-budget.ts
@@ -4,6 +4,22 @@ export const DEFAULT_GENERATION_MODEL_CALL_LIMIT = 40;
export type GenerationModelCallRole = 'author' | 'observer' | 'repair' | 'retry' | 'fallback';
+export interface GenerationModelCallAdmissionInput {
+ role: GenerationModelCallRole;
+ /** Strands' pre-dispatch input-token projection. An admission policy that
+ * requires a hard bound must reject a missing value. */
+ projectedInputTokens?: number;
+}
+
+export type GenerationModelCallAdmissionDecision = { ok: true } | { ok: false; reason: string };
+
+/** Optional host-owned admission policy evaluated immediately before provider
+ * dispatch. The engine supplies orchestration facts; pricing and reservations
+ * remain outside this package. */
+export interface GenerationModelCallAdmission {
+ tryAdmit(input: GenerationModelCallAdmissionInput): GenerationModelCallAdmissionDecision;
+}
+
export interface GenerationCallBudgetReceipt {
/** Aggregate ceiling. Zero preserves the legacy explicit unlimited setting. */
limit: number;
diff --git a/src/agent/hooks.test.ts b/src/agent/hooks.test.ts
index 056718b1..b8c26b9d 100644
--- a/src/agent/hooks.test.ts
+++ b/src/agent/hooks.test.ts
@@ -36,8 +36,12 @@ function fakeAgent() {
for (const cb of hooks.get(EventClass) ?? []) cb(event);
};
/** Simulate one model call: Before (cancellable) then, if not cancelled, After. */
- const modelCall = (): { cancelled: boolean; cancelText?: string } => {
- const before: { cancel?: string | boolean } = {};
+ const modelCall = (
+ projectedInputTokens?: number,
+ ): { cancelled: boolean; cancelText?: string } => {
+ const before: { cancel?: string | boolean; projectedInputTokens?: number } = {
+ ...(projectedInputTokens != null ? { projectedInputTokens } : {}),
+ };
dispatch(BeforeModelCallEvent, before);
if (before.cancel) return { cancelled: true, cancelText: String(before.cancel) };
dispatch(AfterModelCallEvent, {});
@@ -128,6 +132,36 @@ describe('MetricsCollector', () => {
expect(budget.receipt()).toMatchObject({ consumed: 2, remaining: 3, denied: 0 });
});
+ test('quoted-cost admission sees projected input and refuses before consuming the call allowance', () => {
+ const budget = createGenerationCallBudget(5);
+ const inspected: Array<{ role: string; projectedInputTokens?: number }> = [];
+ const admission = {
+ tryAdmit(call: { role: 'author'; projectedInputTokens?: number }) {
+ inspected.push(call);
+ return call.projectedInputTokens === 128_001
+ ? { ok: false as const, reason: 'quoted cost envelope input cap exceeded' }
+ : { ok: true as const };
+ },
+ };
+ const metrics = new MetricsCollector(undefined, 40, budget, 'author', admission);
+ const harness = fakeAgent();
+ metrics.attach(harness.agent as never);
+
+ expect(harness.modelCall(128_000).cancelled).toBe(false);
+ const blocked = harness.modelCall(128_001);
+
+ expect(blocked).toEqual({
+ cancelled: true,
+ cancelText: 'quoted cost envelope input cap exceeded',
+ });
+ expect(inspected).toEqual([
+ { role: 'author', projectedInputTokens: 128_000 },
+ { role: 'author', projectedInputTokens: 128_001 },
+ ]);
+ expect(metrics.capReason()).toBe('quoted cost envelope input cap exceeded');
+ expect(budget.receipt()).toMatchObject({ consumed: 1, remaining: 4, denied: 0 });
+ });
+
test('records token usage from the agent result', () => {
const m = new MetricsCollector();
m.recordResultUsage({ inputTokens: 1200, outputTokens: 340 });
diff --git a/src/agent/hooks.ts b/src/agent/hooks.ts
index f3029b67..6b022967 100644
--- a/src/agent/hooks.ts
+++ b/src/agent/hooks.ts
@@ -17,7 +17,11 @@ import {
BeforeModelCallEvent,
AfterModelCallEvent,
} from '@strands-agents/sdk';
-import type { GenerationCallBudget, GenerationModelCallRole } from './call-budget';
+import type {
+ GenerationCallBudget,
+ GenerationModelCallAdmission,
+ GenerationModelCallRole,
+} from './call-budget';
/** Token-usage subset we surface. The cache fields mirror the Strands `Usage`
* type (dist/src/models/streaming.d.ts): the Anthropic adapter fills them from
@@ -76,6 +80,7 @@ export class MetricsCollector {
private steps = 0;
private usage: AgentUsage | undefined;
private capped = false;
+ private cappedReason: string | undefined;
private cleanups: Array<() => void> = [];
/**
@@ -92,6 +97,7 @@ export class MetricsCollector {
private readonly maxSteps?: number,
private readonly generationCallBudget?: GenerationCallBudget,
private readonly modelCallRole: GenerationModelCallRole = 'author',
+ private readonly modelCallAdmission?: GenerationModelCallAdmission,
) {}
private emit(event: KilnAgentEvent): void {
@@ -120,15 +126,31 @@ export class MetricsCollector {
const offDispatch = agent.addHook(BeforeModelCallEvent, (event) => {
if (this.maxSteps && this.maxSteps > 0 && this.steps >= this.maxSteps) {
this.capped = true;
- event.cancel = `kiln: agent step cap reached (${this.maxSteps} model calls) — aborted to bound cost`;
+ this.cappedReason = `kiln: agent step cap reached (${this.maxSteps} model calls) — aborted to bound cost`;
+ event.cancel = this.cappedReason;
return;
}
+ if (this.modelCallAdmission) {
+ const decision = this.modelCallAdmission.tryAdmit({
+ role: this.modelCallRole,
+ ...(typeof event.projectedInputTokens === 'number'
+ ? { projectedInputTokens: event.projectedInputTokens }
+ : {}),
+ });
+ if (!decision.ok) {
+ this.capped = true;
+ this.cappedReason = decision.reason;
+ event.cancel = decision.reason;
+ return;
+ }
+ }
if (this.generationCallBudget && !this.generationCallBudget.tryConsume(this.modelCallRole)) {
this.capped = true;
const receipt = this.generationCallBudget.receipt();
- event.cancel =
+ this.cappedReason =
`kiln: generation model-call budget reached (${receipt.limit} aggregate calls) — ` +
'aborted before provider dispatch to bound cost';
+ event.cancel = this.cappedReason;
return;
}
// Count admitted provider dispatches, never the SDK's synthetic after-event
@@ -144,6 +166,11 @@ export class MetricsCollector {
return this.capped;
}
+ /** Exact pre-dispatch refusal, suitable for a terminal/salvage diagnostic. */
+ capReason(): string | undefined {
+ return this.cappedReason;
+ }
+
/** Remove all attached hooks. Idempotent. */
detach(): void {
for (const off of this.cleanups) {
diff --git a/src/agent/index.ts b/src/agent/index.ts
index 263dc99a..57bd5ab0 100644
--- a/src/agent/index.ts
+++ b/src/agent/index.ts
@@ -130,6 +130,9 @@ export {
export type {
GenerationCallBudget,
GenerationCallBudgetReceipt,
+ GenerationModelCallAdmission,
+ GenerationModelCallAdmissionDecision,
+ GenerationModelCallAdmissionInput,
GenerationModelCallRole,
} from './call-budget';
diff --git a/src/agent/run.ts b/src/agent/run.ts
index c2896bfa..a1440298 100644
--- a/src/agent/run.ts
+++ b/src/agent/run.ts
@@ -52,6 +52,7 @@ import {
createGenerationCallBudget,
generationModelCallLimitFromEnv,
type GenerationCallBudget,
+ type GenerationModelCallAdmission,
type GenerationModelCallRole,
} from './call-budget';
import {
@@ -182,6 +183,9 @@ export interface RunKilnAgentOptions
gradeRefine?: 'auto' | 'off';
/** Attribution role for this invocation within the shared generation budget. */
modelCallRole?: GenerationModelCallRole;
+ /** Host-owned pre-dispatch admission. Used by quoted operations to bind
+ * provider execution to their reserved-cost envelope. */
+ modelCallAdmission?: GenerationModelCallAdmission;
}
export interface RunKilnAgentResult {
@@ -254,6 +258,7 @@ export async function runKilnAgent(opts: RunKilnAgentOptions): Promise<RunKilnAg
maxSteps,
generationCallBudget,
opts.modelCallRole ?? 'author',
+ opts.modelCallAdmission,
);
const surface = resolveToolSurface(opts.toolSurface);
const trustedCategory = opts.intent?.category ?? opts.category ?? 'prop';
@@ -444,7 +449,7 @@ export async function runKilnAgent(opts: RunKilnAgentOptions): Promise<RunKilnAg
steps: collected.steps,
...(collected.usage ? { usage: collected.usage } : {}),
...(counters ? { counters } : {}),
- error: `kiln agent exceeded ${maxSteps} model calls (step cap) — aborted to bound cost${qaNote}`,
+ error: `${metrics.capReason() ?? `kiln agent exceeded ${maxSteps} model calls (step cap) — aborted to bound cost`}${qaNote}`,
};
}
capped = true;