tidebase

Tidebase

AI エージェント向けのエージェント認証と認証情報のブローカー機能に加え、チェックポイント、キュー、スケジュール、承認ゲートを提供します。ご自身の Postgres で利用できます。

クイックスタート · API · ストレージの仕様 · 対象範囲

Tidebase は AI エージェントに ID と保管庫を提供します。エージェントが API を呼び出すと、呼び出しは Tidebase を経由し、認証情報が挿入されるため、エージェントもモデルもキーを見ることはありません。利用範囲を制限し、監査し、取り消すことができます。

さらに、チェックポイント、ライブ状態、キュー、スケジュール、承認ゲートなど、永続化が必要な要素もすべてご自身の Postgres に保存します。コードは引き続きアプリ、ワーカー、またはジョブプロセス内で実行され、Tidebase が実行することはありません。そのため、「この実行はステップ 7 で停止したが、安全に再実行できるか？」に答えられ、「エージェントが GitHub トークンを平文で保持している」という状況もなくなります。

ドキュメント：https://tidebase.dev · コミュニティ：Discord · AI アシスタント向け：/llms.txt

Tidebase を選ぶ理由

エージェント製品には、通常、同じような運用基盤が必要になります。

• 共有 API キーではなく、エージェントごとの ID
• サードパーティのシークレットや OAuth トークン用の保管庫
• シークレットをモデルに渡さずに API を呼び出す方法
• 実行とステップのステータステーブル
• 途中までの進捗を保存するチェックポイントの Blob
• 再試行フラグと手動レビュー状態
• UI への進捗ストリーミング
• リスクの高い操作の承認ゲート
• トークンとコストの台帳
• 復旧や外部レビュー画面のための Webhook 連携

Tidebase は、既存のコードを囲むこのレイヤーに加え、エージェントがキーを持たずに実際のサービスを利用できるようにする認証情報ブローカーをパッケージ化して提供します。コードは実行せず（ランタイムは引き続きお客様のものです）、LLM プロキシでもホスト型ワーカーランタイムでもありません。

クイックスタート

最速の方法（Node 不要）、ビルド済みサーバーイメージ：

docker compose --profile server up -d   # Postgres + ghcr.io/blueprintlabio/tidebase on :7373

その後、任意の SDK を http://localhost:7373 に向けてください（npm i @tidebase/sdk または pip install tidebase）。

開発環境のセットアップ（サーバーと Studio をソースから実行）：

Postgres を起動します。

docker compose up -d postgres

依存関係をインストールします。

pnpm install

サーバーと Studio を実行します。

pnpm dev

• サーバー：http://localhost:7373
• Studio：http://localhost:5173

サンプルのワークフローを実行します。

pnpm example

2 つのチェックポイントの完了後に失敗させます。

FAIL_WRITE=1 pnpm example

Studio または API から実行 ID をコピーして、再開します。

TIDEBASE_RUN_ID=run_xxx pnpm example

plan と fetch-sources の各ステップはチェックポイントから返されます。再実行されるのは write-report だけです。

## エージェント認証と認証情報の仲介

エージェントに独自の ID を与え、サードパーティのシークレットを保管し、エージェント自身がキーを保持することなく API を呼び出せるようにします。Tidebase はシークレットを注入して外部への呼び出しを行い、スコープの設定、監査、取り消しができます。

import { Tidebase } from '@tidebase/sdk'

const tide = new Tidebase({ baseUrl: 'http://localhost:7373', apiKey: process.env.TIDEBASE_API_KEY })

// 1. Vault a secret behind a pinned upstream. The returned resource never carries the secret.
await tide.resources.connect('github', {
  provider: 'static',
  baseUrl: 'https://api.github.com',
  secret: process.env.GITHUB_TOKEN,
  scopesAllowed: ['repo.read'],
})

// 2. Inside a run, request a grant for what the agent needs to do.
const auth = tide.auth(runId)
const grant = await auth.request({
  resource: 'github:repo:acme/app',
  action: 'repo.read',
  scopes: ['repo.read'],
})

// 3. Make the call through Tidebase. The token is injected upstream; the agent and the LLM never see it.
const res = await auth.use(grant.grantId, { method: 'GET', path: '/user' })

シークレットは保存時にエンベロープ暗号化されます（AES-256-GCM と KMS でラップされた DEK）。baseUrl で上流を固定し、scopesAllowed で付与できる権限の上限を設定するため、付与情報が漏えいしても任意のホストにはアクセスできません。プロキシはプライベート IP とメタデータホストをブロックして SSRF を防御し、GET /audit はシークレット情報を含まない付与記録を返します。OAuth プロバイダーについては、認証情報の管理を nango または openbao に委任でき、Tidebase は不透明な接続参照のみを保持します。

Tidebase を AI コーディングエージェントと使う

プロジェクトのすべての AI セッションが Tidebase を正しく使うようにします。

npx @tidebase/sdk init        # writes a Tidebase section into AGENTS.md/CLAUDE.md (idempotent)

MCP を介して、実行、ゲート、復旧にアシスタントが直接アクセスできるようにします。

claude mcp add tidebase -e TIDEBASE_URL=http://localhost:7373 -- npx -y @tidebase/mcp

または、Claude Code プラグイン（スキルと MCP サーバーが一体化）をインストールします。

/plugin marketplace add BlueprintLabIO/tidebase
/plugin install tidebase@tidebase

エージェントが読み取れるドキュメントは tidebase.dev/llms.txt にあります。各ドキュメントページには、対応する未加工の .md ファイルも用意されています。

キュー、スケジュール、キャンセル（v0.5）

Tidebase はコードを実行することなく、コードをいつ実行するかも決定できるようになりました。

// durable queue: dedupe, delay, retries with backoff, concurrency caps
await tide.enqueue('generate-report', {
  queue: 'reports',
  input: { topic },
  dedupeKey: `report:${topic}`,
  maxAttempts: 3,
  deadlineMs: 600_000
})

// pull-mode worker: claims ready runs and executes registered workflows
tide.workflow('generate-report', generateReport)
await tide.work({ queues: ['reports'] })

// cron (UTC, 5-field), double-fires are structurally impossible
await tide.schedules.set('daily-digest', {
  cron: '0 9 * * *',
  workflowName: 'daily-digest'
})

// authoritative, one-way cancellation, workers observe it at step/gate
// boundaries; complete/fail can never resurrect a cancelled run
await tide.runs.cancel(runId, { reason: 'customer asked', actor: 'support' })

プッシュモードでのディスパッチにも対応しています。キューに invokeUrl を設定すると、クレームを待つ代わりに、Tidebase が署名済みの run.invoke Webhook をアプリに配信します。キューに登録されたジョブは実行そのものであり、queued はライフサイクル状態であって、別のテーブルではありません。そのため、ステータスにずれが生じません。

ライフサイクル全体、リプレイの契約、ワーカー停止時の復旧モデル、デプロイの規律（pnpm migrate によるバージョン管理されたマイグレーション、拡張／縮小デプロイ時の TIDEBASE_AUTO_MIGRATE=0）については、docs/production.md をご覧ください。

テスト

pnpm test

このテストスイート（TypeScript テスト 84 件と Python 統合テスト 9 件。プッシュのたびに CI で実行）は、分離された tidebase_test データベース内の同じ Postgres を使用します。カバレッジではなく、不変条件に基づいています。すべてのテストで、実際の Postgres を使い、公開 API または SDK を通じて、耐久性または安全性の保証を検証します。これには、競合時にのみ意味を持つ保証のための並行性プローブも含まれます。

検証される内容：

• 完了済みのステップはストレージからリプレイされ、クラッシュ後の復旧 Webhook による再開を含め、再実行されません
• ステップと実行のリースは相互排他的でフェンスされており、ゾンビワーカーは古い結果を書き戻せません
• リプレイ時の入力ハッシュの不一致は、実行を破損する前に拒否されます
• 障害の分類は再開の契約に従います。キーのない外部書き込みは manual_review に保留され、冪等性キー付きのステップと読み取り専用のステップは safe_replay になります
• 並行する書き込みのもとでも、実行ごとのイベントログに欠落はなく、順序が厳密に保たれます
• ゲートは一度だけ解決され、解決トークンが必要であり、再開時にはその判断がリプレイされます
• 子実行はエッジ名によって冪等になるため、再開されたファンアウトでは既存の子が再利用されます
• 復旧 Webhook とチャネル配信には HMAC 署名が付与され、SDK は署名のない、改ざんされた、または偽造されたペイロードを拒否します
• チャネルのエンドポイントが遅延または応答停止しても、他の実行への書き込みがブロックされることはありません

不変条件の全体マップと規約については、docs/testing.md をご覧ください。

API の構成

import { Tidebase } from '@tidebase/sdk'

const tide = new Tidebase()

await tide.run('generate-report', { runId }, async (run, input) => {
  const plan = await run.step('plan', () => makePlan(input))

  await run.state.set({
    status: 'writing',
    progress: 0.7
  })

  return run.step('write-report', () => writeReport(plan))
})

セッション実行

tide.run() は関数のような形の作業に適しています。自由度の高い実行、エージェントの前段に置くプロトコルゲートウェイ、REPL、複数のリクエストにまたがる実行には、代わりに実行へセッションとして接続します。

const session = await tide.runs.attach('mcp-session', { input: { agent: 'hermes' } })

// session is a RunContext: step/gate/state/usage/snapshots all work unchanged
await session.step('tool-call', { input: args }, () => callTool(args))

await session.complete({ calls: 12 }) // or session.fail(err)

セッションはバックグラウンドのハートビート（heartbeatMs、デフォルトは 20s）で実行のリースを保持します。プロセスが停止すると、ハートビートも止まり、リースが期限切れになり、リコンサイラーが引き継いで、ワークフローワーカーがクラッシュした場合と同様に、再キューイングまたは復旧用 Webhook を行います。リースを失ったセッション（onLeaseLost）はゾンビ状態となり、サーバーはその書き込みをフェンスします。既存セッションの実行を再開するには runId を渡します。完了したステップはストレージから再生されます。

MCP ゲートウェイで任意のエージェントの MCP サーバーをラップし、設定を 1 行変更するだけでチェックポイント付きのツール呼び出しと永続的な承認ゲートを実現する、完全な実例については、examples/mcp-gateway/ をご覧ください。

再開コントラクト

各ステップでは、再生のために Tidebase が記録する運用コントラクトを宣言できます。

await run.step(
  'send-email',
  {
    input: { userId },
    sideEffects: ['email.send'],
    idempotencyKey: `welcome:${userId}`,
    replay: 'auto',
    checkpointInvariant: 'provider accepted the message id',
    verifiedBy: 'email provider response'
  },
  () => sendWelcomeEmail(userId)
)

Tidebase はこのコントラクトをステップとともに記録し、Studio に表示します。最終的なステップの失敗は次のように分類されます。

• SDK のリトライが残っている場合は failed_retryable。
• 再生が手動の場合、または冪等性キーなしで副作用が発生する場合は manual_review。
• 重大な失敗の場合は failed。

これによって外部システムでの処理が厳密に 1 回だけになるわけではありません。ログや独自のリトライフラグに隠すのではなく、再開の判断を明示できるようになります。

バージョン管理された状態とスナップショット

run.state.set() と run.state.patch() は、引き続き現在の実行状態を更新します。v0.2 では、Tidebase の状態履歴にもバージョンが追加されます。

await run.state.patch({
  status: 'writing',
  progress: 0.7
})

現在の状態が重要なレビューまたは復元ポイントになったときに、ラベルを付けることができます。

await run.state.save('before-approval', {
  reason: 'the user is about to approve sending'
})

スナップショットは、レポート、アーティファクト、ワークスペース、ドキュメント、アプリの状態など、外部の対象向けにラベル付き状態バージョンを扱う便利な API です。

await run.snapshots.create('draft-v1', {
  target: { type: 'report', id: reportId },
  state: draft,
  reason: 'first complete draft'
})

このモデルは意図的にシンプルにしています。

current state = latest version in a stream
snapshot = labeled state version
time travel = read an older version
fork = create new app/run context from an older version
restore = append a new version based on an older version

Tidebase はバージョンを保存し、公開します。自身の状態対象における復元やフォークの意味は、アプリ側で決定します。

子実行とファンアウト

長時間にわたるエージェントワークフローでは、サブエージェントに処理を分配し、その結果を再結合することがよくあります。Tidebase v0.2 では、親子実行のエッジとチェックポイント付きの結合ステップとしてこれをモデル化します。

const results = await run.fanout('research-options', [
  {
    name: 'flights',
    workflow: researchFlights,
    input: { destination }
  },
  {
    name: 'hotels',
    workflow: researchHotels,
    input: { destination }
  },
  {
    name: 'food',
    workflow: researchFood,
    input: { destination }
  }
])

子実行の作成は、親実行とエッジ名によって冪等になります。親を再開すると、Tidebase は重複を作成せず、既存の子実行を返します。結合された結果は、join:<fanout-name> という名前の通常のチェックポイント付きステップに保存されます。

ゲートとチャネル

チャネルは Tidebase のイベントを外部のインターフェースに配信します。アルファ版では Webhook チャネルをサポートしています。

await tide.run(
  'generate-report',
  {
    input: { topic: 'channels' },
    channels: [{
      type: 'webhook',
      url: 'https://your-app.example.com/api/tidebase-events',
      events: ['run.failed', 'step.failed', 'gate.created']
    }]
  },
  workflow
)

ゲートは、Studio、製品の UI、Slack／Teams アダプター、内部ツール、またはローカルのレビューページで解決できる、永続的な承認判断を作成します。

const decision = await run.gate('approve-send', {
  prompt: 'Send this report to the customer?',
  data: { reportId },
  channels: [{ type: 'webhook', url: process.env.REVIEW_WEBHOOK_URL! }],
  capability: {
    name: 'report.send',
    scopes: ['report:send'],
    reason: 'agent wants to send an external report'
  }
})

if (decision.decision !== 'approved') {
  throw new Error('Report was not approved')
}

Webhook ゲートのペイロードには、レビュアーがゲートを解決するための resolveUrl と resolveToken が含まれます。（認証情報はブローカーが別途処理します。エージェント認証のセクションをご覧ください。）

人間、HTTP ハンドラー、ボット、プロトコルゲートウェイを待機させられない場合は、run.gate() の基盤となる、ブロックしない分割方式を使用します。

const gate = await run.gates.begin('approve-send', { prompt: 'Send it?', data: { reportId } })
if (gate.status === 'pending') {
  // return now; check back with run.gates.get(gate.gateId) on a later request
}

ゲートの開始は、実行内で名前ごとに冪等です。解決済みのゲートを再度開始すると、判断がすぐに返されるため、再試行された呼び出しも同じ回答に収束します。

ローカルの承認チャネルを起動します。

pnpm example:review

別のターミナルで次を実行します。

REQUIRE_APPROVAL=1 \
TIDEBASE_CHANNEL_WEBHOOK=http://localhost:8788/tidebase-events \
pnpm example

http://localhost:8788 を開いてゲートを承認すると、ワークフローが続行します。

リカバリー Webhook

Tidebase では、実行が失敗し、リカバリー Webhook が設定されている場合に、アプリにコールバックできます。SDK はこの Webhook を処理して、該当するワークフローを再開できます。

const run = await tide.runs.create('generate-report', {
  input: { topic: 'checkpoints' },
  recoveryWebhook: 'https://your-app.example.com/api/tidebase'
})

Tidebase は、配信状況、HTTP ステータス、レスポンスボディ、エラーとともに、リカバリーの各試行を記録します。サーバーと SDK の両方で TIDEBASE_WEBHOOK_SECRET が設定されている場合、リカバリーペイロードは x-tidebase-signature で署名されます。

この例にはローカル Webhook サーバーが含まれています。

pnpm example:webhook

使用状況の追跡

Tidebase は、モデルやプロバイダーの呼び出しをプロキシせずに、実行の汎用リソース使用状況を記録できます。

await run.usage.record({
  kind: 'llm',
  provider: 'openai',
  model: 'gpt-4.1-mini',
  label: 'draft-response',
  inputTokens: 1200,
  outputTokens: 420,
  costUsd: 0.012
})

使用状況の記録は実行とともに保存され、usage.recorded イベントとして発行され、Studio で要約されます。同じ台帳で、LLM 以外のリソースも追跡できます。

await run.usage.record({
  kind: 'tool',
  provider: 'internal-search',
  quantity: 8,
  unit: 'queries',
  costUsd: 0.004
})

Tidebase に保存されるデータ

• 実行と試行
• 名前付きチェックポイント付きステップ
• 古いチェックポイントの再利用を防ぐ入力ハッシュ
• ステップ再開コントラクト
• ライブ実行状態
• バージョン管理された状態ストリーム
• ラベル付き状態バージョンとスナップショット
• 親子実行のエッジ
• 追記専用の実行イベント
• リカバリーの試行
• Webhook チャネルの配信
• 永続化されたゲートと判断
• 認証情報／機能の監査メタデータ
• トークン、単位、コストの汎用使用状況記録

すべては Postgres によって支えられ、初日からセルフホストできるように設計されています。

現在の対象範囲

• Postgres を基盤とした実行ストア
• キャンセルと期限を第一級機能として扱う、信頼性の高い実行ライフサイクル管理
• 永続キュー（重複排除、遅延、優先度、再試行／バックオフ、同時実行数とレートの上限）
• cron スケジュール（UTC、二重実行防止）
• プルモードのワーカー（tide.work）とプッシュモードの署名付き呼び出し Webhook
• リコンシリエーター（リース期限切れ時の再キュー／リカバリー、期限切れによるキャンセル、cron、ディスパッチ）
• バージョン管理されたマイグレーションランナー
• TypeScript SDK
• asyncio を含む Python SDK（sdk-python/、tidebase.aio）
• SvelteKit Studio
• ライブ状態の設定／パッチ
• 状態履歴とラベル付きスナップショット
• 子実行とファンアウト結合
• SSE イベントストリーム
• 署名付きリカバリー Webhook
• Webhook チャネル
• 永続化されたゲート
• 使用状況／リソース台帳
• dogfood ワークフロー
• エージェント認証＋認証情報ブローカー：エージェントごとのキーペア ID、実行に紐付いた権限付与、シークレットを保存し、プロキシ経由の呼び出しに注入する保管庫（クライアントと LLM にはシークレットが見えません）、ポリシーエンジン、SSRF 防御、Nango／OpenBao バックエンド

このアルファ版の対象外

**v0.7.0（2026年6月）**時点。以前のアルファ版では、キュー、スケジュール、キャンセル、承認ゲート、API 認証、認証情報ブローカーがこの一覧に含まれていました。これらはすべてリリース済みです（v0.5〜v0.7）。永続キュー（再試行／バックオフ付き）、cron、信頼性の高いキャンセル、厳密に1回だけのゲート、セッション実行、オプトインのベアラー認証、停止したワーカーを検出して再ディスパッチするリコンシリエーターがリリースされ、v0.7 ではエージェント認証コントロールプレーンと認証情報ブローカーもリリースされました。意図的に対象外としているものは、以下のとおりです。

• Tidebase がホストするコード実行（ランタイムはお客様の環境に留まります。これは今後も対象外であり、保留中ではありません）
• LLM ゲートウェイ／プロキシ
• ホスト型チャネルアダプター
• エージェントメモリ（会話または埋め込みの保存）
• マルチテナント認証（現在は単一の共有 API キー）
• ホステッドクラウド

アルファ版について

これはローカルでのデモや初期フィードバック向けであり、本番環境向けではありません。

重要な制限事項：

• マイグレーションはバージョン管理され、アドバイザリロックを使用します。開発環境では起動時に自動マイグレーションされます。また、TIDEBASE_AUTO_MIGRATE=0 と pnpm migrate を使用すると、拡張／縮小デプロイの規律を適用できます。
• API 認証はオプトインです。サーバーと SDK（Studio の場合は VITE_TIDEBASE_API_KEY）に TIDEBASE_API_KEY を設定してください。設定しない場合、API は公開されます。信頼できるローカル環境またはセルフホスト環境でのみ使用してください。
• 外部への副作用には、引き続きユーザーコードで冪等性キーが必要です。
• Tidebase は何が起きたかを記憶し、リカバリー Webhook を呼び出せますが、ユーザーコードが再開時に利用可能であることは保証しません。