tiny-runtime — agent batch and progress tools by AVRG3

tiny-runtime — API ページネーション、再試行ループ、ツールの進捗状況のための MCP ツール

エージェント開発者向けに AVRG3 が開発した、決定論的なヘルパーが3つあります。ページネーションされたジョブを完了させ、進捗のない作業の繰り返しを中断し、ツールの進捗状況をキャッシュスケジューラーに報告します。モデル呼び出し、トレーニング、アカウント、テレメトリーはありません。

バージョン 0.1.1： ライブラリ、CLI、および独立した3ツールの MCP サーバーです。モデル呼び出しやテレメトリーはありません。キャッシュブリッジを利用するには、互換性のある推論サービングとの統合が必要です。ホスト型モデルのキャッシュや標準の vLLM を単独で制御することはできません。

タスクと入力例からツールを探す · 実際のツールスキーマ · 公開インストール。

公開インストール

Node.js 20+ が必要です。npm アカウントも、ソースコードのチェックアウトも必要ありません。

Claude Code：

claude mcp add tiny-runtime -- npx -y -p https://github.com/Warddamn/tiny-tools/releases/download/runtime-v0.1.1/tiny-runtime-0.1.1.tgz tiny-runtime-mcp

Cursor、Claude Desktop、その他の stdio MCP クライアント： このサーバー設定を追加してください。VS Code では mcpServers の代わりに servers を使用します。

{"mcpServers":{"tiny-runtime":{"command":"npx","args":["-y","-p","https://github.com/Warddamn/tiny-tools/releases/download/runtime-v0.1.1/tiny-runtime-0.1.1.tgz","tiny-runtime-mcp"]}}}

MCPB 対応クライアント： ポータブルバンドルをダウンロードして開いてください。macOS、Windows、Linux 用の依存関係が含まれています。Node.js ランタイムが必要です。バンドルには署名がありませんが、リリースのチェックサムとレジストリのハッシュで整合性を検証できます。より小さい npx tarball では、インストール時にサードパーティ製の依存関係をダウンロードします。

Claude Code プラグイン： /plugin marketplace add Warddamn/tiny-tools を実行し、続けて /plugin install tiny-runtime@tiny-tools を実行します。使用方法のガイダンスも追加されます。プラグインと手動の MCP 設定のどちらかを選択してください。

回答例付きの3つの実例 · GitHub からダウンロード · 公式 MCP Registry

JavaScript/TypeScript ライブラリ： npm install https://github.com/Warddamn/tiny-tools/releases/download/runtime-v0.1.1/tiny-runtime-0.1.1.tgz で同じ公開 tarball をインストールし、@tiny_tools_pw/runtime から collectPages、RepeatGuard、または ProgressBridge をインポートします。これは GitHub でホストされているパッケージであり、npm レジストリへの登録はありません。

各部分の役割

• collect_pages / collectPages: 設定されたカーソルソースをたどり、ページ全体を検証し、任意のレコード ID で重複を除外し、整数フィールドを正確に集計して、complete、partial、または failed を返します。永続化されるチェックポイントにより、新しい実行で最後にコミットされたページの次から再開できます。
• check_progress / RepeatGuard / runGuarded: アクションを、信頼できる状態フィンガープリントと比較します。デフォルトでは、停滞が4回繰り返されるとブロックします。実際に編集が行われた後は再度テストでき、状態遷移の繰り返しも認識します。トレース分析は参考情報です。SDK ラッパーは、ツールを実行する前に判定を適用します。
• plan_cache / ProgressReporter / ProgressBridge: ツールの内容をモデルに送信せずに、計測された作業単位を報告します。残り時間を保守的に推定し、並列呼び出しをまとめて考慮して、有効期限付きの retain、prefetch、または release ヒントを出力します。ホストアダプターがヒントを適用し、MCP ツールはプランを書き込むだけです。

これらは、既知のエンジニアリング上の課題を解決するものであり、これまで存在しなかったカテゴリを作るものではありません。MCPProxy にはすでにバッチ処理やページネーションのレシピがあり、ほかのプロジェクトもループ検出やキャッシュを実装しています。このパッケージは、明示的な障害セマンティクス、再利用可能な統合、テストに重点を置いています。あらゆる MCP サーバー向けの汎用プロキシではありません。

チェックアウトから実行する

Node.js 20+ が必要です。リポジトリのルートから実行してください。

npm ci
npm run build
npm run demo:runtime
node packages/runtime/dist/cli.js collect packages/runtime/examples/collect.json --output-dir /tmp/runtime-results
node packages/runtime/dist/cli.js check packages/runtime/examples/guard-trace.json --output-dir /tmp/runtime-results
node packages/runtime/dist/cli.js plan packages/runtime/examples/progress-trace.json --output-dir /tmp/runtime-results

各ジョブは専用のディレクトリを作成し、成果物の絶対パスを返します。CLI の終了コードは、処理が成功した場合は 0、エラーまたは収集が未完了の場合は 1 です。一部のレコードとそのチェックポイントは引き続き利用できます。入力ファイルは上書きされません。対応している環境ではジョブの出力ファイルは所有者のみがアクセスできる権限で作成されますが、親ディレクトリの権限も重要です。

MCP クライアントでは、例のパスを実際のチェックアウトのパスに置き換えてください。

{"mcpServers":{"tiny-runtime":{"command":"node","args":["/absolute/path/tiny-tools/packages/runtime/dist/mcp.js"]}}}

8行の使用方法のスニペットをエージェントの指示に追加してください。追加のモデル呼び出しなしで自動実行するには、モデルにトレース分析ツールを繰り返し呼び出させるのではなく、SDK を統合してください。

バッチ収集

同梱の examples/collect.json は、ローカルの合成ページマニフェストを読み込みます。ファイルソースは pages を含むオブジェクトです。各ページにはリクエスト用の cursor（最初のページでは null）と、items および必須の nextCursor を含む page があります。ソースの処理が完了したことを示すのは、明示的な nextCursor: null のみです。次のカーソルがある場合、ページは空でもかまいません。設定内のファイルパスは、その設定ファイルからの相対パスとして解決されます。

設定された HTTP ソースは、指定されたオリジンとパスに対してのみ GET を使用します。例（ドメインはプレースホルダーであり、実在するサービスではありません）。

{
  "source": {
    "type": "http",
    "url": "https://api.example.com/records?status=open",
    "itemsPath": "data.records",
    "nextCursorPath": "pagination.next_cursor",
    "cursorParam": "cursor",
    "totalPath": "pagination.total",
    "snapshotPath": "snapshot_id",
    "bearerEnv": "RECORDS_API_TOKEN",
    "scope": "account-and-filter-identity"
  },
  "key": "id",
  "sumFields": ["amount_cents"],
  "maxPages": 100,
  "maxRecords": 10000,
  "maxBytes": 16000000,
  "timeoutMs": 30000
}

totalPath、snapshotPath、bearerEnv は任意です。設定されている場合、メタデータが欠けているとページの処理は失敗します。パスには、ドットで区切ったオブジェクト自身のキーを使用します。ドットを含むキーはサポートされていません。API のマッピングは明示的に指定し、推測はしません。返されるカーソルは、不透明なクエリーパラメーター値のままであり、URL ではありません。リダイレクトは拒否されます。認証情報はツールホストの環境に保管してください。設定ファイルやチェックポイントに、解決済みのベアラートークンが保存されることはありません。明示的にローカルテスト用エンドポイントを使用する場合を除き、HTTPS を使用してください。URL のクエリーパラメーターにシークレットを含めないでください。

不要なレコードを取得するより、プロバイダー側で集計やフィルタリングを行うことを優先してください。Link ヘッダー、オフセット、GraphQL POST、またはツール固有のプロトコルを使用する API には、小規模な SDK アダプターが必要です。

import { collectPages } from '@tiny_tools_pw/runtime';
const result = await collectPages({
  sourceId: 'account/dataset/filter/version',
  key: 'id',
  sumFields: ['amount_cents'],
  fetchPage: async (cursor, signal) => {
    const response = await yourReadOnlyClient.list({ cursor, signal });
    return { items: response.records, nextCursor: response.next ?? null };
  }
});

プロバイダーの文書化された契約で response.next が終了を意味する場合に限り、値がない response.next を null にマッピングしてください。コールバックは、独自の I/O を停止できるよう AbortSignal を尊重する必要があります。アダプターがキャンセルを無視しても、コレクターは速やかに戻りますが、任意のコールバック処理を強制終了することはできません。

CLI の収集を再開します。

node packages/runtime/dist/cli.js collect /absolute/path/job.json --checkpoint /absolute/path/tiny-runtime-abc/checkpoint.json

受理された各ページは、次のページを要求する前にチェックポイントとして保存されます。timeoutMs は収集、フェッチ、待機対象のコールバックを対象とし、ジョブのセットアップ、検証、安全なファイルシステムの最終処理には追加の時間がかかります。任意の同期コールバックを中断することはできません。また、タイムアウトしたカスタムアダプターは独自に処理を停止する必要があります。進行状況を要求する MCP クライアントには、コミット済みページの通知が送られます。キャンセルすると以降のリクエストは停止し、コミット済みの作業は保持されます。再開時には新しいディレクトリが作成され、元のチェックポイントは保持されます。maxPages は呼び出しごとの上限です。レコード数とバイト数の上限には、以前にコミットされたページも含まれます。上限を超えるページを受理するには上限を引き上げてください。コレクターがページの一部だけを保存することはありません。HTTP のデフォルトの最大レスポンスページサイズは 1 MB（ハード上限 8 MB）、レコード数は 10,000（ハード上限 100,000）、収集バイト数は 16 MB（ハード上限 64 MB）、タイムアウトは 30 秒（ハード上限 5 分）です。自動リトライ、バックオフ、並列フェッチ、ソースへの書き込みは行いません。

key を指定すると、同一の重複レコードは 1 件として数えられ、ID のバージョンが競合する場合は新しいページ全体が失敗します。key を指定しない場合、すべての行が保持されます。total が宣言されている場合、キーを使用するときはユニークなレコード数、それ以外の場合はすべての行を指す必要があり、値は一定でなければなりません。合計の計算には内部で BigInt を使用し、文字列として返します。丸めた小数ではなく、セントなどの整数の最小通貨単位、または整数文字列を使用してください。小数や統計の処理には tiny-context の query_table を使用してください。

完全性には明確な限界があります。 complete は、設定されたソースが明示的に終了し、設定されたすべてのメタデータチェックに合格したことを意味します。プロバイダーの隠れた上限、偽りの total、ソース内の欠落レコードを検出するものではありません。安定したスナップショット／合計値があると、根拠の信頼性が高まります。再開には、同じソース／マッピング／スコープと集計を使用する必要があります。アカウントやフィルターを変更した場合は、スコープを更新してください。チェックポイントの SHA-256 は偶発的な破損を検出するものであり、悪意のある改ざんを検出するものではありません。チェックポイントにはレコードとカーソルが含まれるため、ソースデータと同様に保護してください。CLI／MCP のジョブは、ページごとに変更差分を含む不変のファイルを 1 つと、小さなアトミックなコミットポインターを 1 つ書き込み、正常終了時に互換性のあるバージョン 1 のスナップショットを 1 つ書き込みます。中断されたジョブにはバージョン 2 のジャーナルが残ります。ジョブディレクトリ全体をまとめて保持し、CLI／MCP または readCheckpoint(path) を使って再開してください。以前のバージョン 1 のスナップショットも引き続き使用できます。ジャーナルの復旧では、信頼できないメタデータカウンターとは独立して、読み込む JSON の合計バイト数を 128 MB（ファイルあたり 64 MB）に制限します。SDK では、より小さい読み込み予算を指定できます。SDK ユーザーは、initialize(checkpoint) の後で new CheckpointStore(freshDirectory).save を onPage として渡せます。最終処理の前に drain() を呼び出してください。従来の onCheckpoint コールバックは引き続きスナップショットベースであり、長時間のジョブでは処理コストが高くなる場合があります。

繰り返し作業ガード

トレースは { "observations": [...], "nextAttempt": {...}, "options": {...} } の形式です。examples/guard-trace.json を参照してください。各観測には、attempt（scope、tool、JSON の args、任意の state）、outcome、任意の stateAfter が含まれます。計測したファイル／リポジトリの状態、etag、またはソースのバージョンに対して fingerprint() を使用してください。操作の成功可否を変える可能性のある依存関係をすべて含めてください。フィンガープリントが不完全だと、誤検知が起きる可能性があります。モデルが自己申告する「進捗した」という主張を根拠として受け入れないでください。

import { RepeatGuard, runGuarded, fingerprint } from '@tiny_tools_pw/runtime';
const guard = new RepeatGuard({ threshold: 3, window: 100 });
const attempt = { scope: workflowId, tool: 'run_tests', args: { suite: 'unit' }, state: fingerprint(await measuredInputs()) };
const result = await runGuarded(guard, attempt, () => runTests(), async () => fingerprint(await measuredInputs()), result => result.exitCode === 0);
if (!result.executed) reportBlocked(result.decision);

runGuarded はリトライを行わず、実行時の例外を握りつぶしません。ワークフローごとに直列で使用してください。同時呼び出しを重複排除するものではありません。信頼できる状態フィンガープリントがない場合、失敗の繰り返しに対してはアドバイスを返すだけで、ブロックはしません。ホストが承認したポーリングには repeatableTools を使用できます。信頼できるホストコードで設定してください。状態が変わっていない場合でも、読み取りの成功は許可され、直前までの失敗回数がリセットされます。状態が変われば、新しい試行が自然に許可されます。guard.clear(scope) は履歴を明示的にリセットします。スナップショットには引数や生の出力ではなく、上限付きのハッシュが含まれますが、予測可能な入力のハッシュ化は匿名化にはなりません。スナップショットを復元するには、コンストラクターの第 2 引数として渡してください。検出は上限付きのヒューリスティックであり、すべての繰り返しが不要であることを証明するものではありません。

ライブ進捗とキャッシュブリッジ

実行可能な統合例については、examples/demo.mjs を参照してください。ライブ SDK の処理経路は次のとおりです。

import { CachePlanner, ProgressReporter, ProgressBridge, httpCacheAdapter } from '@tiny_tools_pw/runtime';
const planner = new CachePlanner();
const reporter = new ProgressReporter(sessionId, uniqueCallId, event => planner.ingest(event));
const bridge = new ProgressBridge(planner, httpCacheAdapter('http://127.0.0.1:8089/cache-hints'));
reporter.report('running', 0, 100);
// Tool adapter reports actual units as work advances.
reporter.report('running', 90, 100);
await bridge.tick(Date.now(), 4); // capacity is session slots, not GPU bytes
reporter.report('done', 100, 100);
await bridge.tick(Date.now(), 4);

ブリッジは同時に発生したティックと、変更のないヒントをまとめ、確認済みのリースは有効期間の半分が経過した時点で更新します。配信の同時実行数には上限（デフォルトは 4）があり、期限は 2 秒で、リースの有効期限を上限とします。また、ディスパッチ前と確認応答後に有効期限を確認します。確認応答に失敗した場合や遅れて届いた場合は、適用済みとして報告しません。アダプターはリースの有効期限を適用し、キャンセルを尊重する必要があります。協調しないアダプターは、その作業を続行する可能性があります。HTTP アダプターでは、Unix ミリ秒単位のタイムスタンプが必要です。

作業中はホストが定期的に、完了時にもう一度 tick を呼び出します。実行環境でライフサイクルを管理してください。必ず終端イベントとして done、failed、または cancelled を報告してください。セッション ID と呼び出し ID は不透明な値にしてください。プロンプト、ファイルパス、結果、ドキュメントの内容は送信されません。タイムスタンプはコントローラーと同じミリ秒単位の時刻領域を共有します。信頼できる境界でリモートの時刻を正規化してください。イベントの呼び出しごとのシーケンス番号は単調増加します。重複したイベント、順序が前後したイベント、未来のタイムスタンプ、古いレポートは拒否されます。ID は呼び出しごとに一意でなければなりません。

残り時間を推定するには、プランナーが同じ合計値を持つ、値が増加する測定値を 2 つ必要とします。停滞、値の後退、不明な合計値、予測期限の超過が発生した場合、推定値は不明になります。finishing は完了間近であることを明示するヒントです。これを出力するのは、信頼できる計測済みコードのみにしてください。複数の呼び出しが並行している場合、最後に残ったアクティブな呼び出しが準備状態を制御します。デフォルト値は、5 秒経過で古いと判定、完了間近の判定範囲は 1 秒以内、リースは最大 2 秒、セッションは最大 1,000 件、呼び出しは最大 5,000 件です。ワークロードに応じて、適切な保持容量、ティック頻度、クォータを設定してください。

カスタムサービングアダプターの契約： httpCacheAdapter は {version:1, session, action, reason, estimatedRemainingMs, validUntilMs} を、明示的に設定されたエンドポイントに POST し、2xx レスポンスを要求します。サービング統合では、不透明なセッション ID を独自の KV キャッシュ状態に対応付け、独自のメモリ予算と認可を適用します。また、解放の通知に失敗した場合でも、validUntilMs を厳格なリース有効期限として扱います。release はこちらのヒントを取り下げるものであり、正確性に不可欠な状態を破棄してはなりません。不明または古いセッションには、エンジンの通常のポリシーが適用されます。retain と prefetch は、いずれも参考情報としての優先度であり、無制限の予約ではありません。エラーはセッションごとに返されます。POST にはタイムアウトが設定され、リダイレクトは無効です。2xx はエンドポイントが受け付けたことを示すものであり、測定済みの GPU 性能を示すものではありません。

これは当社の統合プロトコルであり、既存の vLLM API ではありません。このパッケージには GPU エンジンのパッチは含まれていません。レポーター／コントローラー／アダプター側を実装し、実際のローカル HTTP エンドポイントを使ってテストします。デプロイ時には、エンジン側を用意する必要があります。ホスト型モデルのユーザーは、通常このキャッシュを制御できません。基礎となる研究で報告されたレイテンシの改善は、この実装の結果ではありません。ツール作業単位の不均一さ、誤解を招く進捗報告、リソース競合、敵対的なセッションについては、ワークロード固有の検証とエンジンレベルのクォータが必要です。

検証とサイズ

npm testでは、ライブラリの障害、実際のローカルHTTPソース、チェックポイントからの再開、CLIの終了動作、および実際のMCP stdioクライアントを通じた3つすべてのツールをテストします。npm run demo:runtimeでは、3つすべてをまとめて確認できます。npm run bench:runtimeでは、合成データを使用して、コレクターと通常の正しいスクリプトを比較します。

この開発マシンで、合成した10,000行／100ページのデータを使って5回実行したところ、合計は同じ495,000セントでした。通常のスクリプトは0.46～1.07 ms、コレクターは30.68～39.62 msでした。ネットワーク遅延、ディスクへのチェックポイント書き込み、モデル呼び出しは含まれていません。検証にはCPUコストがかかります。この簡単なケースでは、既存の正しいスクリプトのほうが高速です。合成した障害が変化しないシナリオでは、試行した100回の呼び出しのうち3回を実行し、97回をブロックします。これはポリシーの動作を示すものであり、実環境での削減効果を測定したものではありません。このパッケージについて、トークン／APIコストの削減を測定した結果、幅広いエージェント採用の証拠、または本番環境でのGPUの測定結果は、まだありません。

新たな依存関係の系統やネイティブバイナリはありません。信頼できないデータの検証にはZodを使用し、stdioには既存の公式MCP SDKを使用します。CLIの解析にはCommanderを使用します。このサーバーはstdioのみを公開しますが、SDKの推移的なHTTPパッケージはインストールされます。実際のパッケージサイズと本番インストール時のサイズは、docs/VALIDATION.mdに記載されている新規インストール検証時に記録されます。

AVRG3製 · MIT