mcpField
O
once

once

ローカル
github.com/stringsofthemind-oss開発ツール03 週間前に更新
リポジトリ

once について

Onceは、エージェントによる重要な外部書き込みを保護する開発者向けツールです。操作ID、永続状態、信頼できる照合により、結果が不明な場合の無条件な再試行を防ぎます。MCPサーバーでローカル実行の安全機能を提供します。

主な機能

  1. 01操作IDによる重複書き込み防止
  2. 02確定済み結果の再利用
  3. 03不明な結果での再試行ブロック
  4. 04プロバイダーの確定情報との照合
  5. 05ツールセットの分類と保護
  6. 06読み取り専用の評価コマンド

活用シーン

  1. 01タイムアウト後の返金重複を防止
  2. 02予約やメッセージの再書き込みを防止
  3. 03結果不明の操作を照合
  4. 04エージェントツールの書き込みリスクを評価

MCP 対応

Claude CodeやCursorなどのMCPクライアント向けに、重要な書き込みの冪等性と安全な再試行を支援するMCPサーバーを提供します。ツール実行には永続的なローカルSQLite状態が必要で、結果不明時は再ディスパッチをブロックします。

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

mcp.json · 共通設定
{
  "mcpServers": {
    "stringsofthemind-oss-once": {
      "command": "npx",
      "args": [
        "-y",
        "@once-agent/mcp"
      ],
      "env": {
        "ONCE_API_KEY": "<ONCE_API_KEY>"
      }
    }
  }
}
起動コマンドnpx -y @once-agent/mcp
設定が必要な環境変数
ONCE_API_KEYシークレットOptional key for Cloud checks. Without it once_verify_connection reports Cloud unconfigured/unverified and preserves local diagnostics.

ローカルサーバーにはマシン上の実行環境（Node.js 18 以上など）が必要です。設定ファイルの場所はクライアントごとに異なります。

パッケージ
npm@once-agent/mcp0.2.1

ツール

8

掲載時のツール一覧 · 3 週間前に更新

パラメーター型必須説明
projectPathstringいいえプロジェクトディレクトリの絶対パスまたは相対パス。デフォルトでは MCP サーバーの作業ディレクトリを使用します。
includeEstimatesbooleanいいえレポートに Once スキャナーの推定値を含めます。

詳細

Once：エージェントが返金を送信しました。応答は消失しました。再試行すべきでしょうか？

呼び出し元が応答を受け取る前に、プロバイダーがアクションを確定することがあります。無条件に再試行すると、返金が二重に行われる可能性があります。Once は、1 つの論理操作を記録し、確認済みの結果を再生し、元の結果が不明な間は別の書き込みをブロックします。

5 分以内に動作を確認する

Node.js 24.15+。アカウント、API キー、金融取引は不要です。この実証では、公開済み SDK と、独自の効果ジャーナルを備えた、制御されたローカル HTTP プロバイダーを使用します。

このチェックアウトから：

npm install --no-save --package-lock=false @once-agent/[email protected]
node examples/first10/prove.mjs

WITHOUT ONCE: acknowledgement lost; fresh-process retry -> 2 provider writes
CONFIRMED: 1 provider write; restart replay; changed £50 -> £80: CONFLICT, 0 additional writes
RETRY BLOCKED — ORIGINAL OUTCOME UNKNOWN
The refund may already have succeeded. Once sent no second request.
LOST-ACK: 1 provider write; UNKNOWN -> CONFIRMED; recovered refund_1
PASS

各段階で、別個のプロバイダーの HTTP カウンターとその効果ジャーナルを照合します。証拠は、出力されたディレクトリに保持されます。これは制御されたフィクスチャの実証であり、実際の決済プロバイダーの実証ではありません。手順、ダウンロード先、録画方法の詳細。

独自の操作を保護する

自然な配置：wrapTool は、ホストが所有する非同期コールバックを置き換えます。ID と効果フィールドは明示的に指定して所有します。意味上の判断が暗黙に推測されることはありません。

import { wrapTool } from "@once-agent/sdk";
const safeRefund = wrapTool(refundCustomer, {
  operationId: x => `${x.tenantId}:refund:${x.refundIntentId}`,
  effect: x => ({ tool: "payments:reviewed-account:refund", args: x }),
  statePath: "./durable/operations.sqlite",
  reconcile: lookupAuthoritativeRefund,
});

コールバックと照会関数は、レビュー済みのプロバイダー関数です。すべての引数を確認し、完全なアカウント／テナント権限と、効果をもたらすすべてのフィールドをバインドし、Authorization 認証情報は除外してください。すべての書き込みをラッパー経由で実行してください。内部のコールバック再試行は、この境界の対象外です。照会関数は、プロバイダーの信頼できる情報源に基づく場合にのみ {status: "CONFIRMED", result} を返し、それ以外の場合は {status: "UNKNOWN"} を返します。未対応の場合は照合を省略してください。そうすると UNKNOWN はブロックされたままになります。

ローカル SQLite には、1 台のマシン上の永続的な共有ファイル、Node 24.15+、および実際に新しい意図ごとの異なる ID が必要です。正当な部分返金を複数回行う場合は、返金意図 ID をそれぞれ別にする必要があります。統合ガイドの詳細。

台帳は実行権限の一部です。台帳の変更、削除、置換、リセット、ロールバック、または有効な別の台帳への切り替えによって、効果が再度実行される可能性があります。同じファイルシステムパスであることは、履歴が同一である証明にはなりません。新規プロビジョニングと再起動は別のものです。元の一貫性のある SQLite 状態を保持し、存在するはずの状態が欠落している場合は再初期化しないでください。UNKNOWN によるブロックでは、失われた履歴は修復されません。MCP の互換性と継続性を参照してください。

Once が必要な場合と、不要な場合

重大な外部書き込みが再試行される可能性があり、結果が曖昧になり得て、別の効果が問題となる場合は、Once の使用を検討してください。返金、予約、メッセージ、チケットは例であり、プロバイダーが自動的に対応することを意味するものではありません。

プロバイダーの冪等性キーで操作が完全に解決するなら、それを使用してください。Postgres の一意制約で完全に解決するなら、それを使用してください。繰り返しても問題がないなら、おそらく Once は不要です。Once を使用する場合でも、ネイティブの冪等性は維持してください。Once は、データベース、フレームワーク、キュー、Temporal の代わりにはならず、あらゆる状況での厳密に 1 回の実行を保証するものでもありません。

UNKNOWN は保護です： 元のアクションは成功している可能性があります。その ID と永続的な状態を保持し、信頼できる読み取り専用の照会を行ってください。進行を強制するために新しい ID を発行したり、Once を迂回したりしてはいけません。存在しないという観測結果が得られても、ローカルでの再送信が自動的に許可されるわけではありません。

LangGraph チェックポイントのリプレイに関する証拠

決定論的な ローカル LangGraph JS チェックポイントのリプレイでは、最初のツール呼び出しがまだ実行中の間に、同じチェックポイントを 2 回再開しました。保護なしの経路では プロバイダーへの副作用が 2 件発生し、Once で保護した経路では 1 件でした。件数は、公開済み SDK 0.1.25 を使用した別個のループバック HTTP プロバイダーの追記専用ログから集計しました。

制限事項： これは LangGraph Cloud での再現ではなく、報告されている約 180 秒のスイーパーのテストでもありません。保護には、永続化された共有 同一マシン上の SQLite オーソリティを 1 つ使用しました。別個の一時的な Cloud 台帳は、この証拠の対象外です。普遍的な exactly-once の主張や、Cloud のバグ修正が立証されたわけではありません。

再現を実行して確認する · 統合済みの証明 PR #295 · 範囲を限定した Cloud テストに協力する。独立した Cloud の証拠は引き続き求めています。ローカルのフィクスチャが PASS しても、採用を意味するものではありません。

候補を見つける

SDK 0.1.25 には、読み取り専用の once check [directory] と、制御された返金フィクスチャ用の once prove が含まれています。1 コマンドで証明するには、npx --yes --package=@once-agent/[email protected] once prove を実行してください。詳細な評価には、引き続き once doctor を使用できます。スキャンやインストールによって保護が有効になることはありません。フィクスチャがユーザーのコードを実行することもありません。

ウェブサイト · クイックスタート · 証拠 · FIRST 10 の計画と台帳

詳細なセマンティクス、統合、アーキテクチャ、過去の証拠

@once-agent/sdk

自然な配置（SDK 0.1.24 で導入）： wrapTool(callback, semantics) は、既存のローカル安全エンジンを使用して、ホストが所有するツールコールバックを保護します。安定した論理 ID、完全な副作用とアカウントのバインディング、権威ある照合を指定してください。 Node.js 24.15 以降と、同一マシン上の耐久性のある SQLite オーソリティが 1 つ必要です。UNKNOWN の場合、再ディスパッチはブロックされます。コールバックの不透明な再試行と、コネクター経由のみのモデルアクセスは、 この境界の対象外です。統合例をご覧ください。

自動 Connect： @once-agent/[email protected] では、テスト済みの @once-agent/sdk/connect パスが公開されています。対応するエージェントツールを BYPASS、PROTECT、またはフェイルクローズの UNKNOWN に分類し、信頼できる論理 ID と副作用の バインディングを使用して、ローカルツールレジストリ全体を接続します。また、 OpenAI Agents FunctionTool の直接ラップも含まれています。自動 Connect ガイドを ご覧ください。

ローカル保護： protectLocal は、API キーや登録済みプロバイダーなしで、既存の非同期関数を 1 台のマシン上で保護します。@once-agent/sdk で利用できます。正確な 安全境界と最初の副作用件数チェックについては、 ローカル関数ガイドをご覧ください。

まずはこちら： ゲートなしの再試行シミュレーションを実行するか、 最初のアクションをローカルで保護して確認する。 シミュレーションは SDK を実行しません。ローカルガイドでは、インストール済みの SDK と制御された フェイクプロバイダーを使用し、新規プロセスと UNKNOWN のチェックも行います。

Once — AI エージェントの実行安全性

重要な AI エージェントの書き込み処理における、MCP の冪等性と安全な再試行。

Once は、タイムアウトが不明確な場合、応答が失われた場合、再試行した場合に発生し得る危険な重複実行から、サポート対象の返金、予約、支払いなど、外部から確認できる副作用を保護します。

既存の OpenAI／Claude プラグインランチャーは、以前にレビューされた MCP 0.1.5 に固定されたままです。この MCP リリースでは、新しいプラグインはリリースされず、非公開の実験的な GitHub アダプターも有効になりません。

  • MCP Registry：io.github.stringsofthemind-oss/once
npx -y @once-agent/mcp

エージェントが外部状態を変更でき、不明確な結果の後に再試行する可能性がある場合は、Once の評価をご検討ください。

エージェントツールの自動保護

すでにエージェントツールレジストリまたは関数ツールリストを持つアプリケーションでは、 自動 Connect によって、手動でツールごとにルーティングする連携方式から、 ツールセット全体の評価とフェイルクローズ方式の接続へ移行できます。

import {
  connectLocalAgentToolsetAuto
} from "@once-agent/sdk/connect";

現在サポートされている経路では、明らかな読み取り／検索／生成を BYPASS、明らかに重要な変更を伴う操作を PROTECT、意味が不明確または 矛盾している場合を UNKNOWN に分類できます。UNKNOWN が Once の バイパスを許可するものとして扱われることはありません。保護対象のツールには、 信頼できる論理的なアクション ID と完全な効果のバインディングが引き続き必要です。 自動ローカル保護では、Node.js 24.15+ の永続性のある同一マシン上の SQLite を 使用します。複数ホストでの保証でも、あらゆる状況における厳密に 1 回の実行保証でもありません。

公開済みの経路では、connectOpenAIAgentsFunctionToolsAuto による OpenAI Agents FunctionTools の構造的なラップも提供されます。Once SDK の実行時依存関係に @openai/agents を追加することはありません。

フレームワークをまたいだ再現

異なるフレームワーク。異なる再試行の仕組み。同じ 1 回の効果という不変条件。

Once のフレームワークに依存しない安全境界を、独立した実行モデルと再試行の仕組みを使って検証しています。

検証ラボ障害境界保護なしOnce を使用
LangGraph 敵対的再試行ラボStateGraph + SqliteSaver、プロセスの強制終了、新しいプロセスでの再開素朴な再試行では、外部効果が 2 回発生する可能性があります外部効果は 1 回。CONFIRMED への照合
CrewAI 敵対的再試行ラボネイティブな BaseTool → 構造化ツールの実行、プロセスの強制終了、新しいプロセスからの再ディスパッチ対照実験では、外部効果が 2 回発生します外部効果は 1 回。CONFIRMED への照合
Agno 敵対的再試行ラボAgent(retries=2)、ツールの実行成功後にモデルから HTTP 500 が返る対照実験では、外部効果が 3 回発生しますリリース済みの @once-agent/[email protected] が 3 回すべての呼び出しを受け、外部効果を 1 回だけ確定します

LangGraph と CrewAI のラボでは、不明確な結果からの復旧経路も検証しています。

external effect commits
        ↓
acknowledgement / process is lost
        ↓
provider truth unavailable
        ↓
UNKNOWN
        ↓
execution fails closed
        ↓
provider truth later returns
        ↓
UNKNOWN → CONFIRMED
        ↓
no second external effect

これらの実験で使用されている復旧コアは、sdk/python/src/once_agent/ にある、同じフレームワークに依存しない実装です。

チェックポイントの状態から分かるのは、ワークフローが何を記憶しているかです。照合によって分かるのは、現実に何が起きたかです。

この検証で示されること

検証された安全境界では、フレームワーク自体に再試行を停止させることなく、測定対象のフレームワーク障害モデルにおいて 1 回の効果という不変条件が保たれました。

これは、あらゆる状況で「厳密に 1 回」の実行を保証するという主張ではありません。安全に復旧するには、操作 ID と状態の永続性に加え、結果が不明確な場合に、信頼できるプロバイダーとの照合、またはそれと同等の下流側での保証が引き続き必要です。

フレームワークとの統合

MCP ホストとの統合

Codex プラグイン

公開 GitHub マーケットプレイスから Once — Execution Safety をインストールします。

codex plugin marketplace add stringsofthemind-oss/once --ref main
codex plugin add once@once-agent

このプラグインは、Once の4条件ルーティングルール、エージェント間で共通の操作 ID、読み取り専用の評価を最初に行うワークフロー、ソース変更前の明示的な承認境界を Codex に教えます。また、固定バージョンのローカル @once-agent/mcp サーバーも公開します。

プラグインのソース：plugins/openai/once

Claude Code プラグイン

公開 GitHub マーケットプレイスから Once をインストールします。

claude plugin marketplace add stringsofthemind-oss/once
claude plugin install once@once-agent

これにより、MCP 経由で @once-agent/mcp を公開する Once Claude Code プラグインがインストールされます。

プラグインのソース：plugins/claude-code/once

重要

ONCE は現在 Stripe サンドボックス／テストモードです

ONCE の請求機能は現在、Stripe サンドボックスに接続されています。 このベータ版がサンドボックスモードで実行されている間、実際の支払いが行われたり、実際のお金が動いたりすることはありません。

実際のカード情報は入力しないでください。

テスト中に Stripe から支払い情報を求められた場合は、次の情報を使用してください。

  • カード番号： 4242 4242 4242 4242
  • 名前： John Doe（または任意の名前）
  • 有効期限： 12/34（または将来の日付）
  • CVC： 123（または任意の3桁の数字）
  • 郵便番号／ZIP： 有効に見える値

これらは Stripe のテスト用認証情報のみです。

ONCE は、請求機能がサンドボックスから実際の決済に移行する際に、明確にお知らせします。

副作用を伴う AI エージェントのツールを安全に再試行できるようにします。

Once は、最初のリクエストの結果が不確かな場合に、AI エージェント、ワークフロー、またはアプリケーションが同じ重要な操作を誤って2回実行するのを防ぎます。

代表的な例：

  • 支払いと返金
  • 予約と取り置き
  • メールとメッセージ
  • アカウントの変更
  • 注文の作成
  • Webhook によってトリガーされる操作
  • その他、取り消し不可能な書き込みや外部から確認できる書き込み

インストール

TypeScript / JavaScript：

npm install @once-agent/sdk

Python：

pip install once-agent-sdk

公開パッケージ：

標準の TypeScript クライアントには Node.js 18 以降が必要です。同一マシンでの自動的なローカル保護には Node.js 24.15 以降が必要です。

設定

Once API キーを設定します。

ONCE_API_KEY=your_api_key

Node に関する注意： .env に ONCE_API_KEY を保存しても、通常の Node が自動的に読み込むことはありません。フレームワーク／ランタイムの環境変数ローダーを使用するか、プロセスの起動前に変数をエクスポートしてください。または、対応する Node のバージョンでは node --env-file=.env <your-entry-file> を使ってアプリケーションを実行してください。

TypeScript の new Once() と Python の Once() は、ONCE_API_KEY を自動的に読み込みます。

API キーをソース管理にコミットしないでください。

60秒で始める

まず once setup . でプロバイダーを設定するか、Once アカウントにすでに登録されているプロバイダーエイリアスを使用してください。

TypeScript
import { Once } from "@once-agent/sdk";

async function main() {
  const once = new Once();

  const operationId = Once.id(
    "refund",
    "order_123"
  );

  const result = await once.execute({
    operationId,
    provider: "my-provider",
    action: {
      type: "refund",
      order_id: "123"
    }
  });

  console.log(result.state);
}

main().catch(console.error);
Python
from once_agent import Once

once = Once()
operation_id = Once.id("refund", "order_123")

result = once.execute(
    operation_id=operation_id,
    provider="my-provider",
    action={
        "type": "refund",
        "order_id": "123",
    },
)

print(result["state"])

my-provider を、Once アカウント用に設定したプロバイダーエイリアスに置き換えてください。

重要な点：操作 ID

同じ論理操作では、すべての再試行で同じ操作 ID を再利用してください。

TypeScript：

const operationId = Once.id(
  "refund",
  "order_123"
);

Python：

operation_id = Once.id("refund", "order_123")

同じサポート対象の入力からは、両方の SDK で同じ決定的 ID が生成されます。

異なる論理操作には、異なる意味的入力を使用してください。

Once.id("refund", "order_123");
Once.id("refund", "order_124");

再試行が同じ現実世界の操作を表す場合、再試行ごとに新しいランダム ID を生成しないでください。

これが必要な理由

リクエストが実際の副作用を引き起こす場合、通常の再試行は危険です。

たとえば：

  1. アプリケーションが返金リクエストを送信します；
  2. プロバイダーが返金を実行します；
  3. アプリケーションが応答を受け取る前にネットワーク障害が発生します；
  4. アプリケーションは返金が実行されたかどうか判断できません；
  5. 再試行します。

照合がなければ、再試行によって同じ重大な操作が再度実行される可能性があります。

Once は操作の状態を永続的に保持し、サポート対象のプロバイダー連携では、曖昧な操作を再実行できるようにする前にプロバイダーの実際の状態を照合できます。

Once は、別の実行が安全だと決めつけずに、操作を不確実な状態のまま保持する場合があります。

再試行

TypeScript の再試行では、同じ operationId を再利用します：

await once.execute({
  operationId,
  provider: "my-provider",
  action
});

Python の再試行では、同じ operation_id を再利用します：

once.execute(
    operation_id=operation_id,
    provider="my-provider",
    action=action,
)

操作の状態を確認する

後から操作の永続状態を確認できます。

TypeScript：

const truth = await once.truth(operationId);
console.log(truth.ledger_state);

Python：

truth = once.truth(operation_id)
print(truth["ledger_state"])

曖昧なリクエストの後や、別のプロセスが既存の操作の永続状態を確認する必要がある場合に便利です。

Once.id()

Once.id() は、意味的な値から決定的な操作 ID を生成します。

const id = Once.id(
  "send-invoice",
  "invoice_4821"
);

サポートされる要素は次のとおりです：

  • 文字列
  • 安全な整数

例：

Once.id("payment", "invoice_42");
Once.id("booking", 4821);

サポートされていない値や曖昧な値は、言語によって異なる ID が暗黙に生成されることなく、拒否されます。

たとえば、ブール値、null、小数、または JavaScript の安全な整数の範囲外の整数は渡さないでください。

言語間での ID の一致

Once.id() は、バージョン管理された once-id-v1 エンコーディングを使用します。

TypeScript と Python の実装は、同じ固定の適合性ベクトルを使って検証されるため、サポート対象の入力からは両言語で同じ操作 ID が生成されます。

ID ハッシュでは、曖昧さのない UTF-8 のバイト長付き要素を使用するため、要素の境界が異なる入力が同じハッシュ入力にまとめられることはありません。

可読なプレフィックスはラベルにすぎません。決定的なハッシュが完全な意味的入力を表します。

適切な操作 ID の選び方

操作 ID は、ネットワークリクエストの試行ではなく、現実世界のアクションを識別する必要があります。

適切な例：

Once.id("refund", "order_123");

リスクのある例：

Once.id("refund", Date.now());

タイムスタンプは再試行のたびに変わるため、Once は各試行を別の操作として認識します。

次のように考えるとよいでしょう：

このリクエストがタイムアウトして再試行する場合、再試行は同じ現実世界のアクションを表すべきでしょうか？

答えが「はい」であれば、同じ操作 ID を再利用してください。

CLI ワークフロー

TypeScript パッケージには once CLI が含まれています。

現在の HTTP 自動変換の範囲： npm SDK は TypeScript と JavaScript をサポートしています。実績のある HTTP 自動ソース変換機能は、現時点では既存の TypeScript ソースの範囲に加え、同じ厳密なリクエスト形式と安全性のチェックを満たす、明示的な ESM JavaScript .mjs モジュールをサポートしています。通常の .js および .cjs の呼び出し箇所は doctor／protect で検出・確認できますが、現時点ではこの自動変換の対象外です。プロバイダーを設定するだけでは、それらが PATCHABLE になることはありません。doctor . --protect は推測せずに、ソース形式の対象範囲を報告します。

一般的なワークフローは次のとおりです：

doctor -> review -> protect -> setup/integrate where needed -> first protected action
1. プロジェクトをローカルで評価する

新しいプロジェクトで、npm が Once の CLI を実行するように SDK パッケージを指定します。

npx --yes --package=@once-agent/sdk once doctor .

Doctor は、影響が大きい可能性のある操作を特定し、次に実行する保護コマンドを表示します。API キーは不要で、ソースコードをアップロードしたり、変更したりすることはありません。ソースコードを書き換えずに、.once/ の下にレビュー計画とスニペットを作成するには、npx --yes --package=@once-agent/sdk once doctor . --protect を実行します。以下の短い npx once コマンドを使う前に、npm install @once-agent/sdk で SDK をインストールしてください。

2. 影響の大きい可能性がある操作をスキャンする（任意）
npx once scan .

スキャナーは、Once の保護が役立つ可能性のある、副作用を伴う操作をローカルで探します。

ソースコードは CLI によってローカルでレビューされます。スキャナーはソースコードのアップロードを必要としません。

3. 保護候補をレビューする
npx once protect .

すべての信頼度レベルを含めます。

npx once protect . --all

レビュー計画を作成します。

npx once protect . --all --write-plan

次のものが作成される場合があります。

.once/protect-plan.json
4. パッチをプレビューする
npx once protect . --all --patch

これにより、アプリケーションのソースコードを直接変更せずに、レビュー可能なパッチのプレビューが生成されます。

統合ガイダンスも生成できます。

npx once protect . --all --snippets
5. 必要に応じて Once をセットアップする
npx once setup .

セットアップでは、SDK のインストールと設定、API キーの確認、サポート対象プロバイダーの登録、ローカルの Once 設定の準備を行えます。

変更を加えずにセットアップをプレビューします。

npx once setup . --plan

読み取り専用のソース形状の事前チェックでサポート対象と報告された、リテラルな HTTPS fetch 呼び出しの場合は、既存の Runtime HTTP パスを通じて、対象を正確に指定します。

npx --yes --package=@once-agent/sdk once setup . --runtime-http=https://api.example.com/resource

このセットアップ手順によって、サポートされていない呼び出し箇所が安全に書き換えられるようになるわけではありません。その後、doctor . --protect を再実行し、新しい結果が PATCHABLE の場合に限り --apply を使用してください。

6. 適用可能な変換を適用する
npx once protect . --apply

--apply は意図的に保守的な動作をします。

自動適用が行われるのは、対象が限定的にサポートされている呼び出し箇所であり、変更前に完全な再検証が行われる場合に限られます。

適用エンジンは、ソースのフィンガープリントを確認し、提案された変換を再計算し、TypeScript を検証し、バックアップを作成して、一時ファイルを使用します。また、結果を検証し、書き込み後の検証に失敗した場合はロールバックします。

PATCHABLE 候補が 0 件または複数件ある場合、自動適用は推測による実行を避けるため拒否されます。

必要に応じてホスト型接続を確認する
npx once doctor . --connection

この明示的な接続チェックには ONCE_API_KEY が必要です。既定のローカル評価では不要です。

protect のステータスの意味

保護レビューでは、次のようなステータスが報告される場合があります。

  • PATCHABLE - 現在の限定的な変換機能で、検証済みの自動パッチを生成できます
  • PROVIDER_MAPPING_REQUIRED - この呼び出しにはプロバイダーのマッピングが必要です。また Once は読み取り専用のソース形状の事前チェックも報告します。これにより、プロバイダーをセットアップすれば現在実証済みの変換機能を使えるのか、あるいはソース形状がすでにサポート対象外なのかを確認できます
  • PROVIDER_CAPABILITY_DECLARED - プロバイダーの機能は宣言されていますが、自動変換には引き続き、サポート対象との正確な一致が必要です
  • ADAPTER_REQUIRED - この操作にはプロバイダー固有の統合作業が必要です
  • MANUAL_REVIEW - CLI は呼び出し箇所を自動的に書き換えません

CLI は、安全でない自動変更よりも手動レビューを優先するよう設計されています。

安全性モデル

Once は、あらゆる状況での exactly-once 実行を保証しません。

安全性の特性は、次の要素に依存します。

  • 安定した操作 ID
  • 永続的な Once の操作状態
  • 使用するプロバイダー統合
  • 十分に信頼できるプロバイダーの情報
  • 障害モードが、そのプロバイダー統合のサポート対象モデルに含まれていること

サポート対象のプロバイダー統合では、Once は再試行や通信障害の結果が不明な場合に、再実行を許可する前にプロバイダーの情報を照合し、副作用の重複を防ぐよう設計されています。

外部への副作用が発生したかどうかを Once が判断できない場合、別の実行が安全だと決めつけずに、操作を不確定な状態のまま保持することがあります。

つまり、危険な副作用の重複を避けるために、Once は一時的に可用性を犠牲にする場合があります。

プロバイダーの事実

外部システムが次の問いに相当する質問に回答できる場合、Once の効果が最も発揮されます。

操作 X はすでに実行されましたか？

プロバイダー連携では、次の両方を定義します。

  1. 影響の大きいアクションを実行する方法
  2. Once が後からプロバイダーの確定的な事実を判断する方法

そのため、プロバイダー固有の保証は SDK 自体の保証とは分けて評価する必要があります。

エラー

Once は SDK およびサービスのエラー用に OnceError をエクスポートします。

import {
  Once,
  OnceError
} from "@once-agent/sdk";

const once = new Once();

try {
  await once.execute({
    operationId,
    provider: "my-provider",
    action
  });
} catch (error) {
  if (error instanceof OnceError) {
    console.error(
      error.code,
      error.message
    );
  }

  throw error;
}

すべてのエラーを、外部への副作用を直接実行してよいという許可として自動的に扱わないでください。

エラーは、結果が不確定であることを示している場合があります。操作の事実を照会するか、同じ操作 ID を使って Once 経由で再試行することで、安全性モデルを維持できます。

API の概要

new Once(options?)

Once クライアントを作成します。

デフォルト設定では、環境変数 ONCE_API_KEY を読み取ります。

サポートされているクライアントオプションは次のとおりです。

  • apiKey
  • baseUrl
  • timeoutMs
  • networkRetries
Once.id(...parts)

サポートされているセマンティックな要素から、決定的な操作 ID を作成します。

const operationId = Once.id(
  "charge",
  "invoice_123"
);
once.execute(input)

影響の大きい操作を Once 経由で実行、再開、または解決します。

const result = await once.execute({
  operationId,
  provider: "my-provider",
  action
});

console.log(result.state);

正規の execute レスポンスには state が含まれます。

once.truth(operationId)

操作の永続的な事実レコードを読み取ります。

const truth = await once.truth(operationId);

console.log(truth.ledger_state);

正規の truth レスポンスには ledger_state が含まれます。

設計原則

レスポンスが失われたという理由だけで、取り消し不可能なアクションを繰り返してはいけません。

Once は、この障害モードに対処するために構築されています。

ライセンス

MIT

コメント

Markdown 対応

MCP は初めてですか？

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。