@tryvira/sdk 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1 @@
+Apache License 2.0

package/README.md

@@ -1,3 +1,96 @@
-# Temporary Holding Version
-
-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.
+# @tryvira/sdk
+
+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' } },
+});
+```
+
+## Local verification
+
+From the repository root:
+
+```bash
+npm run local:up
+npm run local:acceptance
+npm run public:surface:acceptance
+```
+
+See [`docs/SDK_GUIDE.md`](../../docs/SDK_GUIDE.md) for the full public-client lifecycle and
+[`docs/AUTH_AND_SCOPING.md`](../../docs/AUTH_AND_SCOPING.md) for credential and scope rules.

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from "./js-client.js";