Add unified provider runtime (#3)

Release the 0.2.0 unified adapter/runtime layer with validated inputs, normalized outputs, lifecycle hooks, built-in RunningHub and OpenAI-compatible adapters, and Node 22-safe timeout enforcement.

Author: Hhh2178

CHANGELOG.md

@@ -2,7 +2,7 @@
 
 All notable changes to `aigc-provider-runtime-kit` are recorded here.
 
-## Unreleased
+## 0.2.0 - 2026-07-10
 
 ### Fixed
 
@@ -19,6 +19,11 @@ All notable changes to `aigc-provider-runtime-kit` are recorded here.
 - Dependency-free OpenAI-compatible chat, image, and custom JSON client.
 - Opt-in exponential retry/backoff helper with jitter and cancellation.
 - Installed-tarball consumer smoke testing for published entrypoints.
+- Unified `ProviderAdapter` contract and `createProviderRuntime` execution entrypoint.
+- Standard text/image/video/audio/JSON outputs and normalized usage metadata.
+- Model input validation for required fields, types, options, ranges, list limits, and capabilities.
+- OpenAI-compatible and RunningHub runtime adapters.
+- Lifecycle and progress events through isolated observability hooks.
 
 ## 0.1.0 - 2026-07-08
 

README.md

@@ -43,7 +43,7 @@ Most AIGC applications eventually need the same provider infrastructure:
 npm install aigc-provider-runtime-kit
 ```
 
-The package is currently in the `0.1.x` foundation line. APIs are intentionally small and may evolve before `1.0`.
+The package is currently in the `0.2.x` runtime line. APIs may continue to evolve before `1.0`.
 
 If the package has not been published to npm in your environment yet, install directly from GitHub:
 
@@ -131,6 +131,43 @@ const response = await client.createImage({
 
 Retries are opt-in. The client retries only retryable network failures, HTTP 408/409/429 responses, and 5xx responses when a retry policy is supplied.
 
+Execute different providers through one runtime entrypoint:
+
+```ts
+import {
+  createOpenAICompatibleAdapter,
+  createOpenAICompatibleClient,
+  createProviderRegistry,
+  createProviderRuntime
+} from "aigc-provider-runtime-kit/runtime";
+
+const registry = createProviderRegistry({ providers, models });
+const openaiClient = createOpenAICompatibleClient({
+  baseUrl: "https://api.example.com/v1",
+  apiKey: process.env.PROVIDER_API_KEY
+});
+
+const runtime = createProviderRuntime({
+  registry,
+  adapters: [createOpenAICompatibleAdapter({ client: openaiClient })],
+  hooks: {
+    onEvent(event) {
+      console.log(event.type);
+    }
+  }
+});
+
+const result = await runtime.execute({
+  providerId: "openai-compatible",
+  modelId: "image-primary",
+  input: { prompt: "A cinematic tropical city" }
+});
+
+console.log(result.outputs);
+```
+
+`providerId` and `modelId` refer to registry IDs. The runtime validates configuration and input, selects an adapter, propagates cancellation/timeouts, and returns normalized outputs.
+
 Build a RunningHub execution descriptor:
 
 ```ts

docs/INDEX.md

@@ -10,6 +10,7 @@ This file is the first-hop router for `aigc-provider-runtime-kit`.
 4. Read the relevant system document:
    - `docs/systems/providers/README.md`
    - `docs/systems/runninghub/README.md`
+   - `docs/systems/runtime/README.md`
    - `docs/systems/harness/README.md`
 5. For public API usage, read `docs/getting-started.md` and `docs/api-reference.md`.
 6. Check the latest daily log under `docs/logbooks/daily/`.
@@ -22,6 +23,7 @@ This file is the first-hop router for `aigc-provider-runtime-kit`.
 | Project overview | `README.md` |
 | Provider runtime architecture | `docs/systems/providers/README.md` |
 | RunningHub architecture | `docs/systems/runninghub/README.md` |
+| Unified runtime architecture | `docs/systems/runtime/README.md` |
 | Harness verification | `docs/systems/harness/README.md` |
 | Getting started | `docs/getting-started.md` |
 | Public API reference | `docs/api-reference.md` |

docs/api-reference.md

@@ -95,6 +95,36 @@ Provide key-pool concurrency helpers against a Redis-like runtime interface.
 
 Orders enabled keys by preferred key, default key, then other enabled keys.
 
+## Unified Runtime
+
+### `createProviderRuntime(options)`
+
+Creates the unified execution entrypoint. It resolves enabled provider/model records, validates model input, selects the first supporting adapter, propagates cancellation and timeout signals, emits lifecycle events, and normalizes provider/model identity in the result.
+
+### `ProviderAdapter`
+
+Adapters implement `supports(provider, model)` and `execute(context)`. Adapter context includes provider/model definitions, validated input, cancellation signal, timeout, metadata, and a progress emitter.
+
+### `createOpenAICompatibleAdapter(options)`
+
+Adapts the OpenAI-compatible client to unified runtime results. Chat text, image URLs/base64 data, and token usage are normalized automatically. Video/audio endpoints can be supplied through `endpoints`.
+
+### `createRunningHubAdapter(options)`
+
+Adapts a RunningHub client to the unified runtime. It supports a custom `resolveRunInput` function or model `advancedConfig.runninghub` with target IDs and an input `fieldMap`.
+
+### `validateProviderExecutionInput(model, input)`
+
+Validates required fields, scalar/array types, allowed options, numeric ranges, list maximums, and declared input capabilities.
+
+### `ProviderRuntimeError` and `isProviderRuntimeError(value)`
+
+Distinguish missing/disabled configuration, provider-model mismatch, invalid input, missing adapters, adapter failures, and aborted/timed-out executions.
+
+### Runtime events
+
+An optional `hooks.onEvent` handler receives started, validated, adapter-selected, progress, success, and failure events. Hook failures are isolated and never change execution behavior.
+
 ## Stability
 
-This is a `0.1.x` foundation API. Prefer wrapping package calls behind a host-app adapter if you need long-term compatibility before `1.0`.
+This is a `0.2.x` pre-1.0 API. The unified runtime is ready for application integration, but breaking improvements remain possible before `1.0`.

docs/logbooks/daily/2026/2026-07/2026-07-10-unified-runtime.md

@@ -0,0 +1,42 @@
+# 2026-07-10 Unified Runtime
+
+## Intent
+
+Deliver the 0.2.0 unified execution layer so applications can run different providers through one validated, observable contract.
+
+## Changed
+
+| Area | Files | Purpose |
+| --- | --- | --- |
+| Runtime contracts | `packages/runtime/src/contracts.ts` | Define adapter, request, result, output, usage, progress, and event contracts |
+| Unified execution | `packages/runtime/src/runtime.ts` | Resolve configuration, validate, select adapters, execute, and normalize results |
+| Input validation | `packages/runtime/src/input-validation.ts` | Validate required fields, types, options, ranges, lists, and capabilities |
+| Built-in adapters | `packages/runtime/src/adapters.ts` | Bridge OpenAI-compatible and RunningHub clients into the unified runtime |
+| Tests | `tests/runtime.test.mjs` | Cover execution, validation, adapter selection, timeouts, hooks, mapping, and normalization |
+| Release | `package.json`, `package-lock.json`, `CHANGELOG.md` | Prepare version 0.2.0 |
+| Documentation | `README.md`, `docs/*` | Document architecture, public API, examples, and boundaries |
+
+## Verification
+
+| Check | Result |
+| --- | --- |
+| `npm run harness:verify:release` | Passed |
+| `npm test` | Passed (26 tests) |
+| Installed tarball consumer | Passed |
+| `npm audit --audit-level=high` | Passed (0 vulnerabilities) |
+
+## Decisions
+
+- Registry model IDs are the public execution identifiers; upstream model IDs remain adapter concerns.
+- Adapter clients are injected so credentials remain owned by the host application.
+- Observability hooks are isolated from execution success/failure.
+- Raw provider responses remain optional while standard outputs are always available.
+
+## Risks
+
+- Vendor-specific async video providers still need dedicated adapters or endpoint/result normalization callbacks.
+- Version 0.2.0 remains pre-1.0 and may evolve as real host applications integrate it.
+
+## Next
+
+Integrate 0.2.0 into a host application, collect provider fixtures, and add provider-specific adapters based on real demand.

docs/roadmap.md

@@ -1,6 +1,6 @@
 # Roadmap
 
-## Current Line: 0.1.x Foundation
+## Current Line: 0.2.x Unified Runtime
 
 Goal: provide stable, framework-neutral primitives that other AIGC products can reuse without copying provider-specific glue.
 
@@ -18,21 +18,25 @@ Completed:
 - OpenAI-compatible chat/image/custom JSON client.
 - Opt-in retry/backoff policy helper.
 - Installed-package consumer smoke testing.
+- Unified provider adapter and execution contracts.
+- Standard execution outputs, usage, errors, timeout/cancellation, and lifecycle events.
+- OpenAI-compatible and RunningHub runtime adapters.
+- Runtime validation for model parameters and input capabilities.
 - Harness, CI, docs, and unit tests.
 
-## 0.2.x Candidate Work
+## 0.3.x Candidate Work
 
 - Add provider adapter examples for vendor-specific video APIs.
 - Add fixtures for common RunningHub App and Workflow shapes.
 - Add idempotency-key guidance and provider-specific retry presets.
 - Add optional host-app adapter examples for Express/Fastify without making them core dependencies.
 - Add package export compatibility tests.
 
-## 0.3.x Candidate Work
+## Later Candidate Work
 
 - Add environment/file loaders around the typed provider registry.
 - Add deeper validation for admin-edited model parameter schemas.
-- Add observability hooks for audit events, timing, provider status, and retry decisions.
+- Add optional OpenTelemetry/Sentry bridge examples on top of runtime events.
 - Add more complete key-pool strategies such as weighted dispatch and cooldown windows.
 
 ## Deferred Until Explicitly Needed

docs/systems/README.md

@@ -7,6 +7,7 @@ System docs describe runtime contracts and reusable boundaries.
 | Harness | `docs/systems/harness/README.md` |
 | Providers | `docs/systems/providers/README.md` |
 | RunningHub | `docs/systems/runninghub/README.md` |
+| Unified runtime | `docs/systems/runtime/README.md` |
 | API integration | `docs/systems/api/README.md` |
 | Worker integration | `docs/systems/worker/README.md` |
 | Admin UI guidance | `docs/systems/admin/frontend-design/` |

docs/systems/runtime/README.md

@@ -0,0 +1,34 @@
+# Unified Provider Runtime
+
+## Purpose
+
+The unified runtime lets host applications execute configured models without branching on provider-specific clients.
+
+## Ownership
+
+- Code: `packages/runtime/src/`
+- Public exports: `aigc-provider-runtime-kit` and `aigc-provider-runtime-kit/runtime`
+- API reference: `docs/api-reference.md`
+- Tests: `tests/runtime.test.mjs`
+
+## Execution Flow
+
+1. Resolve the requested provider and model from the validated registry.
+2. Reject missing, disabled, or mismatched configuration.
+3. Validate input against the model parameter schema and input capabilities.
+4. Select the first adapter whose `supports` method accepts the provider/model pair.
+5. Execute with propagated timeout, cancellation, metadata, and progress events.
+6. Return standard outputs and usage while preserving optional raw provider data.
+
+## Boundaries
+
+- Adapters receive already configured clients; the runtime does not store credentials.
+- Hooks are observational and cannot break provider execution.
+- The runtime does not persist tasks, enqueue jobs, or implement permissions/billing.
+- Retries remain an explicit client/adapter policy because generation calls may not be idempotent.
+
+## Verification
+
+```bash
+npm run harness:verify:release
+```

package-lock.json

@@ -1,7 +1,7 @@
 {
   "name": "aigc-provider-runtime-kit",
-  "version": "0.1.0",
-  "description": "Provider and RunningHub runtime kit for AIGC applications: provider schemas, request builders, execution descriptors, clients, and key-pool dispatch.",
+  "version": "0.2.0",
+  "description": "Framework-neutral AIGC provider runtime with validated registries, unified adapters, standard outputs, and RunningHub/OpenAI-compatible clients.",
   "type": "module",
   "private": false,
   "license": "MIT",