@tryvira/sdk 0.1.11 → 0.1.13

package/README.md

@@ -1,90 +1,90 @@
-# @tryvira/sdk
-
-MIT-licensed client library. The Vira service, application, and backend remain
-proprietary and are governed separately.
-
-Typed JavaScript/TypeScript client for Vira's scoped control and runtime APIs.
-
-## Install
-
-```bash
-npm install @tryvira/sdk
-```
-
-The client sends requests to Vira; it does not execute tools locally or create a second
-authority/telemetry store. Use a customer API key for hosted deployments and a local
-development key only with the local stack.
-
-## Connect and record an observation
-
-```ts
-import { ViraClient } from '@tryvira/sdk';
-
-const vira = new ViraClient({
-  baseUrl: process.env.VIRA_CONTROL_URL ?? 'http://127.0.0.1:4185',
-  apiKey: process.env.VIRA_API_KEY,
-});
-
-const connected = await vira.connectOnce({
-  name: 'my-agent', systemType: 'custom-agent',
-  organizationId: 'org', projectId: 'project', environmentId: 'local',
-  adapterType: 'custom-node', adapterVersion: '1',
-});
-
-const systemId = String(connected?.body.system?.id);
-const connectionId = String(connected?.body.connection?.id);
-await vira.observe({
-  eventId: `event-${Date.now()}`,
-  eventType: 'model.response',
-  aiSystemId: systemId,
-  connectionId,
-  payload: { message: 'A model response was produced.' },
-}, { idempotencyKey: `event-${Date.now()}` });
-```
-
-## Semantic and runtime resolution
-
-Semantic resolution finds an eligible governed target. Runtime resolution is the effectful
-boundary and therefore requires a released behavior point, scope and idempotency key.
-
-```ts
-const semantic = await vira.resolveSemantic({
-  input: 'answer a customer billing question',
-  profile: { domain: 'support' },
-});
-
-const runtime = await vira.resolveRuntime({
-  behaviorPoint: 'support.answer',
-  executionBoundary: { organizationId: 'org', projectId: 'project', environmentId: 'local' },
-  idempotencyKey: 'runtime-request-001',
-});
-```
-
-Do not treat a semantic result as authorization. The server remains the authority and may
-abstain, deny or require a released revision.
-
-## Packs and Strategy executions
-
-The normal pack lifecycle is import → install → evaluate → approve → release. Strategy
-execution starts only from an immutable, released artifact and can be continued with
-state/references when it reaches `WAITING_USER` or `WAITING_HOST`.
-
-```ts
-const packs = await vira.listPacks();
-const imported = await vira.importPack({
-  manifest: { id: 'example.pack', name: 'Example', version: '1.0.0' },
-  objects: {},
-  idempotencyKey: 'pack-import-001',
-});
-console.log(packs?.body, imported?.body);
-
-const continued = await vira.continueStrategyExecution('execution-id', {
-  authorityDigest: 'digest-from-the-execution',
-  state: { answer: 'approved' },
-  references: { userInput: { answer: 'approved' } },
-});
-```
-
-## Documentation
-
-See the public Vira documentation at https://github.com/hrpering/tryvira.
+# @tryvira/sdk
+
+MIT-licensed client library. The Vira service, application, and backend remain
+proprietary and are governed separately.
+
+Typed JavaScript/TypeScript client for Vira's scoped control and runtime APIs.
+
+## Install
+
+```bash
+npm install @tryvira/sdk
+```
+
+The client sends requests to Vira; it does not execute tools locally or create a second
+authority/telemetry store. Use a customer API key for hosted deployments and a local
+development key only with the local stack.
+
+## Connect and record an observation
+
+```ts
+import { ViraClient } from '@tryvira/sdk';
+
+const vira = new ViraClient({
+  baseUrl: process.env.VIRA_CONTROL_URL ?? 'http://127.0.0.1:4185',
+  apiKey: process.env.VIRA_API_KEY,
+});
+
+const connected = await vira.connectOnce({
+  name: 'my-agent', systemType: 'custom-agent',
+  organizationId: 'org', projectId: 'project', environmentId: 'local',
+  adapterType: 'custom-node', adapterVersion: '1',
+});
+
+const systemId = String(connected?.body.system?.id);
+const connectionId = String(connected?.body.connection?.id);
+await vira.observe({
+  eventId: `event-${Date.now()}`,
+  eventType: 'model.response',
+  aiSystemId: systemId,
+  connectionId,
+  payload: { message: 'A model response was produced.' },
+}, { idempotencyKey: `event-${Date.now()}` });
+```
+
+## Semantic and runtime resolution
+
+Semantic resolution finds an eligible governed target. Runtime resolution is the effectful
+boundary and therefore requires a released behavior point, scope and idempotency key.
+
+```ts
+const semantic = await vira.resolveSemantic({
+  input: 'answer a customer billing question',
+  profile: { domain: 'support' },
+});
+
+const runtime = await vira.resolveRuntime({
+  behaviorPoint: 'support.answer',
+  executionBoundary: { organizationId: 'org', projectId: 'project', environmentId: 'local' },
+  idempotencyKey: 'runtime-request-001',
+});
+```
+
+Do not treat a semantic result as authorization. The server remains the authority and may
+abstain, deny or require a released revision.
+
+## Packs and Strategy executions
+
+The normal pack lifecycle is import → install → evaluate → approve → release. Strategy
+execution starts only from an immutable, released artifact and can be continued with
+state/references when it reaches `WAITING_USER` or `WAITING_HOST`.
+
+```ts
+const packs = await vira.listPacks();
+const imported = await vira.importPack({
+  manifest: { id: 'example.pack', name: 'Example', version: '1.0.0' },
+  objects: {},
+  idempotencyKey: 'pack-import-001',
+});
+console.log(packs?.body, imported?.body);
+
+const continued = await vira.continueStrategyExecution('execution-id', {
+  authorityDigest: 'digest-from-the-execution',
+  state: { answer: 'approved' },
+  references: { userInput: { answer: 'approved' } },
+});
+```
+
+## Documentation
+
+See the public Vira documentation at https://github.com/hrpering/tryvira.

package/dist/index.js

@@ -658,6 +658,10 @@ var ViraClient = class {
       { idempotencyKey: options.idempotencyKey }
     );
   }
+  createManualRelease(input, options = {}) {
+    if (!input || typeof input !== "object" || !input.manualApproval) throw new Error("SDK_MANUAL_RELEASE_APPROVAL_REQUIRED");
+    return this.createRelease(input, { idempotencyKey: options.idempotencyKey });
+  }
   recordDeploymentComparison(deploymentId, comparison, options = {}) {
     required(deploymentId, "SDK_DEPLOYMENT_ID_REQUIRED");
     return this.request(

package/dist/js-client.d.ts

@@ -28,6 +28,27 @@ export interface ViraResponse<T = unknown> {
     body: T;
     requestId: string;
 }
+export interface BehaviorProjection {
+    rendered: string;
+    projectionDigest: string;
+    programDigest: string;
+    [key: string]: unknown;
+}
+export interface ProjectionReceipt {
+    projectionDigest: string;
+    programDigest: string;
+    artifactDigest: string;
+    receiptDigest: string;
+    [key: string]: unknown;
+}
+export interface RuntimeResolution {
+    behaviorPoint: string;
+    strategySelection?: ClientBody | null;
+    behaviorProjection?: BehaviorProjection;
+    projectionReceipt?: ProjectionReceipt;
+    projectionMode?: "active" | "unavailable" | "not-applicable";
+    [key: string]: unknown;
+}
 export interface ConnectOnceResult {
     system: ClientBody;
     connection: ClientBody;
@@ -188,13 +209,13 @@ export declare class ViraClient {
         executionBoundary?: Record<string, unknown>;
         semanticContext?: Record<string, unknown>;
         idempotencyKey?: string;
-    }): Promise<ViraResponse<ClientBody> | null>;
+    }): Promise<ViraResponse<RuntimeResolution> | null>;
     /** Resolve a runtime route from a governed execution boundary and semantic context. */
     resolveBoundary(input: {
         executionBoundary: Record<string, unknown>;
         semanticContext?: Record<string, unknown>;
         idempotencyKey?: string;
-    }): Promise<ViraResponse<ClientBody> | null>;
+    }): Promise<ViraResponse<RuntimeResolution> | null>;
     resolveSemantic(input: {
         input: string;
         profile?: Record<string, unknown>;
@@ -216,7 +237,7 @@ export declare class ViraClient {
         idempotencyKey?: string;
     }): Promise<{
         semantic: ViraResponse<ClientBody>;
-        runtime: ViraResponse<ClientBody> | null;
+        runtime: ViraResponse<RuntimeResolution> | null;
     } | null>;
     listBehaviorStrategies(): Promise<ViraResponse<ClientBody> | null>;
     deleteBehaviorStrategy(strategyId: string, options?: {
@@ -338,6 +359,9 @@ export declare class ViraClient {
     createRelease(input: ClientBody, options?: {
         idempotencyKey?: string;
     }): Promise<ViraResponse<ClientBody> | null>;
+    createManualRelease(input: ClientBody, options?: {
+        idempotencyKey?: string;
+    }): Promise<ViraResponse<ClientBody> | null>;
     recordDeploymentComparison(deploymentId: string, comparison: ClientBody, options?: {
         idempotencyKey?: string;
     }): Promise<ViraResponse<ClientBody> | null>;

package/package.json

@@ -1,18 +1,18 @@
-{
-  "name": "@tryvira/sdk",
-  "version": "0.1.11",
-  "description": "Typed Vira SDK for connect-once, observation and governed runtime execution.",
-  "keywords": ["vira", "ai-governance", "ai-runtime", "semantic-routing"],
-  "engines": {"node": ">=20"},
-  "repository": {"type": "git", "url": "https://github.com/hrpering/tryvira.git"},
-  "homepage": "https://github.com/hrpering/tryvira#readme",
-  "bugs": {"url": "https://github.com/hrpering/tryvira/issues"},
-  "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {".": {"types": "./dist/index.d.ts", "import": "./dist/index.js"}},
-  "files": ["dist/index.js", "dist/index.d.ts", "dist/js-client.d.ts", "README.md"],
-  "publishConfig": {"access": "public"},
-  "scripts": {"build": "node ../../scripts/build-publishable-packages.mjs sdk", "pack:check": "npm run build && npm pack --dry-run && npm run public:surface:smoke", "public:surface:smoke": "node ../../scripts/public-surface-contract-acceptance.mjs --sdk-package", "prepublishOnly": "npm run pack:check && npm run public:surface:smoke", "publish:public": "npm run pack:check && npm run public:surface:smoke && npm publish --access public"},
-  "license": "MIT"
-}
+{
+  "name": "@tryvira/sdk",
+  "version": "0.1.13",
+  "description": "Typed Vira SDK for connect-once, observation and governed runtime execution.",
+  "keywords": ["vira", "ai-governance", "ai-runtime", "semantic-routing"],
+  "engines": {"node": ">=20"},
+  "repository": {"type": "git", "url": "https://github.com/hrpering/tryvira.git"},
+  "homepage": "https://github.com/hrpering/tryvira#readme",
+  "bugs": {"url": "https://github.com/hrpering/tryvira/issues"},
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {".": {"types": "./dist/index.d.ts", "import": "./dist/index.js"}},
+  "files": ["dist/index.js", "dist/index.d.ts", "dist/js-client.d.ts", "README.md"],
+  "publishConfig": {"access": "public"},
+  "scripts": {"build": "node ../../scripts/build-publishable-packages.mjs sdk", "pack:check": "npm run build && npm pack --dry-run && npm run public:surface:smoke", "public:surface:smoke": "node ../../scripts/public-surface-contract-acceptance.mjs --sdk-package", "prepublishOnly": "npm run pack:check && npm run public:surface:smoke", "publish:public": "npm run pack:check && npm run public:surface:smoke && npm publish --access public"},
+  "license": "MIT"
+}