Harden standalone runtime kit

Author: Hhh2178

.github/workflows/ci.yml

@@ -37,3 +37,6 @@ jobs:
 
       - name: Test
         run: npm test
+
+      - name: Verify package exports
+        run: npm run test:package

CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to `aigc-provider-runtime-kit` are recorded here.
 
+## Unreleased
+
+### Fixed
+
+- Correct video-model reference image capability inference.
+- Reject unknown RunningHub task states instead of treating them as successful completion.
+
+### Added
+
+- Typed `RunningHubError` failures, bounded request/task timeouts, and task cancellation.
+- Configurable RunningHub key-pool leases.
+- Package export verification and release-safe npm package contents.
+- Tests for multipart data URLs, RunningHub execution failures/cancellation, and key-pool leases.
+
 ## 0.1.0 - 2026-07-08
 
 ### Added

README.md

@@ -29,6 +29,7 @@ Most AIGC applications eventually need the same provider infrastructure:
 - **RunningHub catalog helpers**: normalize RunningHub App/Workflow records into reusable host-app entries.
 - **Execution descriptors**: generate submit/poll/output handling metadata for RunningHub tasks.
 - **RunningHub client**: submit tasks, poll results, normalize failures, and extract image/video/audio URLs.
+- **Bounded execution**: task and request timeouts, cancellation signals, typed errors, and unknown-status protection.
 - **Key-pool concurrency**: acquire and release RunningHub keys against a Redis-like runtime interface.
 - **No framework lock-in**: works with Node.js services, workers, CLI tools, or any framework that can import ESM.
 - **Governed project harness**: includes docs, CI, tests, and verification scripts to keep the package maintainable.
@@ -130,6 +131,33 @@ const result = await client.runTask({
 console.log(result.videoUrls);
 ```
 
+Cancel a task from your host application and handle structured failures:
+
+```ts
+import {
+  createRunningHubClient,
+  isRunningHubError
+} from "aigc-provider-runtime-kit/runninghub";
+
+const controller = new AbortController();
+
+try {
+  await client.runTask({
+    targetType: "workflow",
+    runTargetId: "workflow-id",
+    workflowId: "workflow-id",
+    nodeInfoList: [],
+    signal: controller.signal
+  });
+} catch (error) {
+  if (isRunningHubError(error)) {
+    console.error(error.code, error.stage, error.retryable);
+  }
+}
+```
+
+The client defaults to a 30-minute task timeout and a 2-minute timeout per HTTP request. Override them with `taskTimeoutMs` and `requestTimeoutMs` when creating the client, or use `timeoutMs` for one task.
+
 Use key-pool helpers with a Redis-like runtime:
 
 ```ts
@@ -141,6 +169,7 @@ import {
 const acquired = await acquireRunningHubKey({
   providerId: "runninghub",
   defaultConcurrency: 2,
+  leaseSeconds: 60 * 60,
   runtime: redisLikeRuntime,
   keys: [
     {
@@ -169,6 +198,8 @@ try {
 }
 ```
 
+Choose a lease long enough for the longest expected task. Each successful acquisition refreshes the lease, and the default is one hour.
+
 ## What You Can Build With It
 
 - A multi-provider AIGC backend.
@@ -232,6 +263,7 @@ npm run harness:verify:project
 npm run type-check
 npm run build
 npm test
+npm run test:package
 ```
 
 Use the full release gate before publishing or tagging:

docs/api-reference.md

@@ -57,6 +57,12 @@ Normalizes a source catalog record into a complete RunningHub catalog item.
 
 Creates a minimal RunningHub submit/poll client. Host applications should wrap this client with their own permission, quota, credential, and audit layers.
 
+Client options include `requestTimeoutMs` for individual HTTP requests and `taskTimeoutMs` for the complete polling lifecycle. Both have bounded defaults. `runTask` also accepts a per-task `timeoutMs` and an `AbortSignal` through `signal`.
+
+### `RunningHubError` and `isRunningHubError(value)`
+
+RunningHub failures use a typed error with `code`, `stage`, optional HTTP `status`, and a `retryable` hint. Codes distinguish invalid configuration/input, cancellation, request or response failures, upstream rejection, task failure/timeout, unknown status, and missing output.
+
 ### `extractRunningHubOutputUrls(value)`
 
 Extracts image, video, and audio URLs from nested RunningHub result payloads.
@@ -65,6 +71,8 @@ Extracts image, video, and audio URLs from nested RunningHub result payloads.
 
 Provide key-pool concurrency helpers against a Redis-like runtime interface.
 
+`acquireRunningHubKey` accepts an optional `leaseSeconds` value between 30 seconds and 24 hours. Successful acquisitions refresh the counter lease.
+
 ### `orderRunningHubKeys(keys, preferredKeyId?)`
 
 Orders enabled keys by preferred key, default key, then other enabled keys.

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

@@ -0,0 +1,40 @@
+# 2026-07-10 Runtime Hardening
+
+## Intent
+
+Harden the standalone SDK so clean checkouts can build, test, package, and safely execute bounded RunningHub tasks.
+
+## Changed
+
+| Area | Files | Purpose |
+| --- | --- | --- |
+| Model metadata | `packages/core/src/model-schema.ts` | Correct video reference-image capability inference |
+| RunningHub runtime | `packages/runninghub/src/*` | Add typed errors, timeouts, cancellation, status validation, and configurable key leases |
+| Package release | `package.json`, `scripts/verify-package.mjs`, `.github/workflows/ci.yml` | Build before packing, constrain Node, limit package contents, and verify exports |
+| Tests | `tests/*.test.mjs` | Cover multipart, client, cancellation, status handling, and key-pool behavior |
+| Documentation | `README.md`, `docs/*`, `CHANGELOG.md` | Document public behavior and release guarantees |
+
+## Verification
+
+| Check | Result |
+| --- | --- |
+| `npm run harness:verify:project` | Passed |
+| `npm run type-check` | Passed |
+| `npm test` | Passed (15 tests) |
+| `npm run test:package` | Passed |
+| `npm pack --dry-run` | Passed; examples excluded |
+
+## Decisions
+
+- Keep the project a framework-neutral SDK rather than adding a hosted API, database, queue, or admin UI.
+- Preserve existing public functions while adding optional safeguards and typed error exports.
+- Use Node.js 22 as the explicit supported runtime baseline.
+
+## Risks
+
+- Upstream RunningHub response shapes may evolve and require additional fixtures.
+- Retry/backoff remains a host policy and is not automated in this change.
+
+## Next
+
+Add provider registry validation and additional provider adapters in later releases.

docs/roadmap.md

@@ -11,14 +11,16 @@ Completed:
 - Multipart request body helper.
 - RunningHub catalog and execution descriptor helpers.
 - RunningHub submit/poll client.
+- Bounded RunningHub task/request timeouts, cancellation, and typed errors.
 - RunningHub key-pool concurrency helper.
+- Package export verification and release-safe package contents.
 - Harness, CI, docs, and unit tests.
 
 ## 0.2.x Candidate Work
 
 - Add provider adapter examples for OpenAI-compatible image/video APIs.
 - Add fixtures for common RunningHub App and Workflow shapes.
-- Add error normalization helpers shared by provider clients.
+- Add retry/backoff policy helpers shared by provider clients.
 - Add optional host-app adapter examples for Express/Fastify without making them core dependencies.
 - Add package export compatibility tests.
 

docs/systems/runninghub/README.md

@@ -19,6 +19,8 @@ The RunningHub system provides reusable contracts and helpers for RunningHub AI
 4. Host worker uses `createRunningHubClient` to submit and poll.
 5. Optional key-pool helpers manage multi-key concurrency.
 
+The client applies bounded request and task timeouts, accepts an `AbortSignal`, and reports typed `RunningHubError` failures. The key pool uses a configurable concurrency lease so stale counters can recover.
+
 ## Interfaces
 
 | Interface | Direction | Contract |
@@ -33,6 +35,8 @@ The RunningHub system provides reusable contracts and helpers for RunningHub AI
 - App/workflow IDs are mixed.
 - Fields do not match upstream RunningHub node info.
 - Poll returns success with no usable output URL.
+- Poll returns an unknown status or exceeds its timeout.
+- The host aborts an in-flight task.
 - All keys are busy or no enabled keys exist.
 
 ## Verification

package.json

@@ -8,8 +8,11 @@
   "main": "./dist/packages/runtime/src/index.js",
   "types": "./dist/packages/runtime/src/index.d.ts",
   "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
   "files": [
-    "dist",
+    "dist/packages",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"
@@ -32,12 +35,14 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build",
     "type-check": "tsc -p tsconfig.json --noEmit",
     "test": "npm run build && node --test tests/*.test.mjs",
+    "test:package": "npm run build && node scripts/verify-package.mjs",
     "verify:harness": "node scripts/verify-harness.mjs",
     "harness:verify:project": "npm run verify:harness",
     "harness:verify:workspace": "npm run type-check && npm test",
-    "harness:verify:release": "npm run verify:harness && npm run type-check && npm test"
+    "harness:verify:release": "npm run verify:harness && npm run type-check && npm test && npm run test:package"
   },
   "devDependencies": {
     "typescript": "^5.5.0"

packages/core/src/model-schema.ts

@@ -62,8 +62,8 @@ export function parseInputCapabilities(value: unknown, capability: ModelCapabili
   const maxRef = Number(schema.referenceImages?.max);
   return {
     prompt: source.prompt !== false,
-    imageReference: source.imageReference === undefined ? capability === "image" && Boolean(schema.referenceImages) : Boolean(source.imageReference),
-    multiImage: source.multiImage === undefined ? capability === "image" && Number.isFinite(maxRef) && maxRef > 1 : Boolean(source.multiImage),
+    imageReference: source.imageReference === undefined ? Boolean(schema.referenceImages) : Boolean(source.imageReference),
+    multiImage: source.multiImage === undefined ? Number.isFinite(maxRef) && maxRef > 1 : Boolean(source.multiImage),
     firstFrame: Boolean(source.firstFrame),
     lastFrame: Boolean(source.lastFrame),
     mask: Boolean(source.mask),

packages/runninghub/src/client.ts

@@ -1,8 +1,12 @@
+import { RunningHubError } from "./error.js";
+
 export interface RunningHubClientOptions {
   apiKey: string;
   baseUrl: string;
   fetcher?: typeof fetch;
   wait?: (ms: number) => Promise<void>;
+  requestTimeoutMs?: number;
+  taskTimeoutMs?: number;
 }
 
 export interface RunningHubNodeInfoItem {
@@ -20,6 +24,7 @@ export interface RunningHubRunInput {
   instanceType?: string;
   pollIntervalMs?: number;
   timeoutMs?: number;
+  signal?: AbortSignal;
   onHeartbeat?: (patch: Record<string, unknown>) => void | Promise<void>;
 }
 
@@ -35,15 +40,19 @@ export interface RunningHubRunResult {
 }
 
 export function createRunningHubClient(options: RunningHubClientOptions) {
+  const apiKey = safeText(options.apiKey);
+  const baseUrl = safeText(options.baseUrl).replace(/\/+$/, "");
+  if (!apiKey) throw new RunningHubError("INVALID_CONFIGURATION", "RunningHub apiKey is required", { stage: "configuration" });
+  if (!/^https?:\/\//i.test(baseUrl)) throw new RunningHubError("INVALID_CONFIGURATION", "RunningHub baseUrl must be an HTTP(S) URL", { stage: "configuration" });
   const fetcher = options.fetcher ?? fetch;
   const wait = options.wait ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, Math.max(0, ms))));
 
   async function runTask(input: RunningHubRunInput): Promise<RunningHubRunResult> {
     const targetType = input.targetType;
     const runTargetId = safeText(input.runTargetId);
-    if (!runTargetId) throw new Error(targetType === "app" ? "RunningHub app runTargetId is required" : "RunningHub workflow runTargetId is required");
+    if (!runTargetId) throw new RunningHubError("INVALID_INPUT", targetType === "app" ? "RunningHub app runTargetId is required" : "RunningHub workflow runTargetId is required", { stage: "submit" });
+    throwIfAborted(input.signal, "submit");
 
-    const baseUrl = options.baseUrl.replace(/\/+$/, "");
     const appId = safeText(input.appId || (targetType === "app" ? runTargetId : ""));
     const workflowId = safeText(input.workflowId || (targetType === "workflow" ? runTargetId : ""));
     const submitUrl = targetType === "app"
@@ -58,18 +67,18 @@ export function createRunningHubClient(options: RunningHubClientOptions) {
           usePersonalQueue: "false"
         }
       : {
-          apiKey: options.apiKey,
+          apiKey,
           workflowId: workflowId || runTargetId,
           nodeInfoList: input.nodeInfoList,
           ...(safeText(input.instanceType) ? { instanceType: safeText(input.instanceType) } : {})
         };
 
-    const submitRaw = await postJson(fetcher, submitUrl, options.apiKey, submitBody, "submit");
+    const submitRaw = await postJson(fetcher, submitUrl, apiKey, submitBody, "submit", options.requestTimeoutMs, input.signal);
     const submitData = plainObject(targetType === "app" ? plainObject(submitRaw.data) : submitRaw.data);
     const upstreamTaskId = safeText(submitData.taskId || submitData.id || submitRaw.taskId || submitRaw.id);
     const upstreamCode = Number(submitRaw.code);
     if ((Number.isFinite(upstreamCode) && upstreamCode !== 0) || !upstreamTaskId) {
-      throw new Error(safeText(submitData.msg || submitRaw.message || submitRaw.msg, "RunningHub did not return a valid task id"));
+      throw new RunningHubError("UPSTREAM_REJECTED", safeText(submitData.msg || submitRaw.message || submitRaw.msg, "RunningHub did not return a valid task id"), { stage: "submit" });
     }
 
     await input.onHeartbeat?.({
@@ -81,13 +90,19 @@ export function createRunningHubClient(options: RunningHubClientOptions) {
     });
 
     const startedAt = Date.now();
+    const timeoutMs = normalizeTimeout(input.timeoutMs ?? options.taskTimeoutMs, 30 * 60 * 1000);
     const interval = Math.max(1000, Number(input.pollIntervalMs || 5000));
     for (;;) {
-      if (input.timeoutMs && Date.now() - startedAt > input.timeoutMs) {
-        throw new Error(`RunningHub poll timeout: ${upstreamTaskId}`);
-      }
+      throwIfAborted(input.signal, "poll");
+      if (Date.now() - startedAt >= timeoutMs) throw taskTimeout(upstreamTaskId);
       await wait(interval);
-      const pollRaw = await postJson(fetcher, queryUrl, options.apiKey, { taskId: upstreamTaskId }, "poll");
+      throwIfAborted(input.signal, "poll");
+      if (Date.now() - startedAt >= timeoutMs) throw taskTimeout(upstreamTaskId);
+      const pollRaw = await postJson(fetcher, queryUrl, apiKey, { taskId: upstreamTaskId }, "poll", options.requestTimeoutMs, input.signal);
+      const pollCode = Number(pollRaw.code);
+      if (Number.isFinite(pollCode) && pollCode !== 0) {
+        throw new RunningHubError("UPSTREAM_REJECTED", safeText(pollRaw.msg || pollRaw.message, `RunningHub poll rejected with code ${pollCode}`), { stage: "poll" });
+      }
       const status = safeText(pollRaw.status || plainObject(pollRaw.data).status).toUpperCase();
       const message = safeText(pollRaw.errorMessage || pollRaw.msg || pollRaw.message || plainObject(pollRaw.data).message);
       await input.onHeartbeat?.({
@@ -101,12 +116,17 @@ export function createRunningHubClient(options: RunningHubClientOptions) {
 
       if (["RUNNING", "PENDING", "QUEUED", "WAITING"].includes(status)) continue;
       if (["FAILED", "ERROR", "CANCELLED", "CANCELED"].includes(status)) {
-        throw new Error(message || `RunningHub task failed: ${upstreamTaskId}`);
+        throw new RunningHubError("TASK_FAILED", message || `RunningHub task failed: ${upstreamTaskId}`, { stage: "poll" });
       }
 
       const urls = extractRunningHubOutputUrls(targetType === "app" ? pollRaw.results || pollRaw.data || pollRaw : pollRaw.data || pollRaw);
-      if (urls.imageUrls.length === 0 && urls.videoUrls.length === 0 && urls.audioUrls.length === 0) {
-        throw new Error(message || "RunningHub task completed without usable outputs");
+      const completed = ["SUCCESS", "SUCCEEDED", "COMPLETED", "DONE", "FINISHED"].includes(status);
+      const hasOutput = urls.imageUrls.length > 0 || urls.videoUrls.length > 0 || urls.audioUrls.length > 0;
+      if (!completed && !hasOutput) {
+        throw new RunningHubError("UNKNOWN_TASK_STATUS", `RunningHub returned unknown task status: ${status || "<empty>"}`, { stage: "poll" });
+      }
+      if (!hasOutput) {
+        throw new RunningHubError("MISSING_OUTPUT", message || "RunningHub task completed without usable outputs", { stage: "result" });
       }
       return {
         adapter: "runninghub",
@@ -122,22 +142,30 @@ export function createRunningHubClient(options: RunningHubClientOptions) {
   return { runTask };
 }
 
-async function postJson(fetcher: typeof fetch, url: string, apiKey: string, body: Record<string, unknown>, stage: string) {
-  const response = await fetcher(url, {
+async function postJson(fetcher: typeof fetch, url: string, apiKey: string, body: Record<string, unknown>, stage: "submit" | "poll", timeoutMsValue?: number, signal?: AbortSignal) {
+  const timeoutSignal = AbortSignal.timeout(normalizeTimeout(timeoutMsValue, 120000));
+  const requestSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+  let response: Response;
+  try {
+    response = await fetcher(url, {
     method: "POST",
     headers: {
       "content-type": "application/json",
       authorization: `Bearer ${apiKey}`
     },
     body: JSON.stringify(body),
-    signal: AbortSignal.timeout(120000)
-  });
+      signal: requestSignal
+    });
+  } catch (cause) {
+    if (signal?.aborted) throw new RunningHubError("REQUEST_ABORTED", `RunningHub ${stage} aborted`, { stage, cause });
+    throw new RunningHubError("REQUEST_FAILED", `RunningHub ${stage} request failed`, { stage, retryable: true, cause });
+  }
   const text = await response.text();
-  if (!response.ok) throw new Error(`RunningHub ${stage} failed ${response.status}: ${text.slice(0, 500)}`);
+  if (!response.ok) throw new RunningHubError("REQUEST_FAILED", `RunningHub ${stage} failed ${response.status}: ${text.slice(0, 500)}`, { stage, status: response.status, retryable: response.status === 429 || response.status >= 500 });
   try {
     return text ? JSON.parse(text) as Record<string, unknown> : {};
   } catch {
-    throw new Error(`RunningHub ${stage} returned invalid JSON`);
+    throw new RunningHubError("INVALID_RESPONSE", `RunningHub ${stage} returned invalid JSON`, { stage });
   }
 }
 
@@ -186,3 +214,16 @@ function safeText(value: unknown, fallback = "") {
   if (typeof value === "number" || typeof value === "boolean") return String(value);
   return fallback;
 }
+
+function normalizeTimeout(value: number | undefined, fallback: number) {
+  if (!Number.isFinite(value)) return fallback;
+  return Math.max(1, Math.round(value as number));
+}
+
+function throwIfAborted(signal: AbortSignal | undefined, stage: "submit" | "poll") {
+  if (signal?.aborted) throw new RunningHubError("REQUEST_ABORTED", `RunningHub ${stage} aborted`, { stage, cause: signal.reason });
+}
+
+function taskTimeout(upstreamTaskId: string) {
+  return new RunningHubError("TASK_TIMEOUT", `RunningHub poll timeout: ${upstreamTaskId}`, { stage: "poll", retryable: true });
+}