@h-ai/runner 0.0.0-stage → 1.0.0-beta.24

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [2026] [idealworld.group]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.en.md

@@ -0,0 +1,79 @@
+# @h-ai/runner
+
+Runner hosts managed agent and tool containers. API nodes submit work and read status. Executor nodes claim work and own the containers and connections. A shared database holds tasks, ownership, cancellation requests, and events. The application authenticates users and applies business authorization.
+
+## Start and submit
+
+Initialize `@h-ai/reldb` before Runner. A single node can use SQLite. Multiple instances use shared PostgreSQL or MySQL with a stable nodeId per executor. API nodes can set `executor: false`. This example assumes the database is ready and uses a trusted server-side handler.
+
+```ts
+import { core } from '@h-ai/core'
+import { runner } from '@h-ai/runner'
+
+const scope = { tenantId: 'studio', userId: 'alice' }
+const started = await runner.init({ nodeId: 'worker-east' })
+if (!started.success)
+  throw new Error(started.error.message)
+
+try {
+  const registration = runner.register('report.v1', async (input, context) => {
+    const published = await context.emit({ phase: 'ready' })
+    if (!published.success)
+      throw new Error(published.error.message)
+    return { summary: input }
+  })
+  if (!registration.success)
+    throw new Error(registration.error.message)
+  const accepted = await runner.submit({
+    scope,
+    kind: 'report.v1',
+    idempotencyKey: 'report-2026-11',
+    input: 'Monthly report',
+  })
+  if (!accepted.success)
+    throw new Error(accepted.error.message)
+
+  const task = await runner.get(scope, accepted.data.id)
+  if (!task.success)
+    throw new Error(task.error.message)
+  void task.data.status
+}
+finally {
+  const closed = await runner.close()
+  if (!closed.success)
+    core.logger.error('Runner shutdown failed', { code: closed.error.code })
+}
+```
+
+Use `get` for status, `find` to recover a receipt by scope and idempotency key, `events` for paged sequence cursors, and `cancel` to request cancellation. The cancelled state is published after the container is stopped and cleanup is verified. A child task's `parentId` routes it to the node holding the connection. Child tasks have a separate control concurrency limit.
+
+## Container environments and resources
+
+Each `environments` entry supplies an ID, a locally available image digest, CPU cores, memory MiB, PID count, and scratch MiB. Callers select the environment by `environmentId` and can request lower limits. Executors claim work and reserve resources in the same database transaction. Queue and concurrency limits apply by scope and node.
+
+Reserve separate tool capacity with `toolCapacity` so tools can run while agent workers hold their slots. The default tool budget is 1 CPU core, 1024 MiB of memory, 128 PIDs and 512 MiB of scratch. `toolMaxRunning` defaults to 4. The host must support both partitions. Trusted callers select `capacityClass: "tool"` and can set a cross-node service cap with `concurrency: { key, limit }`.
+
+Handlers use `context.start` to obtain process streams and exit information. Images require Linux cgroup v2 support, `/bin/sh`, and support for UID/GID 1000. The root filesystem is read-only. Runner assigns bounded tmpfs mounts at `/state`, `/workspace`, and `/tmp`, and copies launch files into `/state`. Networking is disabled by default. A registered internal network must pass the engine's internal-network check. Networked tasks should use a gateway configured for their trust boundary.
+
+The executor holds credentials and native connections in memory. Inputs, events, and outputs accept bounded JSON. Pass business identifiers and object references in execution records. When an owner disappears or cleanup cannot be verified, Runner preserves the `unknown` state and resource reservation pending operator reconciliation.
+
+Tool handlers can stage canonical Base64 files by basename in read-only `/input` using `inputs`. While the container is running, `artifact(name, maxBytes)` reads a regular file from `/output`. Total inputs and a single output are each limited to 50 MiB and remain subject to the scratch limit. Images that export artifacts provide `/usr/bin/python3`.
+
+A trusted operator endpoint on the original execution node can call `runner.reconcileUnknown(scope, id, { operatorId, reason })`. Runner verifies the recorded engine and container, checks that the container is gone, and cleans up the recorded staging directory before releasing the reservation and reuse key. It records the operator decision and adds `reconciledAt` to the original `unknown` receipt. Executions without a reliable container receipt retain their reservations.
+
+For a fixed offline tool, register the same `registerWarmPool({ key, kind, environmentId, minReady, maxRunning, maxTotal })` on API and executor nodes. `minReady` targets empty containers across the cluster. `maxTotal` counts starting, ready, running, cleaning and unreconciled instances. Trusted tool requests select `warmPool: true` with the matching service concurrency key. Runner stages authorized input only after claiming a clean instance. Each instance runs one job and is destroyed. The image provides `/usr/bin/python3`, and standby containers consume reserved tool resources.
+
+## Development
+
+```bash
+pnpm --filter @h-ai/runner typecheck
+pnpm --filter @h-ai/runner lint
+pnpm --filter @h-ai/runner build
+pnpm --filter @h-ai/runner test
+```
+
+Tests use real SQLite, PostgreSQL, MySQL, and Docker/Podman containers. Set `HAI_TEST_CONTAINER_ENGINE` to select an engine. The PostgreSQL and MySQL tests use Testcontainers with that engine's Docker-compatible API.
+
+## License
+
+Apache-2.0

package/README.ja.md

@@ -0,0 +1,79 @@
+# @h-ai/runner
+
+Runner はエージェントとツールのコンテナを管理します。API ノードはタスクを登録して状態を取得し、実行ノードはタスクを取得してコンテナと接続を管理します。タスク、所有権、キャンセル要求、イベントは共有データベースに保存します。認証と業務上の認可はアプリケーションが行います。
+
+## 起動とタスクの登録
+
+Runner より先に `@h-ai/reldb` を初期化します。単一ノードでは SQLite を使用できます。複数ノードは共有 PostgreSQL または MySQL を使用し、実行ノードごとに固定の nodeId を設定します。API ノードは `executor: false` を指定できます。以下では、データベースが起動済みで、信頼できるサーバー側ハンドラーを使用します。
+
+```ts
+import { core } from '@h-ai/core'
+import { runner } from '@h-ai/runner'
+
+const scope = { tenantId: 'studio', userId: 'alice' }
+const started = await runner.init({ nodeId: 'worker-east' })
+if (!started.success)
+  throw new Error(started.error.message)
+
+try {
+  const registration = runner.register('report.v1', async (input, context) => {
+    const published = await context.emit({ phase: 'ready' })
+    if (!published.success)
+      throw new Error(published.error.message)
+    return { summary: input }
+  })
+  if (!registration.success)
+    throw new Error(registration.error.message)
+  const accepted = await runner.submit({
+    scope,
+    kind: 'report.v1',
+    idempotencyKey: 'report-2026-11',
+    input: 'Monthly report',
+  })
+  if (!accepted.success)
+    throw new Error(accepted.error.message)
+
+  const task = await runner.get(scope, accepted.data.id)
+  if (!task.success)
+    throw new Error(task.error.message)
+  void task.data.status
+}
+finally {
+  const closed = await runner.close()
+  if (!closed.success)
+    core.logger.error('Runner shutdown failed', { code: closed.error.code })
+}
+```
+
+`get` は状態を取得し、`find` は主体と冪等キーから受付済みタスクを検索します。`events` はカーソルでページングし、`cancel` はキャンセル要求を登録します。コンテナの停止と後処理を確認してからキャンセル済み状態を保存します。`parentId` を指定した子タスクは接続を持つノードで実行され、専用の同時実行枠を使用します。
+
+## コンテナ環境とリソース
+
+`environments` には ID、取得済みのイメージダイジェスト、CPU コア数、メモリ MiB、PID 数、作業領域 MiB を指定します。`environmentId` で環境を選び、必要に応じてリソース上限を下げられます。実行ノードは、同じデータベーストランザクションでタスクを取得してリソースを確保します。
+
+エージェントが実行枠を使用している間もツールを起動できるように、`toolCapacity` でツール専用の枠を確保します。既定値は CPU 1 コア、メモリ 1024 MiB、PID 128 個、作業領域 512 MiB です。`toolMaxRunning` の既定値は 4 です。ホストは両方の枠に対応する必要があります。信頼できる呼び出し元は `capacityClass: "tool"` を指定し、`concurrency: { key, limit }` でサービスのノード横断上限を設定できます。
+
+ハンドラーは `context.start` でコンテナを起動し、標準ストリームと終了結果を取得します。Linux cgroup v2、`/bin/sh`、UID/GID 1000 での実行が必要です。ルートファイルシステムは読み取り専用で、`/state`、`/workspace`、`/tmp` は容量を制限した tmpfs です。起動ファイルは `/state` にコピーします。ネットワークは既定で無効です。使用する内部ネットワークは、実行エンジンで internal として設定し、信頼境界に応じたゲートウェイを用意します。
+
+資格情報と接続は実行ノードで管理します。入力、イベント、出力はサイズ制限付き JSON とし、実行記録には業務 ID とオブジェクト参照を渡します。所有者に接続できない場合や後処理を確認できない場合は `unknown` とし、運用者が確認するまでリソースを保持します。
+
+ツールハンドラーは `inputs` に Base64 ファイルと単純なファイル名を指定し、読み取り専用の `/input` に配置できます。コンテナの実行中に `artifact(name, maxBytes)` で `/output` の通常ファイルを取得できます。入力の合計と単一の出力はそれぞれ 50 MiB 以内で、作業領域の上限も適用されます。成果物の取得にはイメージに `/usr/bin/python3` が必要です。
+
+元の実行ノード上の信頼できる管理エンドポイントは `runner.reconcileUnknown(scope, id, { operatorId, reason })` を呼び出せます。Runner は記録済みのエンジンとコンテナを確認し、コンテナが削除され、作業ディレクトリを後処理できた場合に実行枠と再利用キーを解放します。担当者の判断を記録し、元の `unknown` に `reconciledAt` を追加します。信頼できるコンテナの受付情報がなければ実行枠を保持します。
+
+固定のオフラインツールでは、API ノードと実行ノードに同じ `registerWarmPool({ key, kind, environmentId, minReady, maxRunning, maxTotal })` を登録します。`minReady` はクラスター全体の空コンテナの目標数です。`maxTotal` には起動、待機、実行、後処理、未確認のインスタンスが含まれます。信頼できるリクエストは、サービスの同時実行キーと `warmPool: true` を指定します。空のインスタンスを取得してから認可済み入力を配置し、1 回の実行後に破棄します。イメージには `/usr/bin/python3` が必要で、待機中もツール専用枠を使用します。
+
+## 開発とテスト
+
+```bash
+pnpm --filter @h-ai/runner typecheck
+pnpm --filter @h-ai/runner lint
+pnpm --filter @h-ai/runner build
+pnpm --filter @h-ai/runner test
+```
+
+テストは実際の SQLite、PostgreSQL、MySQL と Docker/Podman コンテナを使用します。`HAI_TEST_CONTAINER_ENGINE` でエンジンを選びます。PostgreSQL と MySQL のテストは、エンジンの Docker 互換 API に Testcontainers で接続します。
+
+## ライセンス
+
+Apache-2.0

package/README.md

@@ -1,3 +1,79 @@
-# Temporary Holding Version
+# @h-ai/runner
 
-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.
+Runner 用于运行受管的 Agent 和工具容器。API 节点提交任务和读取状态，执行节点领取任务，持有实际容器和连接。任务、归属、取消请求和事件保存在共享数据库中。应用负责身份验证和业务授权。
+
+## 启动和提交
+
+先初始化 `@h-ai/reldb`，再启动 runner。单机可以使用 SQLite。多实例使用共享 PostgreSQL 或 MySQL，并为每台执行节点分配稳定的 nodeId。API 节点可以设置 `executor: false`。以下示例使用已启动的数据库，仅运行可信服务器处理器。
+
+```ts
+import { core } from '@h-ai/core'
+import { runner } from '@h-ai/runner'
+
+const scope = { tenantId: 'studio', userId: 'alice' }
+const started = await runner.init({ nodeId: 'worker-east' })
+if (!started.success)
+  throw new Error(started.error.message)
+
+try {
+  const registration = runner.register('report.v1', async (input, context) => {
+    const published = await context.emit({ phase: 'ready' })
+    if (!published.success)
+      throw new Error(published.error.message)
+    return { summary: input }
+  })
+  if (!registration.success)
+    throw new Error(registration.error.message)
+  const accepted = await runner.submit({
+    scope,
+    kind: 'report.v1',
+    idempotencyKey: 'report-2026-11',
+    input: 'Monthly report',
+  })
+  if (!accepted.success)
+    throw new Error(accepted.error.message)
+
+  const task = await runner.get(scope, accepted.data.id)
+  if (!task.success)
+    throw new Error(task.error.message)
+  void task.data.status
+}
+finally {
+  const closed = await runner.close()
+  if (!closed.success)
+    core.logger.error('Runner shutdown failed', { code: closed.error.code })
+}
+```
+
+`get` 读取当前状态，`find` 按主体和幂等键恢复回执，`events` 按序号分页，`cancel` 记录取消请求。只有确认容器停止且清理成功后才发布取消终态。处理器的停止信号来自持久控制状态。父任务通过 `parentId` 将子任务路由到持有连接的节点，子任务使用单独的控制并发额度。
+
+## 容器环境与资源
+
+启动时配置 `environments`，每项提供 ID、已预拉取的镜像 digest、CPU 核数、内存 MiB、PID 数和临时盘 MiB。调用方通过 `environmentId` 选环境，并可请求更低的资源限制。执行节点在同一数据库事务内领取任务并预留资源。按主体和节点设置队列与并发上限。
+
+为防止 Agent Worker 占满节点后工具无法运行，使用 `toolCapacity` 独立预留工具资源。默认预留 1 核 CPU、1024 MiB 内存、128 个 PID 和 512 MiB 临时盘，`toolMaxRunning` 默认为 4。宿主总预算须覆盖两个分区。可信处理器通过 `capacityClass: "tool"` 使用该分区，`concurrency: { key, limit }` 为同一类服务设置跨节点并发上限。
+
+处理器通过 `context.start` 启动容器，取得标准输入、输出、错误流和退出结果。镜像应支持 Linux cgroup v2，使用 `/bin/sh`，并能以 UID/GID 1000 运行。根文件系统只读。`/state`、`/workspace` 和 `/tmp` 按任务分配受限 tmpfs。启动文件复制到 `/state`。节点上已登记的内部网络必须通过引擎的 internal 检查，默认完全禁用容器网络。联网任务应使用按信任域配置的内部网关。
+
+启动环境和原生连接留在执行节点。输入、事件、输出只接受有界 JSON。密钥由可信处理器在启动时解析，调用记录使用业务标识和对象引用。执行节点失联或清理无法确认时保留 `unknown` 状态和预留额度，待运维核实实际容器和外部副作用。
+
+工具处理器可用 `inputs` 将规范 Base64 文件按简单文件名写入只读 `/input`，并在容器仍运行时调用 `artifact(name, maxBytes)` 从 `/output` 读取普通文件。输入总量和输出各最多 50 MiB，同时受环境临时盘限制。用于产物导出的镜像应提供 `/usr/bin/python3`。
+
+原执行节点的可信管理入口可以调用 `runner.reconcileUnknown(scope, id, { operatorId, reason })`。Runner 读取启动前保存的容器及引擎身份，确认容器已经移除并清理同一暂存目录后才释放预算和复用键，同时保存审核记录。原回执仍为 `unknown`，并增加 `reconciledAt`。缺少可信容器回执的任务继续保留预算。
+
+固定离线工具可在 API 与执行节点登记相同的 `registerWarmPool({ key, kind, environmentId, minReady, maxRunning, maxTotal })`。`minReady` 是全体执行节点的空容器目标，`maxTotal` 包含启动、等待、执行、清理和未核验实例。可信工具请求同时指定 `warmPool: true` 和对应服务并发键。领取前容器没有用户输入，领取成功后才写入授权文件。每个实例只执行一个作业，之后销毁。镜像需提供 `/usr/bin/python3`；预热会消耗工具预留资源。
+
+## 开发测试
+
+```bash
+pnpm --filter @h-ai/runner typecheck
+pnpm --filter @h-ai/runner lint
+pnpm --filter @h-ai/runner build
+pnpm --filter @h-ai/runner test
+```
+
+测试包含真实 SQLite、PostgreSQL、MySQL 及 Docker/Podman 容器。通过 `HAI_TEST_CONTAINER_ENGINE` 指定容器引擎。PostgreSQL 与 MySQL 测试通过 Testcontainers 连接同一引擎提供的 Docker 兼容 API。
+
+## 许可证
+
+Apache-2.0