@aaes-ai/govern-sdk 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+## 0.2.0 (2026-10-22, prepared and tagged, not published)
+
+Breaking changes (hence 0.2.0 under the SDK release policy):
+
+- An omitted daemon spend cap now reads as `spendCapMinor: null` with `spendCapMinorPresent: false` on grants, presented grants and federated grants and scopes. 0.1.3 reported an omitted cap as `0`, which could not be told apart from an explicit zero cap. An explicit zero stays `0` with `spendCapMinorPresent: true`. The declarations now type the field as `number | null`.
+- `action()` refuses before sending when the capability has no published risk tier for the caller, and asks the caller to refresh capabilities or request access. 0.1.3 sent such a request without a tier.
+- Read filters accept `limit: 0`, which means the daemon default, as omitting `limit` does.
+
+Fixes:
+
+- Brokered and resumed brokered calls check the connector outcome. An allowed decision whose outcome is missing or malformed raises `AaesError` saying the effect may have run, instead of returning an empty outcome.
+- A federated grant must name the requested intent, a marker receipt hash, and the requested capability (optionally pinned as `capability@version`) and task. The sealed record's intent id is no longer filled in from the request.
+- The bearer token must be a string of printable ASCII characters. Payload numbers must be finite. Capability and catalogue entries must be JSON objects.
+- Response bodies are released after a redirect refusal or a failed read.
+- Wire types: receipts may have class `deferred`; model usage may carry `estimated: true`; execution steps accept `share` and `transfer`; the model list response types are added; license and usage summaries may carry `null` objects.
+
+## 0.1.3 (2026-10-18)
+
+- Published on npm as `@aaes-ai/govern-sdk`. Earlier releases through 0.1.2 remain under `@aaes-ai/sdk`.
+- This version was published by hand from a maintainer login at 15:34 UTC, as the package's required first publish, not by `sdk-publish.yml`. No `sdk/typescript/v0.1.3` tag or gated run exists for it, and it has no provenance. Its registry integrity (`sha512-iBcfEA4lYKhYJ47dx+ZtmGDJjqNp7oPAnPULzsoarP2mmU8tOmwKowifwV3VahlMFCx9aWpPgmNNv3uqoQcOaw==`) equals `npm pack` of commit `0193b9374`, the commit tagged `sdk/python/v0.1.2`.
+- Minor-unit amounts above `Number.MAX_SAFE_INTEGER` are refused before sending, since the caller's exact amount may already be lost as a double.
+- A daemon-published spend cap (`spend_cap_minor`, federated `spend_cap.minor`) must be a nonnegative safe integer and `latency_added_ms` a finite nonnegative number; malformed values raise `AaesError` instead of being coerced, matching the Python and Go clients. An omitted cap still reads as `0`.
+
+## 0.1.2
+
+- Packaging/metadata-only patch: the registry description states the canonical product positioning (AI governance platform for the action layer: permissions, approvals by authorized persons, spending limits on routed actions, sealed decision record), keywords added for registry search, the homepage points to aaes.ai/developers/sdks.html, and the README opens with the product definition. No functional changes; the shipped code is unchanged.
+
+## 0.1.1
+
+- Packaging-only patch, published through the sdk-publish.yml npm trusted publisher without provenance (npm provenance requires a public source repository). No functional changes; the shipped files are unchanged apart from the version field.
+- Verified the 0.1.0 tarball already ships `README.md` (extracted by the registry), so no packaging change was required for npm's README rendering.
+
+## 0.1.0 — candidate
+
+- Shared concurrent entitlement reads and prevented pre-refresh requests from replacing refreshed discovery data.
+- Forwarded optional caller-declared provenance on brokered requests so the daemon can apply the same risk rules as action requests.
+
+- Added bounded work, approval, entitlement and receipt reads.
+- Added agent-manager card reads/decisions, with explicit decision binding.
+- Added separate person-only access revocation client.
+- Preserved daemon-derived identity, fixed destinations, effect-key safeguards and redacted federated material.
+- Added native package consumer tests and release policy; TypeScript declarations and Python PEP 561 metadata.
+- README method list now advertises the complete read and card surface; every advertised method is covered by the package tests.
+
+- Reported deferred decisions instead of hiding them, and added resume across the three SDKs (Go `Resume`, Python `resume`, TypeScript `resume`): a deferred action is resubmitted unchanged under the same effect key via POST /v1/action/resume.
+- Added brokered resume (Go `ResumeBrokered`, Python `resume_brokered`, TypeScript `resumeBrokered`): a standing brokered deferral is revalidated and executed through the connector via POST /v1/brokered/resume, and a brokered resume never reports a grant without a confirmed execution as success.
+- Mapped a 404 from the resume routes to a refusal carrying the daemon's reason verbatim, falling back to the canned no-deferral sentence only when the 404 body states none; a missing deferral is answered without extra advice fetches, and decode errors name the resume route.
+- The TypeScript package publishes under the `@aaes-ai` npm scope (`@aaes-ai/sdk`), matching the GitHub organization and the Go module path; `@aaes/sdk` was never published, so the rename carried no migration cost.
+
+This entry describes the source candidate, not a published registry release.

package/README.md

@@ -1,3 +1,56 @@
-# Temporary Holding Version
+# AAES TypeScript / JavaScript SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+AAES (Autonomous Agentic Enterprise Systems) is an AI governance platform for the action layer: permissions, approvals by authorized persons, and spending limits on requests routed through it, with a sealed record of each completed decision. This package is its TypeScript/JavaScript client.
+
+ES module package `@aaes-ai/govern-sdk`, dependency-free runtime, with complete public TypeScript declarations and wire response types. Node 18+.
+
+```bash
+npm install @aaes-ai/govern-sdk
+# For local development: npm install ./sdk/typescript
+node sdk/typescript/aaes.test.mjs   # node:test, nothing to install
+```
+
+These examples require SDK access, a running AAES daemon, and a token issued by
+your deployment operator. Set `AAES_ENDPOINT` and `AAES_TOKEN` first. The request
+reads permitted capabilities; it does not execute an agent action.
+
+```js
+import { Client } from "@aaes-ai/govern-sdk";
+
+try {
+  const result = await Client.fromEnv().capabilities();
+  console.log(`${result.capabilities.length} permitted capabilities`);
+} catch (error) {
+  console.error(String(error));
+  process.exitCode = 1;
+}
+```
+
+Methods: `capabilities`, `catalogue`, `health`, `action`, `brokered`,
+`resume`, `resumeBrokered`, `presentGrant`, `requestAccess`, `accessRequest`, `observe`, `refresh`,
+`federate`, the bounded reads `listTask`, `task`, `listApprovals`,
+`approval`, `listEntitlements`, `listReceipts`, `receipt`, the
+agent-manager card reads `managerCards` and `decideManagerCard`, the
+person-only operator client's `revokeAccessRequest`, and the exported
+`verifyHint(exportPath, publicKeyPath)`. Every method above is covered by
+this package's tests (`aaes.test.mjs`, `resume.test.mjs`, `read.test.mjs`, `federation.test.mjs`).
+
+What it deliberately does not do: `action()`, `requestAccess()` and
+`observe()` refuse any key they do not document, so `url`, `method`,
+`headers`, `credential`, `token`, `tenantId` and `actorId` cannot be
+smuggled in; the payload is checked against the field names the daemon refuses;
+tenant and actor come from `GET /v1/capabilities`; receipts are the daemon's
+bytes and are verified offline with `aaesctl verify`; a mutating call is
+retried only on opt-in, only after a 503, and only under the same effect key.
+
+Full guide: [docs/guides/INTEGRATION.md](../../docs/guides/INTEGRATION.md).
+
+A 503 response does not prove that the provider performed no action. Repeat only the identical request with its original effect key; never change the key to force a retry. The daemon retains the reservation and dispatch claim for uncertain outcomes and may answer the repeat with 409. It permits another dispatch only after proving that the previous attempt was never dispatched.
+
+## Published package and expanded contract
+
+See [SDK release policy](../RELEASE.md) and [complete operation/scope table](../CONTRACT.md). Version 0.1.3 was published on npm as `@aaes-ai/govern-sdk` on 18 October 2026, by a manual first publish rather than the tag workflow (see the changelog). Version 0.2.0 is prepared and tagged `sdk/typescript/v0.2.0`, but the tag workflow's publish run failed, so 0.2.0 is not on npm. Publishing it needs a re-run of that workflow on the tag, or a new version. Earlier releases through 0.1.2 remain under `@aaes-ai/sdk`. Check npm for later releases.
+
+Endpoint transport: bearer credentials require HTTPS. HTTP is accepted only
+for explicit loopback addresses (`localhost`, `127.0.0.0/8`, or `::1`); DNS
+resolution is never used to authorize plaintext transport.

package/aaes.d.mts

@@ -0,0 +1,180 @@
+import type * as Wire from './wire.js';
+export type { Task, TaskPage, Approval, ApprovalPage, EntitlementPage, ReceiptView, ReceiptPage, PageInfo, ManagerCard, ManagerCardsResponse, ManagerCardDecisionRecorded } from './wire.js';
+export const ENDPOINT_ENV: 'AAES_ENDPOINT';
+export const TOKEN_ENV: 'AAES_TOKEN';
+export const EFFECT_DENIED: 0;
+export const EFFECT_MINTED_UNUSED: 1;
+export const EFFECT_EXECUTED: 2;
+export const EFFECT_AUTHORIZED: 3;
+export const EFFECT_DEFERRED: 4;
+export class AaesError extends Error {}
+export class CallerRouteError extends AaesError {}
+export type JSONValue = string | number | boolean | null | JSONValue[] | { [key: string]: JSONValue };
+export type Payload = { [key: string]: JSONValue };
+export class RetryPolicy {
+  constructor(options?: { maxAttempts?: number; baseDelayMs?: number });
+  maxAttempts: number; baseDelayMs: number;
+  static default(): RetryPolicy;
+  attempts(identified: boolean, answer503: boolean): number;
+  delay(attempt: number): number;
+}
+export class Refusal {
+  constructor(status: number, reason: string, advice?: string[], retryable?: boolean);
+  status: number; reason: string; advice: string[]; retryable: boolean;
+  smallestChange(): string; toString(): string;
+}
+export interface Grant {
+  grantId: string; actorId: string; tenantId: string; capability: string; tier: string;
+  taskId: string; issuedAt: string; expiresAt: string; ttlSeconds: number;
+  spendCapMinor: number | null; spendCapMinorPresent: boolean; spendCapCurrency: string; nonTransferable: boolean;
+  budgetGrantId: string; issuer: string; signature: string;
+}
+export interface GrantPresent {
+  grantId: string; actorId: string; tenantId: string; capability: string; tier: string;
+  taskId: string; issuedAt: string; expiresAt: string; spendCapMinor: number | null; spendCapMinorPresent: boolean; spendCapCurrency: string;
+}
+export interface Receipt {
+  receiptId: string; intentId: string; tenantId: string; taskId: string; approvalId: string;
+  custody: string; grantId: string; effectId: string; effect: string; recordHash: string;
+  issuedAt: string; effectClass: number; railConfirmed: boolean; confirmedAt: string;
+  reportedBy: string; reportedAt: string; observedAt: string; reportedOutcome: string;
+  note: string; receiptHash: string; policyBundleHash: string; inputHash: string; engineVersion: string;
+}
+export class Decision {
+  constructor(fields?: Partial<Omit<Decision, 'ok'>>);
+  allowed: boolean; deferred: boolean; reason: string; intentId: string; grant: Grant | null; receipt: Receipt | null;
+  latencyAddedMs: number; refusal: Refusal | null; readonly ok: boolean;
+}
+export interface ExternalRef {
+  registry: string; kind: string; value: string; source: "registered";
+}
+export interface Action {
+  capability: string; action?: string; taskId?: string; callerTaskId?: string; effectKeyStep?: string;
+  amountMinor?: number; amountCurrency?: string; grantTtlMs?: number; correlationId?: string; parentIntentId?: string;
+  contractId?: string; model?: string; provenanceStatus?: "asserted" | "unknown"; externalRefs?: ExternalRef[];
+  payload?: Payload | null;
+}
+export interface BrokeredResult { decision: Decision; outcome: Partial<Wire.Outcome> }
+export interface Capability {
+  capabilityId: string; version: string; pinned: boolean; kind: string; owner: string;
+  riskTier: string; actions: string[]; resourceId: string; dataClass: string; custody: string;
+  enforcement: string; taskId: string; callerTaskId: string; expiresAt: string | null;
+  source: string; requestId: string; readonly name: string;
+}
+export interface Entitlement {
+  tenantId: string; actorId: string; capabilities: Capability[]; find(spelling: string): Capability | null;
+}
+export interface CataloguePolicy {
+  policyId: string; label: string; required: number; minHumans: number; classes: string[]; authority: string;
+}
+export interface CatalogueEntry {
+  capabilityId: string; version: string; kind: string; owner: string; riskTier: string; actions: string[];
+  resourceId: string; dataClass: string; custody: string; policy: CataloguePolicy;
+}
+export interface Catalog {
+  tenantId: string; actorId: string; requestable: CatalogueEntry[]; find(spelling: string): CatalogueEntry | null;
+}
+export interface AccessAsk {
+  capability: string; actions?: string[]; resourceId?: string; surfaceResourceId?: string; teamId?: string;
+  dataClass?: string; tier?: string; budgetMinor?: number; budgetCurrency?: string; ttlSeconds?: number; taskId?: string;
+  justification?: string; duration?: string; reviewDays?: number; windowStart?: string; windowEnd?: string;
+  windowTimezone?: string;
+}
+export interface AccessAnswer {
+  requestId: string; state: string; needed: Partial<Wire.Quorum>; alreadyHeld: boolean; refusal: Refusal | null;
+}
+export interface AccessView {
+  requestId: string; state: string; needed: Partial<Wire.Quorum>; tenantId: string; actorId: string;
+  capability: string; actions: string[]; resourceId: string; surfaceResourceId: string; teamId: string;
+  dataClass: string; tier: string; budgetMinor: number; budgetCurrency: string; ttlSeconds: number;
+  taskId: string; justification: string; duration: string; reviewTtlSeconds: number;
+  windowStart: string; windowEnd: string; windowTimezone: string; reviewRequired: boolean;
+  reviewedBy: string; reviewedAt: string | null; reviewed: boolean; approvalId: string;
+  approvals: Wire.AccessApprovalState[]; decidedBy: string[]; decidedAt: string | null;
+  expiresAt: string | null; createdAt: string | null; reason: string;
+}
+export interface Observation { intentId: string; effectId?: string; outcome?: string; observedAt?: string; note?: string }
+export interface ObserveResult {
+  intentId: string; receipt: Receipt | null; label: string; enforcement: string;
+  countsTowardCoverage: boolean; refusal: Refusal | null;
+}
+export interface FederateRequest {
+  capability: string; action?: string; taskId: string; effectKeyStep: string; amountMinor?: number;
+  amountCurrency?: string; grantTtlMs?: number; rotate?: boolean; correlationId?: string;
+}
+export class FederatedInstructions {
+  constructor(fields?: Partial<FederatedInstructions>);
+  backend: string; method: string; url: string; headers: Record<string, string>; form: Record<string, string>;
+  json: Record<string, unknown>; subjectTokenIn: string; subjectTokenField: string; subjectTokenType: string;
+  durationSeconds: number; documentation: string; notBuilt: string[]; notes: string[];
+  toString(): string;
+  toJSON(): { backend: string; method: string; url: string; subjectTokenField: string };
+}
+export class FederatedMaterial {
+  constructor(fields?: Partial<FederatedMaterial>);
+  kind: string; credential: Uint8Array; instructions: FederatedInstructions | null; expiresAt: string; audience: string;
+  toString(): string; toJSON(): { kind: string; redacted: true; expiresAt: string; audience: string };
+}
+export interface FederatedLocator { capability: string; endpoint: string; method: string; authority: string; resourceId: string }
+export interface FederatedRecord { intentId: string; mode: string; payloadSeen: boolean; markerReceiptHash: string; receiptId: string }
+export interface FederatedScope { capability: string; actions: string[]; resourceId: string; dataClass: string; tier: string; spendCapMinor: number | null; spendCapMinorPresent: boolean; spendCapCurrency: string; scopeKey: string }
+export class FederatedGrant {
+  constructor(fields?: Partial<FederatedGrant>);
+  federationId: string; intentId: string; decisionGrantId: string; tenantId: string; actorId: string;
+  capability: string; capabilityVersion: string; actions: string[]; resourceId: string; taskId: string;
+  dataClass: string; tier: string; spendCapMinor: number | null; spendCapMinorPresent: boolean; spendCapCurrency: string; scopeKey: string; backend: string;
+  locator: FederatedLocator; issuedAt: string; expiresAt: string; ttlSeconds: number;
+  material: FederatedMaterial; record: FederatedRecord;
+  scope(): FederatedScope; toString(): string;
+  toJSON(): { federation_id: string; intent_id: string; decision_grant_id: string; tenant_id: string;
+    actor_id: string; capability: string; actions: string[]; resource_id: string; task_id: string;
+    data_class: string; tier: string; scope_key: string; backend: string; locator: FederatedLocator;
+    issued_at: string; expires_at: string; ttl_seconds: number; material: ReturnType<FederatedMaterial['toJSON']>; record: FederatedRecord };
+}
+export type FederatedResult =
+  | { ok: true; allowed: true; reason: string; grant: FederatedGrant; refusal: null }
+  | { ok: false; allowed: false; reason: string; grant: null; refusal: Refusal };
+export interface ClientOptions {
+  endpoint?: string; token?: string; retries?: RetryPolicy; timeoutMs?: number; fetchImpl?: typeof fetch;
+}
+export interface PageFilters { limit?: number; cursor?: string }
+export interface TimeFilters extends PageFilters { since?: string; until?: string }
+export interface TaskFilters extends TimeFilters { state?: string; sponsor?: string; assignee?: string; overdue?: boolean }
+export interface ApprovalFilters extends TimeFilters { intentId?: string; taskId?: string; state?: 'pending' | 'all' }
+export interface EntitlementFilters extends PageFilters { actorId?: string; capability?: string; state?: 'all' | 'usable' | 'expired' | 'revoked' }
+export interface ReceiptFilters extends TimeFilters { intentId?: string; taskId?: string; effectClass?: 'denied' | 'minted_unused' | 'authorized' | 'executed' | 'deferred'; custody?: string }
+export interface ManagerCardDecision { cardId: string; approvalId: string; payloadHash: string; policyId?: string; grant: boolean; reason?: string }
+export class Client {
+  constructor(options?: ClientOptions);
+  static fromEnv(options?: ClientOptions): Client;
+  refresh(): void;
+  entitlement(): Promise<Entitlement>;
+  capabilities(): Promise<Entitlement>;
+  catalog(): Promise<Catalog>;
+  health(): Promise<{ healthz: Wire.HealthResponse; readyz: Wire.ReadinessResponse; ready: boolean; reason: string }>;
+  action(action: Action): Promise<Decision>;
+  resume(action: Action): Promise<Decision>;
+  brokered(action: Action): Promise<BrokeredResult>;
+  resumeBrokered(action: Action): Promise<BrokeredResult>;
+  presentGrant(grantId: string): Promise<GrantPresent>;
+  federate(request: FederateRequest): Promise<FederatedResult>;
+  requestAccess(ask: AccessAsk): Promise<AccessAnswer>;
+  accessRequest(requestId: string): Promise<AccessView>;
+  observe(report: Observation): Promise<ObserveResult>;
+  listTask(filters?: TaskFilters): Promise<Wire.TaskPage>;
+  task(id: string): Promise<Wire.Task>;
+  listApprovals(filters?: ApprovalFilters): Promise<Wire.ApprovalPage>;
+  approval(id: string): Promise<Wire.Approval>;
+  listEntitlements(filters?: EntitlementFilters): Promise<Wire.EntitlementPage>;
+  listReceipts(filters?: ReceiptFilters): Promise<Wire.ReceiptPage>;
+  receipt(id: string): Promise<Wire.ReceiptView>;
+  managerCards(): Promise<Wire.ManagerCardsResponse>;
+  decideManagerCard(decision: ManagerCardDecision): Promise<Wire.ManagerCardDecisionRecorded>;
+}
+/** Requires a separately issued person token. The daemon authorizes each call. */
+export class OperatorClient extends Client {
+  static fromEnv(options?: ClientOptions): OperatorClient;
+  revokeAccessRequest(id: string, options?: { reason?: string }): Promise<AccessView>;
+}
+export function guardPayload(payload?: Payload | null): Payload | null;
+export function verifyHint(exportPath: string, publicKeyPath?: string): string;