@uicnz/aria-sdk

v0.20.3

Published

19 days ago

Official TypeScript SDK for applications that connect to an installed Aria Runtime.

0High
0Medium
0Low

shaneholloman

Aria SDK

Official TypeScript SDK for applications that connect to an installed Aria Runtime.

Aria Runtime is a separate proprietary binary distributed privately through an authorized Aria channel. The SDK does not contain the Runtime, start it automatically during onboarding, or require access to Aria source code. No public Runtime download URL or package-manager installation command exists today. A developer or coding agent must begin with an installed aria binary and a Runtime that is reachable, healthy, licensed, authenticated, and authorized for the capabilities the application needs.

Current Release Scope

Local Node and Bun applications can authenticate with an installed Aria Runtime today through project enrollment. Direct authentication from JavaScript running inside a web browser is coming soon. The @uicnz/aria-sdk/web transport remains available for managed clients that have already received a Runtime access credential through an authorized handoff; the SDK does not currently provide ordinary browser credential enrollment.

Enroll, Then Run Preflight

After the Runtime is ready and an authenticated connection is linked to the intended profile, authorize this application with the installed binary:

aria sdk enroll \
    --name YOUR_APPLICATION_NAME \
    --profile PASTE_RUNTIME_PROFILE_ID \
    --connection PASTE_RUNTIME_CONNECTION_ID \
    --capability discovery.read \
    --capability sessions.read

The command requires local-presence approval and stores one ignored, owner-only credential at .aria/private/sdk-client.json. Its secret never appears in arguments or command output. Request the complete capability set the application actually needs; the enrollment becomes its server-enforced ceiling.

Then make preflight the first SDK command you run. Bun is recommended:

bunx --bun --no-install --package @uicnz/aria-sdk aria-sdk preflight

The equivalent scoped npm command is:

npm exec --package=@uicnz/aria-sdk -- aria-sdk preflight

For automation and coding agents, request the same redacted report as JSON:

bunx --bun --no-install --package @uicnz/aria-sdk aria-sdk preflight --json

npm exec --package=@uicnz/aria-sdk -- aria-sdk preflight --json

The explicit package selectors prevent resolution of the unrelated unscoped package. After installing @uicnz/aria-sdk, both commands use this application's package-local binary. Bun's --no-install and npm's optional --offline prevent registry fallback. Inside a package script, the shorter aria-sdk preflight command resolves the same package-local binary.

Preflight checks:

the installed aria binary and its version;
whether the application root is initialized for a project-local Runtime;
connectivity, readiness, and health of the selected Runtime;
licensing, service access, and authentication-profile readiness;
requested, granted, refused, and supported capabilities;
SDK and Runtime contract compatibility;
the configured default provider and whether its required credential is present;
the configured default model.

Preflight is read-only and redacted. It never starts, stops, configures, or authenticates a Runtime, and it never invokes a model. A blocked report exits with status 1; invalid command usage exits with status 2. Do not begin SDK development while preflight is blocked.

Prerequisites

Before the SDK can work, all of the following must be true:

Obtain the Aria Runtime binary through your authorized distribution channel.
Install aria on PATH and confirm that aria --version succeeds.
From the application root, initialize its project-local Aria state with aria init project. This creates the .aria project marker and settings; it does not require Runtime source code.
Start the installed Runtime with aria --daemon ensure from that same application root.
Complete any required Aria activation, licensing, user authentication, and local profile selection.
Configure an active default provider and default model in Aria Runtime.
Enroll this exact project, profile, authenticated connection, and required capability set with aria sdk enroll.
Install the SDK in your application. Bun is recommended:
```
bun add @uicnz/aria-sdk
```
Or use npm:
```
npm install @uicnz/aria-sdk
```

The SDK is an ESM package. It is a client over Runtime-owned state and policy; it cannot repair missing Runtime installation, licensing, authorization, or provider configuration on its own.

Use the installed binary to inspect that handoff before writing application code:

aria init project
aria --daemon ensure
aria --daemon status-summary
aria --daemon auth-status
aria --daemon auth-profiles
aria --daemon providers
aria --daemon models

An uninitialized directory belongs to Aria's user-home namespace rather than a distinct project Runtime. aria --daemon ensure now stops immediately with the initialization command instead of waiting on a socket that cannot represent that application. Run all project-local Runtime and SDK commands from the initialized application root, or pass that exact root through --project-root.

These commands operate on the installed Runtime. They do not require a source checkout. Treat their identifiers as Runtime-issued values: copy an exact profile, provider, model, session, turn, request, or worker id only where an SDK operation explicitly asks for it.

Authorization And Capability Grants

Every connection requests explicit Runtime capabilities. Preflight always requests discovery.read; prove additional application requirements by repeating --capability:

bunx --bun --no-install --package @uicnz/aria-sdk aria-sdk preflight \
  --capability sessions.read \
  --capability sessions.manage \
  --capability events.subscribe \
  --capability requests.read

npm exec --package=@uicnz/aria-sdk -- aria-sdk preflight \
  --capability sessions.read \
  --capability sessions.manage \
  --capability events.subscribe \
  --capability requests.read

A supported capability is not automatically granted. Runtime evaluates the enrolled application and returns the granted and refused sets. The SDK does not elevate its own access or work around a refusal. If a required capability is refused, review the exact project enrollment and Runtime policy, then rerun preflight. Adding a capability requires a new approved enrollment; never remove a required capability merely to make preflight green.

Provider authentication, automation-profile authorization, and application enrollment are separate gates. aria --daemon auth-status can show authenticated provider connections while aria --daemon auth-profiles still shows no usable profile, and a usable profile does not authorize a new SDK application by itself. Profile creation, linking, authority assignment, and local-default selection are policy-bearing administrative actions; perform them through the installed Runtime under your organization's authorization process. Then enroll the exact project with aria sdk enroll and rerun preflight with the same capabilities. Preflight intentionally never bootstraps, links, or enrolls authority.

Inspect enrollment without exposing its credential:

aria sdk status --json

Use aria sdk rotate to replace the project credential without changing its policy binding. Use aria sdk revoke to remove application authority and delete the local credential. Both mutations require local-presence approval.

Machine principals and attestation

The project credential is the ordinary local machine identity. Runtime validates its exact project, profile revision, authenticated connection, revocation/expiry state, and capability ceiling on every connection. Do not copy it between projects, edit it, print it, commit it, or combine it speculatively with another identity.

Managed installations and CI can instead require a named machine principal, an attestation token, or both:

bunx --bun --no-install --package @uicnz/aria-sdk aria-sdk preflight \
  --profile PASTE_ADMINISTRATOR_ISSUED_PROFILE_ID \
  --principal-subject [email protected] \
  --principal-provider constellation-idp \
  --principal-instance https://identity.andromeda.example \
  --principal-scope sdk:develop \
  --attestation-token-env ARIA_SDK_ATTESTATION_TOKEN

npm exec --package=@uicnz/aria-sdk -- aria-sdk preflight \
  --profile PASTE_ADMINISTRATOR_ISSUED_PROFILE_ID \
  --principal-subject [email protected] \
  --principal-provider constellation-idp \
  --principal-instance https://identity.andromeda.example \
  --principal-scope sdk:develop \
  --attestation-token-env ARIA_SDK_ATTESTATION_TOKEN

Populate ARIA_SDK_ATTESTATION_TOKEN through your operating system or secret manager. Never place an attestation token in command arguments, a URL, source control, logs, or issue reports. --attestation-token-env names the environment variable; it does not put the secret itself on the process argument list or in the preflight report.

When Runtime requires attestation, the claimed principal must match the identity resolved from the token. Use the subject, provider, and scopes issued by your administrator rather than copying the fictional values above.

Applications can present the same identity when connecting:

import { Aria } from "@uicnz/aria-sdk/node";

const attestationToken = process.env.ARIA_SDK_ATTESTATION_TOKEN;
if (!attestationToken) {
    throw new Error("ARIA_SDK_ATTESTATION_TOKEN is required.");
}

const aria = await Aria.connectLocal({
    compatibility: "strict",
    clientName: "andromeda-build-observer",
    requestedCapabilities: ["discovery.read", "sessions.read"],
    principal: {
        subjectId: "[email protected]",
        providerId: "constellation-idp",
        providerInstance: "https://identity.andromeda.example",
        scopes: ["sdk:develop"],
    },
    attestationToken,
});

try {
    console.log(await aria.server.status.read());
} finally {
    await aria.close();
}

Use explicit principal and attestation options only for the managed handoff that issued them. Ordinary local applications omit them and use their project enrollment. In either case, continue only when preflight with the same requested capability set reports authorization and exact-profile readiness.

Provider And Model Readiness

Preflight distinguishes credential presence from credential verification:

missing means Runtime cannot see a required provider credential.
configuredUnverified means the credential is present, but preflight has not used it.
notRequired means the selected provider does not require that credential shape.

Because preflight never invokes a model, it cannot prove that a configured credential is accepted by the provider. A readyWithWarnings provider result is therefore expected when a credential is present but unverified. The first authoritative-answer golden path is the end-to-end proof of provider authorization and model execution.

SDK And Runtime Compatibility

Preflight compares advertised contract versions, supported SDK major ranges, operation hashes, and Runtime compatibility metadata. A matching-looking package version alone is not sufficient evidence.

Treat contract.status: "mismatch", compatible: false, or any contract blocker as a stop condition. Obtain and install a Runtime version compatible with this SDK through your authorized private Aria distribution channel, or install the compatible SDK version for your existing Runtime; then rerun preflight. Application connections that must reject mismatches should use compatibility: "strict".

Executable Golden Path

The packed SDK includes an ordered learning path under examples/golden/. Run it with Node 24 or later. The model-free connection proof can clarify a blocked preflight; do not continue to model-backed or mutating examples until preflight succeeds for their principal and capabilities:

00-preflight: the aria-sdk preflight command proves binary, Runtime, authorization, profile, capability, provider, model, and contract readiness without mutation.
01-connect.ts: establishes a strict connection and prints actual Runtime status and granted/refused capabilities.
02-first-turn.ts: creates a durable session and prints the exact authoritative agent answer.
03-stream-turn.ts: reconciles correlated stream deltas with the completed timeline answer.
04-handle-request.ts: inspects one exact request; resolution requires an explicit decision and matching confirmation id.
05-resume-and-fork.ts: returns authoritative answers from both a resumed session and a distinct fork.
06-observe-automation.ts: read-only observation of exact worker progress and the durable answer visible through shared Runtime state.

Start with the model-free connection proof:

bunx --bun --no-install --package @uicnz/aria-sdk aria-sdk example 01-connect

npm exec --package=@uicnz/aria-sdk -- aria-sdk example 01-connect

Then run the first provider-backed proof. The ordinary local path discovers the exact enrollment-bound profile automatically:

bunx --bun --no-install --package @uicnz/aria-sdk aria-sdk example 02-first-turn

npm exec --package=@uicnz/aria-sdk -- aria-sdk example 02-first-turn

On a managed installation without a local project credential, provide the exact profile and the same --principal-* and --attestation-token-env options that made preflight succeed. Do not infer success from a session ID, turn ID, timeline item ID, or arbitrary event count.

The first-turn example uses an obviously fictional prompt, waits for that exact turn to reach authoritative terminal state, prints the actual agent response, and reports the identities used for reconciliation. It may invoke a paid model and is the first point at which provider credentials are verified end to end. See examples/README.md for every command, effect, timeout, cleanup rule, and specialized recipe.

Connect After Preflight

For a local Node application, connect to the already-running Runtime and request only the capabilities the application needs:

import { Aria, resolveAriaSdkEnrollmentProfile } from "@uicnz/aria-sdk/node";

const enrollment = resolveAriaSdkEnrollmentProfile();
if (!enrollment || enrollment.source !== "enrollment") {
    throw new Error('Run "aria sdk enroll" from this project first.');
}

const aria = await Aria.connectLocal({
    compatibility: "strict",
    projectRoot: process.cwd(),
    clientName: "andromeda-session-reader",
    requestedCapabilities: ["discovery.read", "sessions.read"],
});

try {
    const status = await aria.server.status.read();
    const access = await aria.client.access.read();
    console.log({ profileId: enrollment.profileId, status, access });
} finally {
    await aria.close();
}

projectRoot selects the consumer project's local Runtime socket. It is not a path to Aria source code.

Public Entry Points

@uicnz/aria-sdk: universal typed client, operation facade, object handles, streams, media helpers, errors, and diagnostics.
@uicnz/aria-sdk/node: local IPC plus Node HTTP and WebSocket clients, preflight, and Node media helpers.
@uicnz/aria-sdk/web: browser-safe transport helpers for managed clients with an already-issued Runtime access credential; ordinary direct-browser authentication is coming soon.
@uicnz/aria-sdk/contracts: operation descriptors, schemas, capabilities, idempotency metadata, request/event types, and transport availability.
@uicnz/aria-sdk/contracts/<family>: focused contract shards such as sessions, tools, media, and mcp.
@uicnz/aria-sdk/testing: mock transports, fixtures, conformance checks, and replay utilities for application tests.

Typed, Generated, And Raw Operation Access

The same Runtime operation can be reached through a typed object handle, generated namespace, or raw operation call:

const handled = await aria.session(sessionId).read();
const generated = await aria.ops.session.read({ sessionId });
const raw = await aria.call("session.read", { sessionId });

Prefer object handles and generated namespaces for ordinary application code. Use raw calls for generic infrastructure that already understands Runtime operation contracts.

Inspect the installed SDK contract without reading Aria source code:

const descriptor = aria.describe("session.read");
const operations = aria.operations.list();
const transports = aria.operations.transportAvailability("session.read");

HTTP, SSE, And WebSocket Clients

Remote clients use @uicnz/aria-sdk/web. Today this entrypoint requires a Runtime access credential already issued through an authorized managed handoff. Ordinary browser credential enrollment is coming soon. Pass Runtime-issued credentials through transport options, never query strings.

import { Aria } from "@uicnz/aria-sdk/web";

const aria = Aria.connectHttp({
    endpoint: "https://runtime.andromeda.example",
    authToken: () => readRuntimeAccessToken(),
    compatibility: "strict",
});

console.log(await aria.server.status.read());

WebSocket clients mint short-lived Runtime upgrade tickets. SSE and WebSocket subscriptions should always have application-owned cancellation, timeout, and cleanup behavior.

Requests And Approvals

Runtime requests, including approvals and credential requests, are explicit typed records. Reading a request requires requests.read; resolving one requires requests.respond. Runtime derives the responder identity from an ordinary enrolled connection. A managed client supplies a responding entity only when its administrator issued that exact identity as part of the authorization handoff.

const request = await aria.request(requestId).readRequired();
console.log({
    requestId: request.requestId,
    kind: request.kind,
    status: request.status,
    requestPayload: request.requestPayload,
});

Inspection is not approval. Use examples/golden/04-handle-request.ts when implementing an explicit response path; it requires the exact request id, an approve/deny choice, and a second matching request-id confirmation. Do not invent a responding entity for the ordinary enrolled path. Applications must not silently approve requests merely to keep work moving.

Errors And Diagnostics

SDK errors retain structured, redacted metadata when Runtime supplies it, including the operation, request and connection identities, transport, status, required capability, idempotency key, retryability, and contract metadata.

try {
    await aria.sessions.list();
} catch (error) {
    const denial = aria.capabilities.explainDenied(error);
    if (denial.denied) console.error(denial.message);
    throw error;
}

Use aria.diagnostics() and handle-level diagnostics() methods for redacted client, contract, capability, retry, and stream state. Diagnostics are not a substitute for aria-sdk preflight, which also probes the installed binary and live Runtime.

Testing

Use @uicnz/aria-sdk/testing for deterministic application unit tests:

import {
    createAriaReadyStatusFixture,
    createAriaTestingClient,
} from "@uicnz/aria-sdk/testing";

const aria = createAriaTestingClient({
    handlers: {
        "server.status.read": () =>
            createAriaReadyStatusFixture({
                runtimeVersion: "0.0.0-fictional",
            }),
    },
});

console.log(await aria.server.status.read());

Mock conformance proves application behavior against SDK contracts; it does not prove that an installed Runtime, authorization policy, provider credential, or model works. Keep at least one live integration test against the same installed Runtime artifact used in deployment.

Guidance For Coding Agents

When working from the SDK distribution alone:

Do not search for or assume access to Aria Runtime source code.
Confirm the separately installed Runtime is ready, authenticated, and configured.
Enroll the exact project, profile, connection, and capability binding with aria sdk enroll; never inspect or copy the credential.
Run bunx --bun --no-install --package @uicnz/aria-sdk aria-sdk preflight --json, or the equivalent npm exec --package=@uicnz/aria-sdk -- aria-sdk preflight --json, and treat its report as the initial machine-readable SDK handoff.
Stop on blockers instead of inventing source-launch commands or silently reducing requested capabilities.
Request the smallest explicit capability set required by the application.
Never expose access tokens, provider credentials, enrollment credentials, or attestation material in arguments, URLs, logs, examples, or generated output.
Treat queued IDs and accepted submissions as acknowledgements, not completed agent answers.
Wait for the exact operation's authoritative terminal result and return the meaningful result to the caller.

License

The Aria SDK is proprietary software and is not open source. It is publicly installable so authorized users and integrators can build against Aria Runtime contracts. See LICENSE.md for package terms.