バージョニングと公開

概要

Jinba Toolboxは、不変のスナップショットを持つsemverベースのバージョニングシステムを採用しています。各ToolSetはドラフト（編集可能な作業コピー）と公開済みVersionの一覧を管理します。公開すると、すべてのToolコード、スキーマ、Sandbox設定を含むToolSetの完全なスナップショットが、変更不可能なVersionとして凍結されます。この設計により再現性が保証されます。Version 1.0.0 を実行すると、いつどこから呼び出しても常に同じコードが実行されます。

コンセプト

ドラフトとVersion

ToolSet
├── Draft (editable working copy)
└── Versions (immutable releases)
    ├── v1.2.0 [published]
    ├── v1.1.0
    └── v1.0.0

状態	説明
ドラフト	編集可能な作業コピー。Web UIまたはAPIを通じて変更可能。`test` エンドポイント（コンソールのセッションのみ）でのみ実行可能。
Version	不変のリリース。公開後は変更不可。`run` およびMCPエンドポイントで使用される。
公開済み	APIが現在配信しているアクティブなVersion。ToolSetの各環境（`default` と追加した環境）がそれぞれアクティブVersionを持つ。`latestVersion` は共通。

不変のスナップショット

各Versionは、公開時点のToolSetの完全なスナップショットを取得します：

すべてのToolコードとエントリーポイント
入力スキーマと出力スキーマ
Tool名と説明
Sandbox設定（プロバイダー、言語、パッケージ、リソース）

これにより、後でドラフトを更新しても、既存のVersionは変更されません。

公開ワークフロー

ドラフトを編集する

WebコンソールまたはAPIを通じて、ドラフト内のToolに変更を加え、コンソールのテストパネルで動作を検証します。裏側のエンドポイントは POST /v1/orgs/{orgId}/toolsets/slack-tools/tools/post-message/test（ボディは { "input": { ... } }）ですが、サインイン済みユーザーのセッションが必要なため、APIキーでは呼び出せません。

新しいVersionを公開する

ドラフトの準備ができたら、semverバージョン番号とオプションのリリースノートを指定して公開します（公開にもサインイン済みセッションが必要です。コンソールのNew Versionダイアログを使用してください）：

curl -X POST https://toolbox-api.jinba.io/v1/orgs/{orgId}/toolsets/slack-tools/versions \
  -H "Authorization: Bearer <JinbaAuth session token>" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "1.3.0",
    "releaseNotes": "Added thread reply support"
  }'

APIキー（jtb_...）では 400（“User context required”）で拒否されます。SDKの publishVersion() もAPIキーを送るため、同じく失敗します。

公開Versionを設定する

新しく公開されたVersionは、"setAsPublished": false を渡さない限り、environmentSlug（デフォルト default）で指定した環境のアクティブVersionに自動的になります。後から別のVersionをアクティブにする場合や、別の環境でVersionをアクティブにする場合は、明示的に設定します：

curl -X PUT https://toolbox-api.jinba.io/v1/orgs/{orgId}/toolsets/slack-tools/published-version \
  -H "Authorization: Bearer jtb_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "version": "1.3.0", "environmentSlug": "default" }'

変更は即座に反映されます。コンソールでは、VersionsタブのSet Activeを使用します。

開発を続ける

公開後もドラフトはそのまま残るため、ライブの公開Versionに影響を与えることなく、次のVersionに向けて反復的に開発を続けられます。

Versionの解決

run エンドポイント経由でToolを実行する際、Jinba Toolboxは使用するVersionを以下のように解決します：

リクエストボディに version フィールドが含まれている場合、その正確なVersionが使用されます。
それ以外の場合、ToolSet環境のアクティブVersionが使用されます。環境は、リクエストの environmentSlug フィールド、それがなければAPIキーに紐付けられた環境（セッションリクエストでは default）で決まります。
その環境にアクティブVersionがない場合、組織の run およびMCPエンドポイントは latestVersion にフォールバックします。パブリックエンドポイントはフォールバックせず、「No published version available」を返します。

# 公開Versionを使用
curl -X POST .../tools/post-message/run \
  -d '{ "input": { "channel": "#general", "text": "Hello" } }'

# 特定のVersionを使用
curl -X POST .../tools/post-message/run \
  -d '{ "input": { "channel": "#general", "text": "Hello" }, "version": "1.2.0" }'

ロールバック

ロールバックは、環境のアクティブVersionを以前のものに変更するだけです：

# default環境をv1.2.0に戻す
curl -X PUT https://toolbox-api.jinba.io/v1/orgs/{orgId}/toolsets/slack-tools/published-version \
  -H "Authorization: Bearer jtb_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "version": "1.2.0", "environmentSlug": "default" }'

Versionは不変であるため、ロールバック時にデータが失われることはありません。新しいVersionは引き続き利用可能で、いつでも再アクティブ化できます。

Version API

メソッド	エンドポイント	説明
GET	`/v1/orgs/:orgId/toolsets/:slug/versions`	全Versionの一覧（直近30日の `runCount`、環境ごとのアクティブVersion、`hasUnpublishedChanges` を含む）
POST	`/v1/orgs/:orgId/toolsets/:slug/versions`	新しいVersionの公開（`version`、`releaseNotes?`、`setAsPublished` = `true`、`environmentSlug` = `default`）。セッションのみ
GET	`/v1/orgs/:orgId/toolsets/:slug/versions/:version`	Versionの詳細を取得（`isPublished`、`isLatest`）
GET	`/v1/orgs/:orgId/toolsets/:slug/versions/:version/export`	VersionをZIPアーカイブとしてダウンロード
PUT	`/v1/orgs/:orgId/toolsets/:slug/published-version`	環境のアクティブVersionの設定（`version`、`environmentSlug` = `default`）

Versionデータモデル

公開された各Versionは完全なスナップショットを保存します：

interface ToolSetVersion {
  id: string;
  toolSetId: string;
  version: string;              // semver文字列（例: "1.3.0"）
  sandbox: SandboxConfig;       // 凍結されたSandbox設定
  tools: ToolSnapshot[];        // 凍結されたTool定義とコード
  releaseNotes?: string | null;
  publishedBy: string;          // 公開者のユーザーID
  publishedAt: string;          // ISO 8601タイムスタンプ
}

interface ToolSnapshot {
  id: string;
  slug: string;
  name: LocalizedText;
  description: LocalizedText;
  inputSchema: JSONSchema;
  outputSchema: JSONSchema;
  code: string;
  entrypoint?: string;
}

使用量の追跡

Jinba Toolboxは、各Versionの直近30日間の実行回数を集計します。コンソールのVersionsタブでは各Versionの横にこの回数が表示され、Version一覧エンドポイントは runCount として返します。完全な履歴が必要な場合は、APIを通じて実行履歴を取得してください：

const runs = await client.listRuns();
// アプリケーションロジックで `toolSetVersion` ごとにフィルタリング

使用量データは、古いVersionを廃止しても安全かどうかを判断するのに役立ちます。

ベストプラクティス

セマンティックバージョニングに従う — 破壊的なスキーマ変更にはメジャーバンプ、新しいToolや機能にはマイナーバンプ、修正にはパッチバンプを使用してください。
リリースノートを記述する — Version間の変更点をチームが理解するのに役立ちます。
公開前にテストする — 不変のVersionを作成する前に、test エンドポイントでドラフトを検証してください。
MCPの公開ステップを省略しない — MCPエンドポイントはドラフトではなく公開Versionを配信します。
Versionごとの使用状況を監視する — Versionを廃止する前に、依存している利用者がいないことを確認してください。

Docs

バージョニングと公開

概要

コンセプト

ドラフトとVersion

不変のスナップショット

公開ワークフロー

Versionの解決

ロールバック

Version API

Versionデータモデル

使用量の追跡

ベストプラクティス

関連ドキュメント

​概要

​コンセプト

​ドラフトとVersion

​不変のスナップショット

​公開ワークフロー

​Versionの解決

​ロールバック

​Version API

​Versionデータモデル

​使用量の追跡

​ベストプラクティス

​関連ドキュメント

概要

コンセプト

ドラフトとVersion

不変のスナップショット

公開ワークフロー

Versionの解決

ロールバック

Version API

Versionデータモデル

使用量の追跡

ベストプラクティス

関連ドキュメント