Subscription Runtime

Provider-neutral TypeScript runtime for running subscription-backed AI agents from backend services, CI jobs, local worker pools and controlled project workflows.

The package keeps provider execution, session custody, refresh, capacity, concurrency, durable run state, redaction and recovery behind stable contracts. Codex is the most complete provider integration. Claude provider and worker surfaces use the same runtime boundaries.

subscription-runtime is an execution and safety kernel, not an autonomous orchestrator. It can report facts, enforce admission rules and execute brokered operations. A host application still decides what work matters, which roles to run, how to prioritize a backlog and when a workflow is complete.

• provider-neutral session, task, result and event contracts;
• Codex and Claude provider adapters;
• bounded, capacity-aware backend worker pools;
• encrypted local session custody with generation-aware writeback;
• account identity, quota, cooldown and reconnect diagnostics;
• safe execution, workspace isolation and command policy;
• durable worker control inboxes, run events and read models;
• brokered project-control admission, handoff, review, recovery and integration;
• provider-neutral agent-task request/result/event protocol;
• optional in-memory and BullMQ queue adapters;
• an OpenAI-compatible Codex bridge;
• GitHub Actions no-plaintext secret writeback and runner adapters;
• contract fakes and adapter certification helpers.

The runtime owns execution mechanics and project-neutral safety:

• provider session validation, refresh and failure classification;
• encrypted custody, leases, fencing, idempotency and stale-generation checks;
• account capacity facts and safe account reservation;
• bounded worker lifecycle, cancellation, timeouts and recovery;
• normalized run events, snapshots and sanitized diagnostics;
• isolated workspaces, immutable handoff artifacts and reviewed integration;
• brokered codex_goal_project_* operations and durable operation recovery.

The host or orchestrator owns strategy:

• project and task selection;
• producer, reviewer or verifier mix;
• backlog priority and benchmark policy;
• autonomous coordination and completion decisions;
• product-specific retry, escalation and approval policy.

Runtime adapters report facts and enforce safety decisions. They must not hide orchestrator policy inside filesystem, queue, provider, CLI or MCP code.

• Node.js 20 or newer;
• Git and npm for source builds, or package-registry access when consuming a published artifact;
• the provider CLI and an authenticated provider session for provider-specific execution;
• claude-runtime installed alongside the consumer when using the default worker-claude execution engine;
• a base64 or base64url encoded 32-byte key when using encrypted local custody.

Never commit package tokens, provider auth.json, cookies or decrypted session artifacts.

Pin a reviewed full commit SHA, build the source and consume the resulting tarball:

git clone https://github.com/777genius/ar.git subscription-runtime
cd subscription-runtime
git checkout --detach FULL_REVIEWED_COMMIT_SHA
npm ci
npm run check
npm pack
# From the consuming project:
npm install /absolute/path/to/vioxen-subscription-runtime-*.tgz

Do not use a floating branch as a production dependency. The package keeps the name @vioxen/subscription-runtime for API compatibility while the source repository is 777genius/ar.

Configure the @vioxen scope for GitHub Packages:

@vioxen:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}

Then install the published package:

npm install @vioxen/subscription-runtime

Production consumers should commit their lockfile so deployments use the exact artifact that was reviewed. Published versions and release notes are available in GitHub Releases. See Package Consumption for CI authentication and update guidance.

Prefer subpath imports. They make adapter boundaries visible and are verified by the packed-consumer gate.

The root import exposes namespace groups, but subpaths are the stable choice for application code:

import { createSubscriptionRuntime } from "@vioxen/subscription-runtime/core";
import { FileBackendCodexWorker } from "@vioxen/subscription-runtime/worker-codex";
import { BoundedSubscriptionWorkerPool } from "@vioxen/subscription-runtime/worker-core";

This example uses one authenticated Codex account and encrypted local state. It is intended for a backend or a disposable integration project, not as a project orchestration policy.

import { FileBackendCodexWorker } from "@vioxen/subscription-runtime/worker-codex";

const worker = new FileBackendCodexWorker({
  workerId: "codex-main",
  providerInstanceId: "codex-main",
  stateRootDir: "/var/lib/subscription-runtime",
  codexBinaryPath: "codex",
  encryptionKey: process.env.SUBSCRIPTION_RUNTIME_FILE_KEY!,
  model: process.env.CODEX_MODEL ?? "gpt-5.6-sol",
  reasoningEffort: "xhigh",
});

await worker.seedCodexAuthJsonFile(process.env.CODEX_AUTH_JSON_PATH!);
await worker.start();

try {
  const result = await worker.run({
    prompt: "Return a compact JSON readiness assessment.",
  });
  console.log(result.outputText);
} finally {
  await worker.dispose();
}

The durable state directory stores encrypted records. The provider auth file is an explicit bootstrap source and must remain outside version control.

Treat model IDs as exact provider identifiers. For GPT-5.6 Sol use gpt-5.6-sol, not gpt-5.6, and verify availability through the active account's Codex app-server model/list catalog. GPT-5.6 Sol requires Codex CLI 0.144.0 or newer.

For pools, account rotation and deployment guidance, see Backend Workers, Codex Auth and Codex Worker Pool Operations.

Inspect safe account and capacity facts without launching a provider task:

subscription-runtime-account-status --provider all --json
subscription-runtime-account-status --provider codex --only reconnect_required

Provider probes are opt-in because they can spend provider capacity. See Account Diagnostics and Agent Account Observability.

The package publishes these executables:

The goal CLI and MCP server are operational control surfaces, not a hidden orchestrator. They expose facts and brokered actions while the caller owns the desired workflow. Start with Codex Worker Agent Quickstart and Project Access Boundaries.

The repository follows Clean Architecture with feature-sliced bounded contexts for complex runtime features:

host application / orchestrator
  -> agent-task, OpenAI bridge, CLI or MCP transport
    -> worker-core application and domain contracts
      -> provider ports, custody ports, control ports and integration ports
        -> Codex / Claude / local file / BullMQ / GitHub adapters

Dependency direction stays inward:

• core owns provider-neutral session and execution contracts;
• worker-core owns worker, control, integration and observability domains;
• providers implement provider behavior without importing host policy;
• stores implement custody and durable facts without deciding what to run;
• CLI, MCP, queues and process runners remain adapters;
• worker-codex and worker-claude are composition surfaces, not domain cores.

Temporal, JetStream, Redis, webhooks and filesystem details must stay out of worker-core. Add them through ports and adapter packages.

See Architecture and Runtime DDD And Feature Architecture for the complete dependency and bounded-context rules.

Project-control capabilities have grown beyond simple worker launch. The current runtime includes:

• typed launch requests, admission state and required integration inputs;
• isolated writer workspaces and pinned source revisions;
• immutable producer handoff artifacts and verifier input patches;
• durable operation claims, fencing, recovery and replay;
• capacity-aware account reservation, cooldown and safe rotation;
• control inbox delivery and active-turn guidance;
• reviewed output adoption, remediation and merge-bound integration;
• run-event replay, projections and compact operations snapshots;
• rollback or quarantine when reviewed output cannot be safely admitted.

These mechanisms prove that an action is allowed and recoverable. They do not decide which project outcome should be pursued.

Relevant references:

• Project Access Boundaries
• Run Event API
• Runtime Boundaries And Worker Control Inbox
• Codex Worker Pool Operations

• Provider credentials are never valid log or persisted event payloads.
• Durable local sessions use AES-256-GCM with a 32-byte key.
• Refreshed sessions use generation hashes, compare-and-swap writeback, idempotency and lease state.
• GitHub Actions writeback sends sealed encrypted values, not raw auth JSON.
• Materialized provider auth belongs in process-local temporary state.
• Worker pools are bounded and expose queue, health and capacity state.
• Provider, runtime and event discriminators use strict TypeScript enums or validated literal contracts, with explicit handling for unknown legacy data.
• Worker writes require an admitted access scope. Integration into the target workspace additionally requires reviewed handoff evidence.
• Runtime results, events and diagnostics are sanitized before persistence or transport.

For adapter-level guarantees, see Adapter Certification.

Install dependencies and run the complete local quality gate:

npm ci
npm run check

The gate covers TypeScript, build output, unit and contract tests, architecture boundaries, package contents and a packed external consumer.

Useful focused commands:

npm run typecheck
npm test
npm run check:boundaries
npm run check:packed-consumer

Live worker, provisioning, terminal, task-assignment, smoke and E2E scripts are not part of the normal quality gate. Run them only with explicit authorization and only against disposable sandbox/test projects, never real user projects.

The Publish Package GitHub Actions workflow builds, tests, packs and publishes the artifact to GitHub Packages from a GitHub Release or manual dispatch. It can also attach the exact tarball to the release.

Publishing is idempotent and fail-closed. Before npm publish, the workflow checks the current package.json version with an authenticated registry request. An absent version may be published. An existing version is downloaded and skipped only when its SHA-512 integrity is byte-identical to the freshly packed artifact; mismatches or incomplete metadata stop the workflow. Existing release assets follow the same byte-identity rule, and new assets are uploaded without overwrite/clobber behavior. The network-free preflight regression suite is available through npm run check:publish-preflight. Release events and manual dispatch both require an existing tag that equals v<package.json version> exactly; package-only branch publication is not supported. When a target version is absent, the standard authenticated npm registry /-/whoami endpoint confirms token validity without depending on any particular package or retained version. CI exercises that same production helper against GitHub Packages with its read-only package token whenever the publish contract or its workflow changes.

dist is generated for packaging and is not committed. Public subpaths must pass check:packed-consumer before release.

Licensed under the Apache License 2.0.