@stigg/agent-sdk-js 0.3.2 → 0.4.0

package/README.md

@@ -6,6 +6,9 @@ Check a customer's entitlements, credits or budget **before** a model call, mete
 actually used **after** it, and let [Stigg](https://stigg.io) handle the pricing, packaging and
 billing behind it.
 
+[![npm](https://img.shields.io/npm/v/@stigg/agent-sdk-js?color=cb3837&logo=npm)](https://www.npmjs.com/package/@stigg/agent-sdk-js)
+[![license](https://img.shields.io/badge/license-MIT-blue)](https://github.com/stiggio/stigg-agent-sdk-ts/blob/main/LICENSE)
+
 ```bash
 npm install @stigg/agent-sdk-js      # or: yarn add @stigg/agent-sdk-js
 ```
@@ -13,6 +16,23 @@ npm install @stigg/agent-sdk-js      # or: yarn add @stigg/agent-sdk-js
 Requires Node 22 or later. Ships CommonJS with type declarations, and a `./internal` subpath for
 the engine seam. Twelve providers and gateways, **and not one of them is a dependency**.
 
+## ⚡ Try it in thirty seconds
+
+No API keys. No Stigg account. Nothing to sign up for.
+
+```bash
+git clone https://github.com/stiggio/stigg-agent-sdk-ts && cd stigg-agent-sdk-ts
+corepack enable && yarn install
+yarn example-client-anthropic
+```
+
+A built-in mock stands in for both the LLM vendor and the Stigg API — and it is not a stub. The
+vendor mock speaks the real wire format, so the vendor's own SDK parses a genuine response and
+every field is populated. The Stigg mock implements real entities, budgets and hierarchy, so the
+example genuinely hits a denial and tells you which budget caused it.
+
+Add a real key to `.env` later and the same example talks to the real thing.
+
 ## 🎯 Quick start
 
 Wrap the client you already have, and keep calling it the way you already do.
@@ -99,6 +119,7 @@ rather than handing back a client that quietly meters nothing.
 | Gate without a client to wrap | `stigg.check(context)` |
 | Meter something you measured yourself | `stigg.report(context, metrics)` |
 | Give an agent its own budget | `stigg.register({ customerId, agentId, budget })` |
+| Start new customers on a plan | `stiggContext: { defaultPlanId }`, beside `customerId` |
 | Meter a gateway you operate | `client.stigg.headers()` out, `stigg.ingestFromHeaders(...)` back |
 
 One wrapped client serves every customer and every agent: the context is an argument, given once at
@@ -112,6 +133,8 @@ One wrapped client serves every customer and every agent: the context is an argu
   and no Stigg account** against a built-in mock of both
 - **[Adding a platform](.claude/skills/govern-new-platform/SKILL.md)** — provider or gateway, and
   what every binding owes
+- **[Contributing](CONTRIBUTING.md)** — how to run it locally, and how a change lands
+- **[Security](SECURITY.md)** — reporting a vulnerability privately
 
 ## 📄 License
 

package/dist/core/context.d.ts

@@ -8,6 +8,16 @@ import type { EventIngest } from '../engine/engine';
 export type StiggContext = {
     /** The tenant. Every governance call is scoped to one customer. */
     customerId?: string;
+    /**
+     * The plan a customer is provisioned onto when Stigg does not know them yet. Optional: without
+     * it, an unknown customer is not provisioned.
+     *
+     * Kept apart from {@link StiggContext.customerId} rather than folded into it, because the two
+     * are usually given in different places - the plan once at `wrap`, for every customer the
+     * client will serve, and the customer per call. A call naming a different customer inherits the
+     * client's plan.
+     */
+    defaultPlanId?: string;
     /**
      * The agent this call spends as. Travels as a dimension under
      * {@link StiggContext.attributionKey}, which is the entire mechanism by which an agent is
@@ -90,6 +100,8 @@ export type ResolvedContext = {
      * reaches the engine resolves it first, so nothing downstream has to re-check it.
      */
     customerId: string;
+    /** The plan an unknown customer is provisioned onto - undefined when none was given. */
+    defaultPlanId?: string;
     entitlement?: Entitlement;
     /** The agent folded in, so the check and the report send one object and neither re-derives it. */
     dimensions: Record<string, string>;

package/dist/core/context.js

@@ -58,6 +58,20 @@ function agentDimension(context) {
     }
     return { [context.attributionKey]: context.agentId };
 }
+/**
+ * A plan id as given, trimmed - or a refusal when it was given blank. Absent stays absent: no
+ * plan is a legal choice, while an empty one is a typo that would provision nobody onto nothing.
+ */
+function planId(value) {
+    if (value === undefined)
+        return undefined;
+    const named = typeof value === 'string' ? value.trim() : '';
+    if (!named) {
+        throw new Error('stiggContext.defaultPlanId is empty - leave the field out to provision no plan, or name the ' +
+            'plan new customers should start on.');
+    }
+    return named;
+}
 /**
  * Validates and derives, once. Everything expensive about a context happens here rather than on
  * the call path - see the note at the top of this file for why that split exists.
@@ -97,6 +111,7 @@ function resolveContext(context, correlationId,
     const dimensions = agent ? { ...context.dimensions, ...agent } : (context.dimensions ?? {});
     return {
         customerId,
+        defaultPlanId: planId(context.defaultPlanId),
         // Normalized, not passed through: `isEnforced` asks `!== undefined` while every other reader
         // asks for truthiness, so a JS caller's `entitlement: null` would be enforced by one and
         // absent to the rest - a call that runs the gate and then reports itself ungated.
@@ -120,6 +135,7 @@ function resolveContext(context, correlationId,
  */
 const CONTEXT_KEYS = {
     customerId: true,
+    defaultPlanId: true,
     agentId: true,
     attributionKey: true,
     dimensions: true,
@@ -223,6 +239,9 @@ function overrideContext(base, override) {
     }
     return {
         customerId,
+        // Independent of the customer: a call naming its own customer still provisions onto the
+        // client's plan unless it names a plan too.
+        defaultPlanId: override.defaultPlanId !== undefined ? planId(override.defaultPlanId) : base.defaultPlanId,
         entitlement,
         dimensions,
         checkedId,

package/dist/core/session.d.ts

@@ -45,6 +45,12 @@ export type SessionDeps = {
      * than disappearing.
      */
     engine: () => Promise<GovernanceEngine>;
+    /**
+     * Creates the customer on their default plan if Stigg does not know them yet. Shared across
+     * every session of one SDK and remembered per customer, so only a customer's first call pays
+     * the round trip. Absent, nothing is ever provisioned.
+     */
+    provisionCustomer?: (customerId: string, planId: string) => Promise<void>;
     logger: Logger;
     onError: (error: EngineError, context: ErrorContext) => void;
     hooks: SessionHooks;
@@ -181,6 +187,13 @@ export declare class GovernanceSession {
      * says never rejects. The failure is reported like any other.
      */
     private hook;
+    /**
+     * Makes sure a customer with a default plan exists. Never throws, and answers whether Stigg was
+     * reached - false only for an outage, which is reported here and retried by the next call. A
+     * refusal is an answer: the SDK reports it once, and the call goes on to meet whatever the check
+     * says about a customer that does not exist.
+     */
+    private provisionCustomer;
     /**
      * The last stop for a failure. `onError` is the application's own code and can throw too, and
      * there is nowhere left to report that to, so it falls back to the logger.

package/dist/core/session.js

@@ -49,6 +49,8 @@ const emptyMetricNameError = () => new errors_1.EngineError('measure', 'a metric
  * `'async'` report would reach the event API with no name at all.
  */
 const DEFAULT_EVENT_NAME = 'agent.usage';
+/** How both engines say a check found no such customer - the reason, verbatim, from the API. */
+const CUSTOMER_NOT_FOUND = 'CustomerNotFound';
 class GovernanceSession {
     deps;
     pending = new Set();
@@ -93,6 +95,8 @@ class GovernanceSession {
      * applies the error policy.
      */
     async warmUp(context) {
+        // First, so the cache below loads a customer that exists rather than remembering one that did not.
+        await this.provisionCustomer(context);
         if (!(0, context_1.isEnforced)(context))
             return;
         try {
@@ -116,11 +120,22 @@ class GovernanceSession {
             return this.record((0, decision_1.unenforcedDecision)(), context);
         try {
             const engine = await this.deps.engine();
+            // Before the check, not after: a customer Stigg has never seen holds no entitlement, so their
+            // first call would be refused for not existing yet.
+            const reached = await this.provisionCustomer(context);
             const result = await engine.check(context.customerId, {
                 entitlement,
                 requestedUsage,
                 dimensions: context.dimensions,
             });
+            // The policy answers only when both halves say so: Stigg could not be reached to create the
+            // customer, and the check then found no customer. Either alone is not that. An existing
+            // customer gets the real answer whatever happened to the create, and a customer Stigg
+            // refused - an unknown plan, an archived customer - is refused here too, rather than
+            // waved through by an `allow` that exists for outages, not for configuration mistakes.
+            if (!reached && result.accessDeniedReason === CUSTOMER_NOT_FOUND) {
+                return this.record((0, decision_1.policyDecision)(context.checkErrorAction === 'allow'), context);
+            }
             return this.record((0, decision_1.toDecision)(result, { customerId: context.customerId, entitlement: context.entitlement }), context);
         }
         catch (err) {
@@ -253,17 +268,21 @@ class GovernanceSession {
         }
         const promise = this.deps
             .engine()
-            .then((engine) => engine.report(context.customerId, {
-            metrics: sendable,
-            entitlement: context.entitlement,
-            mode,
-            // Flattened here rather than in the engine, so both transports send the same event and a
-            // sync report pays nothing for a field it will not use.
-            raw: mode === 'async' ? (0, dimensions_1.flattenRaw)(raw) : undefined,
-            dimensions,
-            idempotencyKey,
-            event: event ?? { name: DEFAULT_EVENT_NAME },
-        }))
+            .then(async (engine) => {
+            // A metering-only client never checks, so this is the first place its customer is seen.
+            await this.provisionCustomer(context);
+            return engine.report(context.customerId, {
+                metrics: sendable,
+                entitlement: context.entitlement,
+                mode,
+                // Flattened here rather than in the engine, so both transports send the same event and a
+                // sync report pays nothing for a field it will not use.
+                raw: mode === 'async' ? (0, dimensions_1.flattenRaw)(raw) : undefined,
+                dimensions,
+                idempotencyKey,
+                event: event ?? { name: DEFAULT_EVENT_NAME },
+            });
+        })
             .then((result) => {
             this.ingested += 1;
             // A replay is a delivery that consumed nothing - the server had already counted these
@@ -397,6 +416,24 @@ class GovernanceSession {
     hook(name, context, invoke) {
         (0, hooks_1.safely)(invoke, (err) => this.reportError(asEngineError(name, err), name, context));
     }
+    /**
+     * Makes sure a customer with a default plan exists. Never throws, and answers whether Stigg was
+     * reached - false only for an outage, which is reported here and retried by the next call. A
+     * refusal is an answer: the SDK reports it once, and the call goes on to meet whatever the check
+     * says about a customer that does not exist.
+     */
+    async provisionCustomer(context) {
+        if (!context.defaultPlanId || !context.customerId || !this.deps.provisionCustomer)
+            return true;
+        try {
+            await this.deps.provisionCustomer(context.customerId, context.defaultPlanId);
+            return true;
+        }
+        catch (err) {
+            this.reportError(asEngineError('provisionCustomer', err), 'provisionCustomer', context);
+            return false;
+        }
+    }
     /**
      * The last stop for a failure. `onError` is the application's own code and can throw too, and
      * there is nowhere left to report that to, so it falls back to the logger.

package/dist/engine/composite-engine.d.ts

@@ -1,5 +1,5 @@
 import type { Logger } from '../logger';
-import type { EngineCapabilities, EngineCheckParams, EngineCheckResult, EngineReportParams, EngineReportResult, EngineResolution, EntityInput, EntityPlacement, GovernanceEngine } from './engine';
+import type { EngineCapabilities, EngineCheckParams, EngineCheckResult, EngineReportParams, EngineReportResult, EngineResolution, EntityInput, EntityPlacement, GovernanceEngine, ProvisionOutcome } from './engine';
 export type CompositeDelegates = {
     upsertEntity?: GovernanceEngine;
     check: GovernanceEngine;
@@ -11,6 +11,11 @@ export type CompositeDelegates = {
     unattributedCheck?: GovernanceEngine;
     report: GovernanceEngine;
     archiveEntity?: GovernanceEngine;
+    /**
+     * Creates customers on their default plan. The Node SDK, so the plan it answers with lands in
+     * the cache the next check reads. A customer API, so it needs no governance.
+     */
+    provisionCustomer?: GovernanceEngine;
 };
 /**
  * Whether this check is about an entity at all.
@@ -47,6 +52,7 @@ export declare class CompositeEngine implements GovernanceEngine {
     constructor(deps: CompositeDeps);
     upsertEntity(customerId: string, entity: EntityInput, placement?: EntityPlacement): Promise<void>;
     archiveEntity(customerId: string, entityId: string): Promise<void>;
+    provisionCustomer(customerId: string, planId: string): Promise<ProvisionOutcome>;
     check(customerId: string, params: EngineCheckParams): Promise<EngineCheckResult>;
     report(customerId: string, params: EngineReportParams): Promise<EngineReportResult>;
     /**

package/dist/engine/composite-engine.js

@@ -70,6 +70,15 @@ class CompositeEngine {
     async archiveEntity(customerId, entityId) {
         await this.run('archiveEntity', this.provisioner(), (engine) => engine.archiveEntity(customerId, entityId));
     }
+    async provisionCustomer(customerId, planId) {
+        const delegate = this.delegates.provisionCustomer;
+        if (!delegate?.provisionCustomer) {
+            throw new errors_2.EngineError('provisionCustomer', 'no client here can create customers.');
+        }
+        // Not through `run()`: its fallback is REST, which does not provision customers, so there is
+        // nothing to re-route to - an unreachable Node SDK fails here and the call's own check decides.
+        return delegate.provisionCustomer(customerId, planId);
+    }
     async check(customerId, params) {
         const delegate = (0, exports.isAttributed)(params)
             ? this.delegates.check

package/dist/engine/create-engine.js

@@ -61,7 +61,7 @@ async function createGovernanceEngine(config) {
         const resolution = customerLevel('governance not enabled for this account');
         return {
             engine: new composite_engine_1.CompositeEngine({
-                delegates: { check: nodeSdk, report: nodeSdk },
+                delegates: { check: nodeSdk, report: nodeSdk, provisionCustomer: nodeSdk },
                 fallback: rest,
                 resolution,
                 logger: config.logger,
@@ -78,7 +78,14 @@ async function createGovernanceEngine(config) {
         engine: new composite_engine_1.CompositeEngine({
             // An attributed check goes to REST because only it returns chains; an unattributed one has
             // no chain to lose, and ingest prefers the cached SDK either way.
-            delegates: { upsertEntity: rest, check: rest, unattributedCheck: nodeSdk, report: nodeSdk, archiveEntity: rest },
+            delegates: {
+                upsertEntity: rest,
+                check: rest,
+                unattributedCheck: nodeSdk,
+                report: nodeSdk,
+                archiveEntity: rest,
+                provisionCustomer: nodeSdk,
+            },
             fallback: rest,
             resolution,
             logger: config.logger,

package/dist/engine/engine.d.ts

@@ -133,12 +133,40 @@ export type EntityInput = {
     displayName?: string;
     metadata?: Record<string, string>;
 };
+/** What provisioning a customer came to. Every variant is an answer from Stigg. */
+export type ProvisionOutcome = {
+    status: 'created';
+    /** How the server chose the first subscription - `REQUESTED_PLAN` when it took ours. */
+    decision: string;
+    /** The plan the customer actually landed on, if they landed on one. */
+    planId?: string;
+} | {
+    status: 'existing';
+}
+/** Refused, for a reason a retry would not change: an unknown plan, a key that cannot write. */
+ | {
+    status: 'rejected';
+    reason: string;
+    code?: string;
+};
 export interface GovernanceEngine {
     readonly capabilities: EngineCapabilities;
     upsertEntity(customerId: string, entity: EntityInput, placement?: EntityPlacement): Promise<void>;
     check(customerId: string, params: EngineCheckParams): Promise<EngineCheckResult>;
     report(customerId: string, params: EngineReportParams): Promise<EngineReportResult>;
     archiveEntity(customerId: string, entityId: string): Promise<void>;
+    /**
+     * Creates the customer on `planId` when Stigg does not know them yet, and does nothing when it
+     * does. `existing` is the common answer, and it leaves the customer's subscriptions alone: a
+     * default plan is where a new customer starts, never something an existing one is moved onto.
+     *
+     * Resolves for every answer Stigg gave - including `rejected`, a request it refused - and
+     * throws only when Stigg could not be reached, which is the one failure worth trying again.
+     *
+     * Optional: an engine with no customer API cannot provision, and the caller treats its absence
+     * as having nothing to do.
+     */
+    provisionCustomer?(customerId: string, planId: string): Promise<ProvisionOutcome>;
     /**
      * Loads whatever state this engine caches for a customer, so the checks that follow are local.
      *

package/dist/engine/node-sdk-engine.d.ts

@@ -13,7 +13,7 @@
  * configuration passed straight through rather than re-described here.
  */
 import Stigg, { type ClientConfiguration } from '@stigg/node-server-sdk';
-import type { EngineCapabilities, EngineCheckParams, EngineCheckResult, EngineReportParams, EngineReportResult, GovernanceEngine } from './engine';
+import type { EngineCapabilities, EngineCheckParams, EngineCheckResult, EngineReportParams, EngineReportResult, GovernanceEngine, ProvisionOutcome } from './engine';
 /**
  * Caching - all of it, and none of it implemented here.
  *
@@ -84,6 +84,21 @@ export declare class NodeSdkEngine implements GovernanceEngine {
      * amount happened to warm it.
      */
     preload(customerId: string): Promise<void>;
+    /**
+     * One mutation, no lookup first. Stigg refuses to provision a customer it already has - the
+     * whole mutation, subscription included - so an existing customer comes back as a duplicate and
+     * is left exactly as they were. Reading first would only add a round trip to every customer's
+     * first call in each process, to learn what the create already says.
+     *
+     * Here rather than on REST because the Node SDK creates the customer and the subscription in one
+     * mutation, and writes the entitlements it answers with straight into the cache - so the check
+     * that follows reads the new plan locally instead of fetching it.
+     *
+     * Throws only when Stigg did not answer. Any answer - created, duplicate, or refused - resolves,
+     * because the caller treats them differently: a refusal will be the same next time, and an
+     * unreachable server may not.
+     */
+    provisionCustomer(customerId: string, planId: string): Promise<ProvisionOutcome>;
     upsertEntity(): Promise<void>;
     archiveEntity(): Promise<void>;
     /**

package/dist/engine/node-sdk-engine.js

@@ -52,6 +52,11 @@ const node_server_sdk_1 = __importStar(require("@stigg/node-server-sdk"));
 const errors_1 = require("../errors");
 const sdk_identity_1 = require("../sdk-identity");
 const report_1 = require("./report");
+/**
+ * The API's own code for an error it answered with. Absent when nothing answered - a refused
+ * connection, a dropped socket - which is what tells a refusal apart from an outage.
+ */
+const errorCode = (err) => err?.errorCode;
 const LOCAL_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '[::1]']);
 /**
  * Drops keys that were never set, so a spread cannot un-set a default.
@@ -133,6 +138,39 @@ class NodeSdkEngine {
     async preload(customerId) {
         await this.client.reloadEntitlements(customerId);
     }
+    /**
+     * One mutation, no lookup first. Stigg refuses to provision a customer it already has - the
+     * whole mutation, subscription included - so an existing customer comes back as a duplicate and
+     * is left exactly as they were. Reading first would only add a round trip to every customer's
+     * first call in each process, to learn what the create already says.
+     *
+     * Here rather than on REST because the Node SDK creates the customer and the subscription in one
+     * mutation, and writes the entitlements it answers with straight into the cache - so the check
+     * that follows reads the new plan locally instead of fetching it.
+     *
+     * Throws only when Stigg did not answer. Any answer - created, duplicate, or refused - resolves,
+     * because the caller treats them differently: a refusal will be the same next time, and an
+     * unreachable server may not.
+     */
+    async provisionCustomer(customerId, planId) {
+        try {
+            const provisioned = await this.client.provisionCustomer({ customerId, subscriptionParams: { planId } });
+            return {
+                status: 'created',
+                decision: provisioned.subscriptionDecisionStrategy,
+                planId: provisioned.subscription?.planId,
+            };
+        }
+        catch (err) {
+            const code = errorCode(err);
+            if (code === 'DuplicatedEntityNotAllowed')
+                return { status: 'existing' };
+            if (code && code !== 'RequestTimeout') {
+                return { status: 'rejected', code, reason: err instanceof Error ? err.message : String(err) };
+            }
+            throw (0, errors_1.asEngineError)('provisionCustomer', err);
+        }
+    }
     async upsertEntity() {
         throw new errors_1.GovernanceNotEnabledError('The Node server SDK has no governance surface; entities need the REST client.');
     }

package/dist/stigg-agent-sdk.d.ts

@@ -159,6 +159,18 @@ export declare class StiggAgentSDK {
      * rather than once each. Only the memoized path is shared - see `register`.
      */
     private readonly registering;
+    /**
+     * Customers this process has provisioned, by id - settled or still in flight. Shared by every
+     * client, so a customer seen by ten wrapped clients is provisioned once.
+     *
+     * A refusal is remembered like a success: an unknown plan or a key that cannot write will be
+     * refused the same way next time, and retrying it would spend a rate-limited call on every call.
+     * Only an unreachable Stigg is forgotten, so the customer's next call tries again.
+     *
+     * Capped at {@link KNOWN_CUSTOMERS_CAP}, oldest first. Forgetting a customer costs one more
+     * provisioning call, which Stigg answers as a duplicate - so the cap bounds memory, not safety.
+     */
+    private readonly customers;
     private started?;
     /**
      * When the attempt currently in `started` rejected, or undefined while it is pending or has
@@ -254,6 +266,18 @@ export declare class StiggAgentSDK {
      */
     private get contextDefaults();
     private newSession;
+    /**
+     * Creates the customer on `planId` the first time this process sees them, if Stigg does not
+     * already know them. Keyed by customer alone: once one exists, which plan a later call names
+     * is irrelevant - an existing customer is never moved.
+     */
+    private provisionCustomer;
+    /**
+     * The server picks the first subscription, and the plan asked for is only a request: a
+     * predefined free or trial plan can win, or no subscription may be created at all. Logging
+     * success regardless would hide a customer who landed somewhere nobody chose.
+     */
+    private describeProvisioned;
     /** The session the no-client paths share, built on first use so an unused SDK builds none. */
     private standalone;
     /**

package/dist/stigg-agent-sdk.js

@@ -120,6 +120,11 @@ const DEFAULT_WALLET = { currencyId: 'credits' };
  * for why remembering it at all is the point.
  */
 const RETRY_START_AFTER_MS = 2_000;
+/**
+ * How many customers one process remembers having provisioned. A server serving an open-ended set
+ * of tenants would otherwise grow this for as long as it runs.
+ */
+const KNOWN_CUSTOMERS_CAP = 10_000;
 /** The key shorthand and the options object, folded into the one object the config takes. */
 function toOptions(first, second) {
     return typeof first === 'string' ? { ...second, apiKey: first } : { ...first, ...second };
@@ -184,6 +189,18 @@ class StiggAgentSDK {
      * rather than once each. Only the memoized path is shared - see `register`.
      */
     registering = new Map();
+    /**
+     * Customers this process has provisioned, by id - settled or still in flight. Shared by every
+     * client, so a customer seen by ten wrapped clients is provisioned once.
+     *
+     * A refusal is remembered like a success: an unknown plan or a key that cannot write will be
+     * refused the same way next time, and retrying it would spend a rate-limited call on every call.
+     * Only an unreachable Stigg is forgotten, so the customer's next call tries again.
+     *
+     * Capped at {@link KNOWN_CUSTOMERS_CAP}, oldest first. Forgetting a customer costs one more
+     * provisioning call, which Stigg answers as a duplicate - so the cap bounds memory, not safety.
+     */
+    customers = new Map();
     started;
     /**
      * When the attempt currently in `started` rejected, or undefined while it is pending or has
@@ -443,6 +460,7 @@ class StiggAgentSDK {
     newSession(hooks) {
         const session = new session_1.GovernanceSession({
             engine: () => this.ensureStarted().then((state) => state.engine),
+            provisionCustomer: (customerId, planId) => this.provisionCustomer(customerId, planId),
             logger: this.config.logger,
             onError: this.config.onError,
             hooks: hooks ?? {},
@@ -450,6 +468,52 @@ class StiggAgentSDK {
         this.sessions.add(session);
         return session;
     }
+    /**
+     * Creates the customer on `planId` the first time this process sees them, if Stigg does not
+     * already know them. Keyed by customer alone: once one exists, which plan a later call names
+     * is irrelevant - an existing customer is never moved.
+     */
+    provisionCustomer(customerId, planId) {
+        const known = this.customers.get(customerId);
+        if (known)
+            return known;
+        const pending = this.ensureStarted().then(async ({ engine }) => {
+            const outcome = await engine.provisionCustomer?.(customerId, planId);
+            if (outcome?.status === 'created')
+                this.describeProvisioned(customerId, planId, outcome);
+            // Said once, here, rather than by every call that follows: the memo keeps the refusal, so
+            // later calls go straight to the check, which answers for a customer that does not exist.
+            if (outcome?.status === 'rejected') {
+                const error = new errors_1.EngineError('provisionCustomer', `Stigg refused to provision customer ${customerId} on plan ${planId}, and will not be ` +
+                    `asked again by this process: ${outcome.reason}`);
+                (0, hooks_1.safely)(() => this.config.onError(error, { operation: 'provisionCustomer', customerId }), (reportErr) => this.config.logger.warn(`[stigg] onError threw while reporting ${error.message}: ${String(reportErr)}`));
+            }
+        });
+        this.customers.set(customerId, pending);
+        if (this.customers.size > KNOWN_CUSTOMERS_CAP) {
+            this.customers.delete(this.customers.keys().next().value);
+        }
+        // Only its own entry: one evicted by the cap may have been replaced by a newer attempt for the
+        // same customer by the time it fails, and deleting that one would re-ask a settled customer.
+        pending.catch(() => {
+            if (this.customers.get(customerId) === pending)
+                this.customers.delete(customerId);
+        });
+        return pending;
+    }
+    /**
+     * The server picks the first subscription, and the plan asked for is only a request: a
+     * predefined free or trial plan can win, or no subscription may be created at all. Logging
+     * success regardless would hide a customer who landed somewhere nobody chose.
+     */
+    describeProvisioned(customerId, planId, outcome) {
+        if (outcome.decision === 'REQUESTED_PLAN' && outcome.planId === planId) {
+            this.config.logger.info(`[stigg] customer ${customerId} provisioned on plan ${planId}`);
+            return;
+        }
+        this.config.logger.warn(`[stigg] customer ${customerId} was created, but not on plan ${planId}: Stigg chose ` +
+            `${outcome.decision}, and the customer is on ${outcome.planId ?? 'no plan'}.`);
+    }
     /** The session the no-client paths share, built on first use so an unused SDK builds none. */
     standalone() {
         this.loose ??= this.newSession();

package/package.json

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