@stigg/agent-sdk-js 0.0.0-stage → 0.1.0

package/dist/types.js

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unitsPerTokens = exports.wholeUnitsForGovernance = exports.toMeasurement = exports.vendorMetrics = exports.emptyTokenUsage = exports.entitlementRef = exports.entitlementKind = exports.entitlementId = void 0;
+exports.entitlementError = entitlementError;
+exports.usageValueError = usageValueError;
+/**
+ * The vocabulary shared by the core, the engines and every binding, and the argument list of
+ * every call on the public surface.
+ *
+ * Terms follow Stigg governance rather than the draft design notes: provision/archive (not
+ * register/de-register), ingest (not report), assignment (not budget), dimensions (not tags).
+ *
+ * The imports below are all `import type`, so they are erased at compile time: this file pulls in
+ * no module at runtime and stays the leaf everything else can depend on.
+ */
+const errors_1 = require("./errors");
+/** The id to send as `featureId`/`currencyId`, whichever kind the entitlement is. */
+const entitlementId = (entitlement) => entitlement.currencyId ?? entitlement.featureId;
+exports.entitlementId = entitlementId;
+/** 'credit' targets read the customer's credit pool; 'feature' targets need an entitling subscription. */
+const entitlementKind = (entitlement) => entitlement.currencyId ? 'credit' : 'feature';
+exports.entitlementKind = entitlementKind;
+/**
+ * The entitlement as every Stigg endpoint takes it: one of two mutually exclusive id fields,
+ * ready to spread.
+ *
+ * ```ts
+ * await client.v1Beta.customers.entitlements.check(customerId, { ...entitlementRef(entitlement), requestedUsage });
+ * ```
+ *
+ * Narrowing on the property rather than through {@link entitlementKind} is the point: a function
+ * call cannot narrow a union, so every hand-written version of this needed a `!` on each branch -
+ * an assertion that the union already guarantees and that would survive the union changing.
+ */
+const entitlementRef = (entitlement) => entitlement.currencyId !== undefined ? { currencyId: entitlement.currencyId } : { featureId: entitlement.featureId };
+exports.entitlementRef = entitlementRef;
+/**
+ * Why an entitlement cannot be billed against, if one was named at all.
+ *
+ * Naming none is legal: it is how a caller asks for metering without enforcement, so undefined is
+ * not an error here. The one place an entitlement is genuinely required is an assignment, which is
+ * written over `(entity x entitlement)` - and `register` refuses that case itself, because only it
+ * knows the agent to name in the message.
+ *
+ * What stays refused is an entitlement that is named and names nothing. The union permits
+ * `{ currencyId: '' }`, and an empty currency is falsy - so it classifies as a feature and every
+ * branch downstream then asks for a `featureId` that is not there. An empty id is a typo rather
+ * than an intention, and letting it through meters a run against nothing while it still looks
+ * enforced.
+ */
+function entitlementError(entitlement) {
+    if (!entitlement)
+        return undefined;
+    if ((0, exports.entitlementId)(entitlement)?.trim())
+        return undefined;
+    return new Error('a run needs a non-empty currencyId or featureId - an empty one bills against nothing.');
+}
+const emptyTokenUsage = () => ({ input: 0, output: 0, cacheRead: 0, cacheCreate: 0 });
+exports.emptyTokenUsage = emptyTokenUsage;
+/** What a run reports when nobody says otherwise: exactly what the vendor stated. */
+const vendorMetrics = (measurement) => measurement.metrics ?? {};
+exports.vendorMetrics = vendorMetrics;
+/** A binding may report either shape; `TokenUsage` is the common case and stays terse. */
+const toMeasurement = (value) => 'input' in value ? { usage: value } : value;
+exports.toMeasurement = toMeasurement;
+/**
+ * The amount to report when this run is attributed to a governance entity.
+ *
+ * Governance counts in whole units and cannot be made to count otherwise from here: its ingest
+ * schema is `z.number().int()`, and the counter behind it is a Redis `HINCRBY`, which takes an
+ * integer delta. A fractional amount is rejected at that boundary - the wallet still moves, the
+ * per-entity counter does not, and nothing in the response says so. An agent's budget silently
+ * stops advancing while its spend carries on.
+ *
+ * So an attributed run rounds up, and only an attributed run: a run that names no entity reports
+ * what its mapper produced, because the wallet takes fractions and nothing downstream of it
+ * counts in whole units.
+ *
+ * Rounding *up* rather than to nearest, because a call that happened must cost something: at any
+ * sane denomination most calls are worth less than one unit, and rounding to nearest would bill
+ * nothing for nearly all of them.
+ *
+ * TODO: delete this, and the call sites that use it, once governance counts fractional usage.
+ * The platform fix is to scale internally - store micro-units and accept fractions at the API
+ * boundary - which keeps `HINCRBY` working and is the only way an agent budget can be
+ * denominated finely enough to price a call worth a tenth of a cent. Until then this is a
+ * deliberate overcharge on small calls, which is why it is announced rather than silent.
+ */
+const wholeUnitsForGovernance = (value) => Math.ceil(value);
+exports.wholeUnitsForGovernance = wholeUnitsForGovernance;
+/**
+ * Why a measured value cannot be reported, if it cannot.
+ *
+ * Zero is not an error - a cached refusal or an empty stream is a normal turn - but a mapper
+ * dividing by an unset config returns NaN or Infinity, and reading those as "nothing was used"
+ * meters the run at zero while every call still reports success. Those are refused everywhere.
+ *
+ * A fraction is refused on one path only, and the rule is the endpoint's rather than this SDK's:
+ *
+ * - **The wallet** takes them. `credits.consumption.consume` and its async twin accept a
+ *   fractional `amount`, and balances are fractional too - which they have to be, or a currency
+ *   could never be denominated finely enough to price a call worth a tenth of a cent.
+ * - **An event** takes them. The number rides as a dimension and a meter sums what it finds,
+ *   which is the only way a gateway's `cost` reports honestly.
+ * - **The usage report** does not: `POST /api/v1/usage` answers
+ *   `400 Expected integer, received float`. That is the one case refused here, where the caller
+ *   can still see which metric it was - metering failures are swallowed into `onError`, so a 400
+ *   three frames down is a silent gap rather than an error anyone reads.
+ *
+ * Shared, because every path that reports usage has to answer this the same way.
+ */
+function usageValueError(value, mode = 'sync', 
+// Whether this metric draws the credit wallet rather than reporting a feature. The wallet takes
+// fractions in both modes, so what the ingest mode decides does not apply to it.
+drawsWallet = false) {
+    if (!Number.isFinite(value) || value < 0) {
+        return new errors_1.EngineError('ingest', `usage value must be a finite non-negative number, got ${value}`);
+    }
+    if (mode === 'async' || drawsWallet || Number.isInteger(value))
+        return undefined;
+    return new errors_1.EngineError('ingest', `usage value must be a whole number to report against a feature, got ${value}. The usage ` +
+        'report takes integers; a credit currency takes fractions, and so does an event under ' +
+        "`ingest: 'async'`.");
+}
+/**
+ * One metric, summed from every token class and divided by the unit size.
+ *
+ * The mapper for an application that prices tokens itself. Named for what it produces - units
+ * under an id - rather than for credits, because it does not deduct any: it reports a number, and
+ * that number draws the wallet only when the id happens to name a credit currency. Which it is
+ * decides the whole ingest path, so a mapper that claimed to know was the wrong place to look.
+ *
+ * **Prefer reporting the raw counters and converting in Stigg.** A consumption mapping on the plan
+ * does the same arithmetic where a pricing change does not need a deploy, and it is the only place
+ * that can weight cache reads cheaper. Reach for this when the application deliberately prices
+ * itself.
+ *
+ * The division is reported as it comes out. A credit currency takes fractions, so a call worth
+ * four fifths of a unit costs four fifths of one - rounding it up here would be this SDK's
+ * arithmetic on someone else's price. A **feature** is the exception: `POST /api/v1/usage` takes
+ * integers, so pick a `tokensPerUnit` that divides, or round in your own mapper.
+ *
+ * @param id The Stigg feature id or credit currency id to report under.
+ * @param tokensPerUnit How many tokens make one unit.
+ */
+const unitsPerTokens = (id, tokensPerUnit = 1) => ({ usage }) => usage ? { [id]: (usage.input + usage.output + usage.cacheRead + usage.cacheCreate) / tokensPerUnit } : {};
+exports.unitsPerTokens = unitsPerTokens;

package/package.json

@@ -1,6 +1,92 @@
 {
   "name": "@stigg/agent-sdk-js",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.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",
+  "publishConfig": {
+    "access": "public",
+    "main": "dist/index.js",
+    "typings": "dist/index.d.ts",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "./internal": {
+        "types": "./dist/internal.d.ts",
+        "default": "./dist/internal.js"
+      },
+      "./package.json": "./package.json"
+    }
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/stiggio/stigg-sdk.git",
+    "directory": "packages/agent-sdk/agent-sdk-js"
+  },
+  "scripts": {
+    "build": "rm -rf dist && yarn run -T tsc -p tsconfig.json --noEmit && yarn run -T tsc -p tsconfig.build.json",
+    "lint": "yarn run -T eslint \"{src,examples,test,testing}/**/*.ts\"",
+    "test": "tsx --test test/*.test.ts",
+    "example-setup": "tsx examples/shared/setup-governance.ts",
+    "example-client": "tsx examples/client/anthropic.ts",
+    "example-client-anthropic": "tsx examples/client/anthropic.ts",
+    "example-client-openai": "tsx examples/client/openai.ts",
+    "example-client-gemini": "tsx examples/client/gemini.ts",
+    "example-client-groq": "tsx examples/client/groq.ts",
+    "example-client-mistral": "tsx examples/client/mistral.ts",
+    "example-client-ollama": "tsx examples/client/ollama.ts",
+    "example-client-openrouter": "tsx examples/client/openrouter.ts",
+    "example-client-litellm": "tsx examples/client/litellm.ts",
+    "example-client-typesafe": "tsx examples/client/typesafe.ts",
+    "example-two-agents": "tsx examples/client/two-agents.ts",
+    "example-gateway": "tsx examples/gateway/openrouter.ts",
+    "example-gateway-openrouter": "tsx examples/gateway/openrouter.ts",
+    "example-gateway-litellm": "tsx examples/gateway/litellm.ts",
+    "example-gateway-bedrock": "tsx examples/gateway/bedrock.ts"
+  },
+  "nx": {
+    "includedScripts": [
+      "build",
+      "lint",
+      "test"
+    ]
+  },
+  "files": [
+    "dist/**/*"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@stigg/node-server-sdk": "6.1.0",
+    "@stigg/typescript": "0.1.0-beta.55",
+    "zod": "^4.6.1"
+  },
+  "devDependencies": {
+    "@anthropic-ai/sdk": "^0.124.0",
+    "@aws-sdk/client-bedrock-runtime": "^3.1150.0",
+    "@google/genai": "^2.28.0",
+    "@mistralai/mistralai": "^2.7.0",
+    "@openrouter/sdk": "^1.4.25",
+    "@typesafe-ai/sdk": "^0.6.0",
+    "dotenv": "^17.4.2",
+    "groq-sdk": "^1.6.0",
+    "ollama": "^0.6.4",
+    "openai": "^7.13.0",
+    "tsx": "^4.23.13"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./internal": {
+      "types": "./dist/internal.d.ts",
+      "default": "./dist/internal.js"
+    },
+    "./package.json": "./package.json"
+  }
 }