@stigg/agent-sdk-js 0.7.5 → 0.7.6

package/dist/engine/engine.d.ts

@@ -122,9 +122,14 @@ export type EntityPlacement = {
     /**
      * Set the budget only when the assignment does not exist yet. An existing one keeps its limit
      * and cadence, so a raise made in the dashboard survives the next run. Mutually exclusive with
-     * `usageLimit` - it costs one extra read, which is why it is not the default.
+     * `usageLimit` - it costs one extra read, which is why a number is never seeded unless asked for.
+     *
+     * `null` seeds an unlimited assignment - the metering-only one, which puts the agent in the tree
+     * and tracks its usage without its own assignment refusing it. It is what a budget with no limit
+     * sends, so that case pays the read on every call. Unlike a numeric seed it still applies the
+     * caller's `cadence` to an existing assignment, as a budget with no limit always has.
      */
-    usageLimitOnCreate?: number;
+    usageLimitOnCreate?: number | null;
     cadence?: string;
     /** The entities the budget is scoped to - its own assignment beside the agent's whole one. */
     scopeEntityIds?: string[];

package/dist/engine/rest-governance-engine.js

@@ -16,6 +16,8 @@ const errors_1 = require("../errors");
 const types_1 = require("../types");
 const sdk_identity_1 = require("../sdk-identity");
 const report_1 = require("./report");
+/** The window an unlimited assignment is created with when the caller named none. */
+const TRACKING_CADENCE = 'P1M';
 /** The governance check endpoint is `/api/v1-beta/` and flagged experimental. */
 class RestGovernanceEngine {
     /**
@@ -116,11 +118,16 @@ class RestGovernanceEngine {
         const scope = scopeOf(placement.scopeEntityIds);
         // Every page: the one with this scope can sit past the first, and missing it would overwrite
         // an admin's limit with the seed.
+        const tracking = placement.usageLimitOnCreate === null;
         for await (const row of this.client.v1Beta.customers.assignments.list(customerId, { entityId, ...capability })) {
-            // Already assigned: leave the limit and its window exactly as they are.
+            // Already assigned: leave the limit and its window exactly as they are - except that a
+            // metering-only call still moves the window it named, as a budget with no limit always did.
             if (scopeOf(row.scopeEntityIds) === scope)
-                return {};
+                return tracking ? cadence : {};
         }
+        // Governance requires a window on create, and a metering-only caller has no reason to pick one.
+        if (tracking)
+            return { usageLimit: null, cadence: placement.cadence ?? TRACKING_CADENCE };
         return { usageLimit: placement.usageLimitOnCreate, ...cadence };
     }
     async check(customerId, { entitlement, requestedUsage, dimensions }) {

package/dist/stigg-agent-sdk.js

@@ -152,7 +152,8 @@ function toPlacement(input) {
     if (onCreate && typeof input.budget.limit !== 'number') {
         throw new Error(`Agent ${input.agentId} asked to seed a budget with no limit to seed. ` +
             "`budget.apply: 'on-create'` writes a cap the first time and never again, so there is " +
-            'nothing to write without `budget.limit`.');
+            'nothing to write without `budget.limit`. To seed an unlimited, metering-only budget, ' +
+            'leave out both `limit` and `apply`.');
     }
     // Each entry names an entity, and a blank one names none: the budget would be scoped to an
     // entity no request resolves, and apply to nothing.
@@ -160,12 +161,15 @@ function toPlacement(input) {
         throw new Error(`Agent ${input.agentId} has a budget.scope that is not a list of entity ids: ${JSON.stringify(scope)}. ` +
             'Leave it out, or pass [], for the whole budget.');
     }
+    // No limit at all is metering only: an agent with no assignment is in nobody's tree and its usage
+    // is counted against nothing, so it gets an unlimited one - seeded, so a cap set later survives.
+    const tracking = !onCreate && input.budget.limit === undefined;
     return {
         parentId,
         entitlement,
         cadence,
         usageLimit: onCreate ? undefined : input.budget.limit,
-        usageLimitOnCreate: onCreate ? (input.budget.limit ?? undefined) : undefined,
+        usageLimitOnCreate: tracking ? null : onCreate ? (input.budget.limit ?? undefined) : undefined,
         scopeEntityIds: scope?.length ? scope : undefined,
     };
 }

package/dist/types.d.ts

@@ -509,10 +509,21 @@ export type AgentBudget = {
      * A scoped budget governs only the requests it names: one naming no model, or a model with no
      * budget, is limited by the agent's whole budget and its ancestors' alone - with neither, by
      * nothing. Register the whole budget too.
+     *
+     * A scope with no `limit` meters that scope only: it is created unlimited, like a whole budget
+     * with no limit, so it shows that scope's usage and refuses nothing.
      */
     scope?: string[];
 } & ({
-    /** The limit, written on every call. `null` clears whatever is assigned. */
+    /**
+     * The limit, written on every call. `null` clears whatever is assigned.
+     *
+     * Omitted, the agent is metering only: the first call creates an unlimited assignment, so its
+     * usage is tracked in the governance tree and its own assignment never refuses it - its
+     * ancestors' budgets and the customer's entitlement still can. Later calls leave the limit
+     * assigned by then - a cap set in the dashboard included - untouched, though a `cadence` they
+     * pass is still applied. `cadence` defaults to `'P1M'` on that create.
+     */
     limit?: number | null;
     /** Writes the limit every time. The default. */
     apply?: 'always';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stigg/agent-sdk-js",
-  "version": "0.7.5",
+  "version": "0.7.6",
   "description": "Stigg agent SDK (JS) - run-lifecycle governance for agentic stacks, with examples per layer",
   "main": "dist/index.js",
   "typings": "dist/index.d.ts",