ペイロードと転送

エンベロープ

interface PayloadEnvelope {
  schema_version: 1
  account_id: string
  project_id: string
  resource: string
  resource_id: string
  source: PayloadSource
  references: ArtifactRef[]
  payload: JsonObject
}

account_id と project_id は検証済みプロジェクトから取得します。 ペイロードのルーティングとコンテキストを担いますが、認証情報ではなく、アクセスを認可するものでもありません。 resource は vision.prd などの柱と種別で、resource_id は成果物またはイベントの ID です。

Markdown 成果物の payload は { metadata, body } です。 Record と Drift Event のペイロードは、検証済みの JSON エンベロープです。 references は、検証済みの入力から得られる明示的な参照です。

ソースの出所

PayloadSource.kind は次のいずれかです。

• markdown — 安全な相対 path が必要
• json — 安全な相対 path が必要
• integration — integration と external_id が必要

解析済みの成果物は、パスから markdown または json を判定します。 直接渡された Record は、連携元をソースとして推定します。 直接渡された Drift Event にはソースフィールドがないため、呼び出し側が出所を明示する必要があります。

createPayload(
  project: Project,
  input: ParsedArtifact | RecordEvent | DriftEvent,
  source?: PayloadSource
): PayloadEnvelope

ソースオブジェクトは、余分なフィールドと無効な組み合わせを拒否します。 ファイルの出所には、ローカル成果物と同じ相対パスの構文制限を適用します。

注入する転送処理

interface PayloadTransport {
  send(
    payload: PayloadEnvelope,
    context: { authorization: string }
  ): Promise<{ correlationId?: string }>
}

sendPayload はエンベロープを検証・構築し、認証情報を解決して、呼び出し側が提供するこのインターフェースを実行します。 エンドポイントやプロトコル構成は選択しません。

認証情報には env:NAME 参照を使います。 resolveCredential は実行時に値を読み取り、欠落、改行、ヌルバイトを含む値を拒否します。 認証情報は転送コンテキストとして個別に渡され、ペイロードエンベロープには含まれません。

await sendPayload(project, input, transport, {
  credentialRef: 'env:LANGDRIFT_TOKEN',
  source
})

SDK は、HTTP クライアント、永続化、バッチ処理、バックグラウンドキュー、自動再試行、自動アップロードを提供しません。 Markdown 本文と Record データはペイロードの内容になるため、秘密情報を含めないでください。

転送エラー

注入したアダプターは TransportError(status) を送出できます。 sendPayload は次のように対応付けます。

• 401 または 403 → REMOTE_UNAUTHORIZED
• その他の 4xx → REMOTE_REJECTED
• それ以外の転送エラー → MCP_UNAVAILABLE

これらは LangDriftError になります。 リモートの応答本文、スタック、認証情報をそのまま転送することはありません。 利用不能な転送のデータはローカルにキュー保存されず、再試行は明示的に行います。