RightOS

← RightFlow

RightFlow API（v0.1）

認証は RightOS と同じ組織 API キーです。RightFlow は提案を作り、受諾時に RightOS トークンを読み取り検査しますが、verify/use/cancel/transfer は呼び出しません。

可視性は必要性を意味しません。組織全体の list は統合者／管理向けです。通常は get または actorId などのスコープ参照を優先してください。progress は粗い協調シグナルとし、高頻度テレメトリは実行系に置いてください。

概念ガイド · 判断ガイド · rightflow-openapi.json · sdk/rightflow.ts · Facility Handoff Lab · MCP

レート制限

IP あたり約 180 回/分、組織あたり約 120 回/分、書き込み（POST/PUT）は組織あたり約 60 回/分。超過時は 429 rate_limited（Retry-After）。

エンドポイント

MethodPath説明
POST/api/rightflow/tasksタスク作成（open）
GET/api/rightflow/tasksタスク一覧（統合者／管理。通常は get または actorId）
GET/api/rightflow/tasks/{taskId}タスク取得
POST/api/rightflow/tasks/{taskId}/transitions実行状態遷移（start／粗い progress／complete／fail／cancel）
POST/api/rightflow/tasks/{taskId}/suggest-candidates次の担い手候補の参考ランキング（自動提案しない。softSignals はリクエスト限り）
PUT/api/rightflow/actors/{actorId}アクター能力・待機表明（availability）の upsert
GET/api/rightflow/actorsアクター一覧（統合者／管理）
POST/api/rightflow/proposals割当・再割当・交換の提案
GET/api/rightflow/proposals提案一覧（統合者／管理。taskId フィルタ推奨）
POST/api/rightflow/proposals/{id}/accept提案受諾（能力＋RightOS権利ゲート）
POST/api/rightflow/proposals/{id}/reject提案却下
POST/api/rightflow/safety-events安全イベント記録＋事後協調修復（L2・実行系が先に動作済み）
POST/api/rightflow/lab/attempt-executeLab: 実行系シミュレータ（L1 権利再検証）
POST/api/rightos/admin/break-glass緊急一括無効化（L3・管理者のみ・監査付き）

最小フロー例

PUT /api/rightflow/actors/actor_a
Authorization: Bearer rk_live_...
{ "capabilities": ["carry.light", "indoor.navigation"], "availability": "waiting" }

POST /api/rightflow/tasks
{ "title": "Move parcel", "requiredCapabilities": ["carry.light"],
  "spatialRequirement": { "kind": "zone_ref", "zoneId": "zone_lobby" } }

POST /api/rightflow/tasks/task_.../suggest-candidates
{ "actorIds": ["actor_a", "actor_b"],
  "softSignals": { "actor_a": { "nearZone": "zone_lobby" } } }
→ reference ranking only (heuristic.v0); does not create proposals

POST /api/rightflow/proposals
{ "kind": "assignment", "taskId": "task_...", "toActorId": "actor_a" }

POST /api/rightflow/proposals/prop_.../accept
→ commits assignment in RightFlow after rights/capability gates

POST /api/rightflow/tasks/task_.../transitions
{ "action": "start" }

薄い TypeScript クライアント

import { RightFlow } from "https://rightos.i-s3.com/sdk/rightflow.ts";

const rf = new RightFlow({ apiKey: "rk_live_..." });
await rf.upsertActor("actor_a", ["carry.light"], { availability: "waiting" });
const { task } = await rf.createTask({
  title: "Move parcel",
  requiredCapabilities: ["carry.light"],
  spatialRequirement: { kind: "zone_ref", zoneId: "zone_lobby" },
});

// Option A — reference scorer (heuristic.v0; does not create proposals)
const ranked = await rf.suggestCandidates(task.id, {
  actorIds: ["actor_a", "actor_b"],
  softSignals: { actor_a: { nearZone: "zone_lobby" } },
});
const pick = ranked.candidates.find((c) => c.eligible)?.actorId ?? "actor_a";

// Option B — external engine swap: rank outside Core, then only POST proposals
// const pick = (await acmeRouter.rank(task.id))[0].actorId;

const { proposal } = await rf.createProposal({
  kind: "assignment",
  taskId: task.id,
  toActorId: pick,
});
await rf.acceptProposal(proposal.id);
await rf.transition(task.id, "start");
// Execution systems must re-verify RightOS before real action.

実装上の注意