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.
JavaScript 3d3d-assets3d-modelingagent-skillsagent-toolsai-agentsasset-pipelinecligame-assetsglbgltfmcpmcp-servermodel-context-protocolprocedural-generationprocedural-modelingtext-to-3dthreejstypescript
feat: add host model-call cost admission (#39)
Matthew Kissinger65b9fe435970
diff --git a/src/agent/call-budget.ts b/src/agent/call-budget.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 RunKilnAgentOptionsgradeRefine?: '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<RunKilnAgmaxSteps,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<RunKilnAgsteps: 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;