Aggrega ワークスペース設定スキーマ
自動生成されたリファレンスです。手動で編集しないでください。公開されている JSON Schema から再生成してください。
スキーマ ID: https://aggrega.ai/schemas/aggrega-config-v1beta1.schema.json
aggrega CLI が読み込むワークスペースごとの設定ファイルです。.aggrega-config.yaml に配置されます。workspace ブロックはルートマーカーです。その存在によってワークスペースのルートが示され、このブロックにはカタログディレクトリのみが含まれます。それ以外のキーはすべて設定であり、トップレベルに置かれます。設定は次の分類に分かれます。コンテンツの取得元、固定、キャッシュの方法(レジストリの選択、オフライン、自動 pull と固定の動作、アーティファクトおよびコンパイル済みモジュールのキャッシュの場所とサイズ上限)、コンテンツの信頼方法(署名と署名検証の動作)、オーサリングの判定の厳しさ(ルールごとの lint 設定、非推奨の厳格さ、オーサリング release のヒント)、ワークスペース全体にアタッチする Wasm プラグイン(ガバナンス、リンター、インポーター、ターゲットごとの provider レンダリングのバインディング)、そして CLI の実行方法(並行性、サービング、デーモンの解析キャッシュの削除上限)です。以下のプロパティが完全かつ正式な一覧です。この概要はキーではなく分類を挙げているため、キーを追加してもこの概要が誤りになることはありません。フラットなトップレベル構造で、apiVersion/kind のエンベロープを持たず、カタログのコンテンツとは区別されます。スキーマの進化に関する方針: 新しいトップレベルキーの追加は SemVer の MINOR の更新(追加的な変更)です。キーの削除や移動、または制約の強化は SemVer の MAJOR の破壊的変更です。
トップレベルの型: object
プロパティ
| プロパティ | 種類 | 必須 | 説明 |
|---|---|---|---|
workspace | object | いいえ | ワークスペースのルートマーカーです。これが存在するだけで、そのディレクトリがワークスペースのルートとして示されます。ここに含めるのはルートを定義するカタログディレクトリ(ワークスペース自身のもの、および Release に個別に与えられたもの)だけです。ルートを定義しない設定はすべて、ここではなくトップレベルに置きます。ベンダリングされたカタログディレクトリを持たないルートを示すには workspace: {} と書きます。 |
default_registry | string | いいえ | エンティティがレジストリを明示的に指定しない場合に、エンティティの公開先となり、依存関係の解決元となるデフォルトの OCI レジストリです。aggrega push はそこに公開し、aggrega pull はそこから取得します。デフォルトは hub.aggrega.ai です。registries 配下のエントリの name(そのエントリの host を表します)、ホストそのもの、またはホストの後に / とリポジトリパスを続けたもの(ghcr.io/acme や harbor.example.com/platform など)を書きます。名前が最初に照合されます。あるエントリの name である値は、ホストのような綴りであってもそのエントリのホストとなり、公開、プル、署名検証、およびレジストリごとのすべての信頼設定はその 1 つのホストを使用します。2 つのエントリの名前となっている値は曖昧であるとして拒否され、名前の後にパスが続く値も拒否されます。名前はエントリのホストを表すものであり、その配下の場所を表すものではないためです。それ以外の値はホストでなければならず、その信頼ポリシーが保持されている綴りで書きます。すなわち、ドットを含む小文字のホスト名(registry.example.com)、localhost、単一の名前の後にポートを続けたもの(registry:5000)、IPv4 アドレス、または角括弧で囲んだ IPv6 アドレス([::1])で、いずれも任意の :port を付けることができ、スキーム、認証情報、空白、大文字は含みません。その後に任意でリポジトリパスを続けられます。リポジトリパスは小文字と数字からなる 1 つ以上のセグメントを / でつないだもので、セグメント内は .、_、__、またはダッシュで区切ることができ、タグ、ダイジェスト、末尾の / は含みません。パスは公開と取得の場所です。デフォルトレジストリを通じて公開されるすべてのエンティティは <host>/<path>/ 配下に公開され、デフォルトレジストリを通じて解決されるすべてのエンティティはそこから取得されるため、一方が公開したものを他方が見つけられます。パスはレジストリの信頼方法には一切関与しません。適用されるポリシーを持つ registries エントリ、ログイン、署名要件、信頼されたアイデンティティは、すべてホストのみによって決まります。HTTPS で到達するホストのポート 443 はそのホストのデフォルトポートであり、これを書くと拒否され、ポートなしで書くべき綴りが示されます。localhost およびその他のループバックアドレスはプレーン HTTP で到達するため、そこでは 443 は通常のポートであり保持されます。空の値はデフォルトレジストリを指定しません。値はこのスキーマではなく設定の読み込み時に判定されます。名前が参照するエントリが別の設定ファイルで宣言されている可能性があるためです。値はすべての設定ファイルと AGGREGA_DEFAULT_REGISTRY 環境変数を読み込んだ後に読み取られ、どれによって設定された場合でも同じ文言で拒否され、そのファイルまたは変数が示されます。1 回の呼び出しで公開先を指定する --registry フラグも、同じ方法でエントリの名前と照合されます。このフラグが持つそれ以外の値は参照であってもよく、その参照が示すホストは同じ綴りの要件に従い、公開先となります(リポジトリパスは付きません)。ホストは綴りのみで判定され、名前が解決できるかどうか、そこでレジストリが応答するかどうかは確認されません。デフォルト: "hub.aggrega.ai" |
offline | 真偽値 | いいえ | true の場合、ビルドはどのレジストリにも接続せず、キャッシュ済みのアーティファクトとベンダリングされたカタログコンテンツのみを参照します。デフォルトは false です。デフォルト: false |
auto_pull | 真偽値 | いいえ | false(デフォルト)の場合、aggrega build は読み取り専用です。ソースのピンを書き込むことはなく、リリースごとのロックファイルが存在しないか不完全な場合は、先に aggrega pull --release <release> を実行するよう求める診断を出してビルドを明示的に停止します。true の場合、aggrega build はビルドの前にプロセス内でプルステップを実行し、Release の依存関係をロックファイルとキャッシュに解決します。そのため、Release に対する初回のビルドで明示的なプルステップは不要です。同じ 1 回限りのオプトインは、コマンドラインで aggrega build --auto-pull としても利用できます。ロックファイルを書き込むのは引き続き pull だけです。offline: true はプルステップを無効にしません。プルステップはレジストリに接続せず、マシンがすでに保持しているもの(キャッシュとローカルのカタログディレクトリ)に対して実行され、どちらにも存在しない参照があると、その参照を示すプル自身の拒否によってビルドが停止します。デフォルト: false |
pin_sources_at_pull | 真偽値 | いいえ | false(デフォルト)の場合、プルはエンティティの横にピンを記録しません。Release がビルドする、このワークスペースのカタログディレクトリ内の Recipe または FeatureRecipe について、エンティティの横にある entity.lock が、エンティティが読み取る各入力(座標が完全に記述されたリモートの source:、artifacts エントリがインポートするファイル、またはエンティティの横にあるローカルの source: の各ファイル)のピンを記録していない場合、プルは停止し、エンティティ、各入力とその種別、およびそれらを記録するステップとして aggrega pin を示します。ピン留めはエンティティ作成者のステップであるため、誰もピン留めしていないエンティティはまだ利用できる状態ではありません。true の場合、このワークスペースのすべてのプルが代わりに同じエンティティに対してそのステップを実行し、aggrega pin が書き込むのと同じ entity.lock のバイトを書き込みます。他者がピン留めしていないエンティティを利用するワークスペースは、こうすることで停止する代わりにそのピンを一度だけ記録します。自身のロックファイルを埋めるビルドはプルであり、この設定に従います。aggrega pull --pin-sources は 1 回の呼び出しでピン留めし、--pin-sources=false は 1 回の呼び出しで停止します。この設定の内容にかかわらずです。カタログディレクトリではなくキャッシュから解決されたエンティティにはロックを書き込む場所がなく、プルによってピン留めされることも停止させられることもありません。デフォルト: false |
pin_sources_at_push | 真偽値 | いいえ | true の場合、このワークスペースのすべての aggrega push は、公開するエンティティをバンドルする前にエンティティ作成者のピンステップを実行するため、そのステップがエンティティの横に書き込む entity.lock が公開内容に含まれます。false(デフォルト)の場合、push はピンステップを実行せず、そのステップが記録するはずのすべてのピンを entity.lock が記録していない Recipe または FeatureRecipe を拒否し、aggrega pin を示します。このステップはエンティティの横に書き込むため、エンティティに書き込み可能な場所がある場合にのみ実行されますが、push には常にそれがあります。push はドキュメントによって指定されたエンティティを公開するためです。aggrega push --pin-sources は 1 回の呼び出しでピン留めし、--pin-sources=false はピン留めしません。この設定の内容にかかわらずです。aggrega pin が実行するのと同じステップであり、同じバイトを書き込みます。デフォルト: false |
artifact_cache_dir | string | いいえ | ローカルのアーティファクト/コンテンツのキャッシュディレクトリです(レジストリからのプル、OCI マニフェスト、コンパイル済みフィクスチャ)。デフォルトは .aggrega/cache です。慣例により gitignore に含めるべきです。パスは、コマンドをどこから実行した場合でも、ワークスペースのルートからの相対パスとして解釈されます。絶対パスの値は設定の読み込み時に拒否されます。この設定を読み取るものはすべてそのルートを基準に解決するため、絶対パスでは到達しない場所を指してしまうためです。キャッシュはカタログディレクトリの中に置くことができます(カタログディレクトリは一般にワークスペースのルートであるため、デフォルトはそうなっています)が、キャッシュがカタログディレクトリそのものであってはなりません。カタログのスキャンはキャッシュを飛ばすため、カタログディレクトリを指す値では、そのディレクトリの内容全体がスキャンから除外されます。ワークスペースのルート自体を指す値(.、またはそれに帰着する任意の綴り)は、まさにその理由で設定の読み込み時に拒否されます。それ以外のカタログディレクトリを指す値は拒否されません。問題なく読み込まれ、その後のスキャンでそのディレクトリには何も見つからなくなるため、workspace.catalog_dirs に列挙されたディレクトリの外にキャッシュを置くことは利用者自身が確認する必要があります。デーモンのメモリ内パースキャッシュの上限を定める parse_cache、およびマシン全体のコンパイル済みモジュールストアの上限を定める compiled_module_cache とは別のものです。デフォルト: ".aggrega/cache" |
skip_signature_verification | 真偽値 | いいえ | 署名検証をグローバルに、明示的に無効化するオプトアウトです。true の場合、必須の hub ベースラインを含むすべてのレジストリで署名検証が無効になります。緊急時や開発シナリオを想定したもので、決して黙って行われることはありません。pull が署名をチェックしたはずの場所ではどこでも、検証がグローバルに無効化されている旨の警告が出されます。デフォルトは false です。Default: false |
build | object | いいえ | ビルド時の厳格さの調整項目と作成時のヒントです。authoring_release はインライン診断のために LSP に current Release のヒントを与えます。halt_on_deprecated_severity は非推奨エンティティの使用に対するビルドの反応を制御します。yaml_indent はレンダリングされるすべての YAML 成果物のインデント幅を設定します。 |
plugins | object | いいえ | ワークスペースレベルの Wasm プラグインのアタッチメントです。各ソケット(governance、linter、importer)はプラグイン参照の配列を受け取り、ビルドは各プラグインの文書化されたエントリ関数をそのソケットの契約に従って呼び出します。providers リストは、ケイパビリティをそれを提供するプロバイダーレンダリングプラグインに結び付けます。 |
lint | object | いいえ | ルールごとの厳格さの調整項目です。 |
parse_cache | object | いいえ | デーモンのパースキャッシュの追い出し上限です。両方の上限が同時に適用されます。LRU 追い出しループはキャッシュへの挿入のたびに実行され、エントリ数とバイト合計の両方が範囲内に収まるまで、最も長く使われていないエントリを削除します。どちらかが 0 の場合は unbounded on that axis を意味し、キャッシュが 1 回の呼び出しの間だけ存在する CI シナリオで有用です。ディスク上のコンテンツキャッシュである artifact_cache_dir とは別物です。 |
compiled_module_cache | object | いいえ | ディスク上のコンパイル済みモジュールキャッシュのサイズ上限です。これはコンパイラが再利用するマシンコードのストアで、Wasm プラグインをビルドごとではなくマシンごとに 1 回だけコンパイルするためのものです。マシン上のすべてのワークスペースで共有されるため、マシン全体で 1 つの値にしたい場合、このキーはグローバル設定ファイルに置きます。上限は呼び出しごとに 1 回、プラグインが読み込まれる前に、残りが収まるまでコンパイルの古い順にエントリ全体を削除することで適用されます。ビルドのコンパイル中に適用されることはありません。エントリの削除による損失は後の再コンパイルだけなので、上限を下げても安全です。aggrega cache status はストアの現在のサイズを報告し、aggrega cache evict --max-size はコマンドラインで指定した上限までオンデマンドで削減します。artifact_cache_dir(pull したレジストリのコンテンツ)や parse_cache(デーモンのインメモリパースキャッシュ)とは別物です。 |
concurrency | object | いいえ | デーモンのリクエストディスパッチの並行性設定です。デーモンは単一の stdin ストリームからリクエストを読み取り、上限付きのリクエストキューを処理するワーカープールで各リクエストを実行します。レスポンスは完了順にかかわらず、リクエストの到着順に出力されます。 |
serve | object | いいえ | IDE 統合が利用するサービスとしてのコンパイラであるデーモン(aggrega serve)の動作設定です。 |
mcp | object | いいえ | Model Context Protocol サーバー(aggrega mcp)の設定です。transport はサーバーへの到達方法(プロセスの標準入出力経由か HTTP 経由か)を選択し、どちらを選んでも読み取られます。announce_tools も両方のトランスポートで読み取られます。クライアントに提示されるツールは、クライアントがどのように到達したかではなく、サーバーの性質だからです。その他のキーはすべて HTTP トランスポートが開始するリスナーを設定するもので、サーバーが標準入出力で通信している間は使用されません。listen も同様で、そこで読み取られるのは、アドレスが使用されない旨をサーバーがエラーストリームに 1 行で伝えるためだけです。各キーがどちらに当たるかは以下に記載しています。エディタのバックエンドデーモンを設定する serve とは別物です。 |
registries | RegistryConfig[] | いいえ | レジストリごとの設定と署名の信頼ポリシーで、レジストリのホストをキーとします。ここに記載されていないレジストリはデフォルトを使用します。存在する署名は検証され、署名がない場合は許容されます。ただし hub.aggrega.ai は例外で、その組み込みベースラインにより、明示的なエントリがなくても検証済みの署名が必須です。ホストに対する明示的なエントリは、そのホストのベースラインを上書きします。Default: [] |
signing | SigningConfig | いいえ | すべてのレジストリに適用されるトップレベルの署名ブロックです。キーレスサービスの URL、任意の鍵付き署名用の鍵のパス、およびすべてのレジストリに対する信頼の姿勢(required と kinds)を含みます。レジストリごとの signing ブロックは、そのホストに対するエンドポイントのデフォルトを上書きし、そのホストにスコープされた同じ required/kinds の姿勢を持ちます。1 つの名前に 1 つの役割があり、スコープは配置によって決まります。トップレベルの required/kinds ポリシーは、設定のカスケード全体で単調に合成されます。セキュリティ:このブロックは秘密情報を保持しません。OIDC ID トークンが設定フィールドになることはなく(実行時にフラグまたは周囲の OIDC 環境から供給されます)、key_path は鍵ファイルへのパスであり、鍵のバイト列をインラインで書くことはありません。 |
追加のプロパティは許可されません。
aggrega-config.workspace
ワークスペースのルートマーカーです。これが存在するだけで、そのディレクトリがワークスペースのルートとして示されます。ここに含めるのはルートを定義するカタログディレクトリ(ワークスペース自身のもの、および Release に個別に与えられたもの)だけです。ルートを定義しない設定はすべて、ここではなくトップレベルに置きます。ベンダリングされたカタログディレクトリを持たないルートを示すには workspace: {} と書きます。
| プロパティ | 種類 | 必須 | 説明 |
|---|---|---|---|
catalog_dirs | string[] | いいえ | このワークスペースがローカルエンティティを読み込む任意のカタログディレクトリで、レジストリにフォールバックする前に参照されます。各エントリはファイルシステムパスで、それを宣言するファイルからの相対パスとして解決されます。このリストは順序付きの先勝ち検索スタックです。あるアイデンティティを最初に宣言した、リストの先頭に近いディレクトリがそのアイデンティティを所有し、後のディレクトリにある同じアイデンティティは隠されます。ワークスペースルートの catalog ディレクトリも、リストされたすべてのエントリの後に、存在する場合に限り読み込まれます。ただし、リストされたエントリがすでにそれを含む場合は、そのエントリの一部として読み込まれます。したがって、ディレクトリをリストすると、ワークスペースがすでに読み込んでいるものを置き換えるのではなく、それに追加されます。このキーを省略することと空のリストとして書くことは異なる意味を持ちます。省略した場合、ワークスペースは引き続き catalog を読み込みます。[] と書いた場合、ローカルカタログをまったく読み込まず、これがワークスペースにローカルカタログがないことを示す方法です。releases の下で独自のカタログディレクトリを与えられた Release は、このリストの代わりにそれらを読み込みます。ルートスコープ:ローカルカタログディレクトリはこのワークスペースルートに属するため、トップレベルではなくルートマーカーに置かれます。 |
catalog_dirs_append | string[] | いいえ | 有効な catalog_dirs リストへの任意の追加専用の追記です。各優先順位レイヤーで、ここにあるエントリは解決済みのベースリストに連結されるため、ワークスペース設定とグローバル設定はカタログディレクトリを隠し合うのではなく合成できます。同一レイヤーでの相互作用:1 つのレイヤーで catalog_dirs と catalog_dirs_append の両方が指定された場合、そのレイヤーでの解決値はベースリストの後に追記リストが続いたものになります。Default: [] |
releases | ReleaseCatalogConfig のマップ | いいえ | Release 独自の任意のカタログディレクトリで、複数のカタログバリアントを並べて保持し、各 Release をそのうちの 1 つに対してビルドするワークスペース向けです。各キーは Release ファイルで、それを宣言するファイルからの相対パスとして書きます。各値は catalog_dirs と catalog_dirs_append を持ち、このブロックでの意味と同じですが、スコープはその 1 つの Release に限られます。ここで指定された Release は、このブロックのリストの代わりに自身の catalog_dirs を読み込み、その後に自身の catalog_dirs_append が続きます。catalog_dirs を省略したエントリはこのブロックのリストを維持し、その後に自身の catalog_dirs_append を追加します。検索順序、ワークスペースルートの catalog ディレクトリ、空のリストの意味は、このブロック自身のリストと同じです。このマップで指定されていない Release は、従来どおりこのブロックのリストを読み込みます。Release は、ターミナルから、aggrega serve を介したエディタから、あるいは aggrega mcp を介してなど、どのようにビルドされてもこれらのディレクトリを読み込みます。また、1 回の呼び出しに対しては、--catalog ディレクトリが引き続きそれらより先に検索されます。存在しないファイルを指定するエントリは、設定の読み込み時にエントリとファイルを示して拒否されるため、Release の名前を変更しても、ビルド対象のカタログが知らないうちに変わることはありません。設定ファイル間では、各 Release のエントリはこのブロック自身のキーと同じ方法で合成されます。その Release について、より近いファイルの catalog_dirs がより遠いファイルのものを置き換え、すべてのファイルの catalog_dirs_append がカスケード順に追加されます。AGGREGA_CATALOG_DIRS はこのブロックのリストを設定し、ここにあるエントリには影響しません。単一の Release に関係しない操作(カタログ全体の lint や検証、名前によるエンティティの検索、エディタによるワークスペースのエンティティ一覧表示)は、これらではなくこのブロックのリストを読み込みます。 |
追加のプロパティは許可されません。
aggrega-config.build
ビルド時の厳格さの調整項目と作成時のヒントです。authoring_release はインライン診断のために LSP に current Release のヒントを与えます。halt_on_deprecated_severity は非推奨エンティティの使用に対するビルドの反応を制御します。yaml_indent はレンダリングされるすべての YAML 成果物のインデント幅を設定します。
| プロパティ | 種類 | 必須 | 説明 |
|---|---|---|---|
authoring_release | string | いいえ | LSP がインライン診断の current Release コンテキストとして扱う Release YAML ファイルへのパスです。任意です。 |
yaml_indent | integer | いいえ | レンダリングされるすべての YAML アーティファクト(docker-compose ファイル、Helm チャートのテンプレートと values、Kubernetes マニフェスト)のインデント幅(スペース数)です。デフォルトは 2 で、これらの形式の慣例的な幅です。最小値: 2。最大値: 9。デフォルト: 2 |
halt_on_deprecated_severity | string (enum) | いいえ | 順序付き集合 warning < error < retracted における重大度で、記録された非推奨マーカーがこの重大度以上の場合にビルドを停止します。マーカーが記録される両方の場所を管理します。1 つはビルドがバイト単位で再現するすべてのものについてのロックファイル、もう 1 つはその横にあるプラグイン信頼レコードで、受理か拒否の判定を返すロールでアタッチされたプラグイン(ir-verdict または render-verdict での plugins.governance アタッチメント、およびすべての plugins.linter アタッチメント)についてのものです。1 つのダイヤル、1 つのルール、両方のストアです。デフォルトでは未設定で、未設定の場合、記録されたマーカーによってビルドが停止することはありません。マーカーはすでに固定したバージョンに対して記録されるため、一度成功したビルドは成功し続けます。通知と解決は別々の軸であり、どちらもこのダイヤルではありません。いずれかのレコードを読み込むすべてのサーフェスは、固定しているすべての非推奨参照と、マーカーを持つすべての信頼済みプラグインを、すべての重大度について、その名前、重大度、メッセージとともに報告します。対象は aggrega build、aggrega validate --release、aggrega lint --release、エディタ向けデーモン、および AI ネイティブの build、describe、validate ツールです。したがって、このしきい値を上げても、報告される内容が減ることはありません。このダイヤルはビルドのみを管理します。aggrega build(および同じ操作である AI ネイティブの build ツール)を停止させ、報告用のサーフェスはマーカーを示して処理を続行します。参照がどのバージョンに解決されるかに影響するのは retracted マーカーのみで、それはビルド時ではなく aggrega pull がバージョンを選択するときに作用します。Allowed values: "warning", "error", "retracted" |
追加のプロパティは許可されません。
aggrega-config.plugins
ワークスペースレベルの Wasm プラグインのアタッチメントです。各ソケット(governance、linter、importer)はプラグイン参照の配列を受け取り、ビルドは各プラグインの文書化されたエントリ関数をそのソケットの契約に従って呼び出します。providers リストは、ケイパビリティをそれを提供するプロバイダーレンダリングプラグインに結び付けます。
| プロパティ | 種類 | 必須 | 説明 |
|---|---|---|---|
governance | PluginRef[] | いいえ | governance ソケットのプラグイン。各エントリは、アタッチ先のパイプラインの role(annotation-transform、label-transform、ir-verdict、render-verdict のいずれか)を指定します。role によって、プラグインが出力できる内容とデフォルトのエントリ関数の両方が決まります(annotation-transform → transform_annotations、label-transform → mutate、ir-verdict → verdict_ir、render-verdict → verdict_render)。デフォルト: [] |
governance_append | PluginRef[] | いいえ | 有効な governance リストへの追記専用の追加分です。ここのエントリは各優先順位レイヤーで解決済みのベースリストに連結されるため、ワークスペース設定とグローバル設定は governance のアタッチを上書きせずに合成できます。デフォルト: [] |
linter | PluginRef[] | いいえ | linter ソケットのプラグイン。デフォルトのエントリ関数: lint_rules。linter プラグインのエクスポートは lint_ で始まる必要があるため、これらのエントリの function: はその接頭辞を持つエクスポートを指定します。デフォルト: [] |
linter_append | PluginRef[] | いいえ | 有効な linter リストへの追記専用の追加分です。governance_append と同じく、上書きせずに合成するセマンティクスです。デフォルト: [] |
importer | FixedEntryPluginRef[] | いいえ | importer ソケットのプラグイン。ソケットは import エントリ関数を呼び出します。アタッチでは関数を指定しません。デフォルト: [] |
importer_append | FixedEntryPluginRef[] | いいえ | 有効な importer リストへの追記専用の追加分です。governance_append と同じく、上書きせずに合成するセマンティクスです。デフォルト: [] |
providers | FixedEntryPluginRef[] | いいえ | ケイパビリティごとのプロバイダー選択です。各エントリは、1 つのプロバイダーケイパビリティ(Recipe が spec.capability でバインドする素のケイパビリティ名。例: helm や compose)を、それを提供するプロバイダーレンダリングプラグインの素の識別子(Plugin エンティティの識別子、つまり metadata.pluginType と metadata.name をスラッシュで連結したもの。例: provider/helm)にバインドします。末尾には任意で :version を付けられ、その形式はバージョンピンと同じ 3 種類(素の形式、完全一致の :1.0.0、メジャー互換範囲の :^1.0.0)です。これは、複数のプロバイダープラグインが同じケイパビリティを提供するフェデレーテッドカタログにおける曖昧さ解消と上書きのための設定箇所で、バインディングによってどのパブリッシャーのプラグインがそのケイパビリティをレンダリングするかを選択します。ケイパビリティを提供するプロバイダープラグインが 1 つだけの場合、エントリは不要です。合成後のリスト全体でケイパビリティごとに許可されるエントリは 1 つだけで、ケイパビリティが重複すると解決は明示的に停止します。解決は pull 時に行われます。pull は解決済みのバインディングを Release ごとのロックファイルに記録し、ビルドはロックファイルを読み取ります。pull 後にここを変更しても次の pull まで反映されないため、ビルド出力はこの変更の影響を受けません(決定的な出力)。Release のすべてのビルドと検証では、Recipe がそのケイパビリティを要求しているかどうかにかかわらず、ここの各エントリも検査されます。ビルドが保持するプラグインのうち、エントリのケイパビリティを提供しないものを指定したエントリは停止し、そのプラグインが提供するものと、存在する場合は 1 文字違いの綴りを示します。ケイパビリティを指定しプラグインを指定しないエントリで、ビルドが読み取るどのプロバイダープラグインもそのケイパビリティを提供しない場合は、停止せずに警告として報告されます。それを提供するプラグインは別の Release だけが読み取るものかもしれないためです。また、プラグインが提供するがこの Release が要求しないケイパビリティのエントリは正当であり、何も報告されません。エントリはワークスペース全体に対して記述され、ビルドは 1 つの Release を対象とするためです。コロンを含む capability は設定の読み込み時に拒否されます。Recipe の spec.capability は最後のコロンまでがケイパビリティ、その後がバージョンピンとして読み取られるため、そのようなエントリに到達できる Recipe は存在しないからです。曖昧さなく提供されているケイパビリティのエントリがなくてもエラーではありませんが、曖昧に提供されているケイパビリティのエントリがない場合は pull が明示的に停止し、候補のプラグインを一覧表示します。バージョンの共存は維持されます。バインディングはケイパビリティごとにプラグインリポジトリを選択し、各 Recipe 自身の spec.capability のバージョンピンがそのリポジトリ内のバージョンを選択するため、1 つのプロバイダーの異なるバージョンをピンする 2 つの Recipes も共存できます。デフォルト: [] |
providers_append | FixedEntryPluginRef[] | いいえ | 有効な providers リストへの追記専用の追加分です。ここのエントリは各優先順位レイヤーで解決済みのベースリストに連結されるため、ワークスペース設定とグローバル設定はプロバイダーバインディングを上書きせずに合成できます。governance_append と同じく、上書きせずに合成するセマンティクスです。ケイパビリティごとに 1 エントリという規則は合成後のリストに適用されるため、下位レイヤーですでにバインドされたケイパビリティを指定する追記エントリは、解決を明示的に停止させます。デフォルト: [] |
cli | CLIPluginRef[] | いいえ | トップレベルの aggrega コマンドとしてインストールされる CLI 拡張プラグインです。各エントリは 1 つの CLI プラグインを、解決済みでバージョンがピンされたアーティファクト参照と、インストール時にその参照が解決されたゲストバイトのコンテンツダイジェストによってピンします。ベースリストが設定カスケード全体で丸ごと置き換えられる 4 つの横断的なソケットリストとは異なり、CLI リストは合成されます。グローバル設定の CLI プラグインはすべてのワークスペースでコマンドを登録し、ワークスペース設定のものはそのプロジェクトでのみ登録し、両方が併せて登録されます。そのため _append の対応キーは不要です。各プラグインが提供するコマンド名とヘルプは、プラグイン自身の自己記述から得られ、digest をキーとするディスク上の describe キャッシュから読み取られます(キャッシュが空の場合はゲストの読み込みにフォールバックします)。リストが保持するのはピンだけです。コマンド実行時に、解決されたバイトは再ハッシュされて digest と比較されます。不一致の場合はコマンドが明示的に停止し、再ピンを指示するため、ピン後にバイトが変更されたプラグインが気付かれずに実行されることはありません。デフォルト: [] |
追加のプロパティは許可されません。
aggrega-config.lint
ルールごとの厳格さの調整項目です。
| プロパティ | 種類 | 必須 | 説明 |
|---|---|---|---|
publishing_discipline | object | いいえ | publishing-linter のルールセットに対するワークスペース全体のゲートです。allow_* フラグは個々の非推奨チェックを緩和します。アーティファクトの不変性はここでは設定できません。aggrega push は公開済みのバージョンの上書きを無条件に拒否します。 |
追加のプロパティは許可されません。
aggrega-config.lint.publishing_discipline
publishing-linter のルールセットに対するワークスペース全体のゲートです。allow_* フラグは個々の非推奨チェックを緩和します。アーティファクトの不変性はここでは設定できません。aggrega push は公開済みのバージョンの上書きを無条件に拒否します。
| プロパティ | 種類 | 必須 | 説明 |
|---|---|---|---|
allow_dynamic_refs | 真偽値 | いいえ | true の場合、publishing-linter はカタログコンテンツ内の $dynamicRef / $dynamicAnchor の JSON Schema 構文を受け入れます。デフォルトは false です。これらの構文はコンパイル時のスキーマ合成を非局所的にするため、推奨されません。デフォルト: false |
allow_id_overrides | 真偽値 | いいえ | true の場合、publishing-linter はエンティティのスキーマコンテンツ内のサブスキーマに対する $id の上書きを受け入れます。デフォルトは false です。$id の上書きは、リゾルバと JSON Schema バリデータの双方が依拠する「スキーマごとに正規の識別子を 1 つ」という慣例を壊します。デフォルト: false |
allow_direct_x_aggrega_extensions | 真偽値 | いいえ | true の場合、ビルド時の非推奨チェックは、スキーマコンテンツに直接記述された x-aggrega-selector および x-aggrega-inject キーワードを受け入れます。デフォルトは false です。推奨される記述方法は usesSchema(依存関係ソケット向け)または featuresSchema(認証情報バインディング向け)で、コンパイラがそれらをこれらのキーワードに合成します。デフォルト: false |
allow_aggrega_ai_prefix | 真偽値 | いいえ | true の場合、publishing-linter は予約済みの aggrega.ai/ および feature.aggrega.ai/ 名前空間を使うアノテーションキーを、その正規のコンテキスト外でも受け入れます。予約プレフィックスのルールはカタログエンティティの metadata.annotations を検査します。素の aggrega.ai/ プレフィックスはプラットフォームネイティブです(既知のアノテーションキーはこのフラグに関係なく対象外です)。feature.aggrega.ai/ プレフィックスは Feature 種別でのみ正規です。デフォルトは false です。エンタープライズのツールが正当な理由で予約プレフィックスを使う必要がある場合に、オペレーターがこれを設定します。両方のプレフィックスがまとめて緩和されます。デフォルト: false |
allow_nonstandard_names | 真偽値 | いいえ | true の場合、publishing-linter はプロジェクトの文書化された命名の慣例に従わないカタログエンティティ名を受け入れます。デフォルトは false です。一貫した命名は、リゾルバ、ラベル選択、レビュー担当者の使いやすさを支えています。デフォルト: false |
allow_category_mismatches | 真偽値 | いいえ | true の場合、publishing-linter は category-matches-directory ルールを抑制します。標準カタログの慣例では、core/false |
allow_undeclared_recipe_provides | 真偽値 | いいえ | true の場合、publishing-linter は provides-declared-by-component ルールを抑制します。このルールは、Recipe が spec.provides で公開するキーのうち、その spec.implements が指す Component が spec.schema の provides の柱で宣言していないものを報告します。この 2 つは別々の面です。Recipe が公開するものはコンシューマーが受け取る値であり、Component が宣言するものは inject の from: 参照の検査対象となる出力の契約です。そのため、宣言されずに公開されたキーは、そのような参照を停止させます。Recipe がその Component の宣言以上のものを公開すること自体はビルド時に受け入れられるため、この指摘は公開の拒否ではなく助言にとどまります。デフォルトは false です。デフォルト: false |
allow_connection_credential_mismatches | 真偽値 | いいえ | true の場合、publishing-linter は connection-credential-matches-target-key ルールを抑制します。このルールは aggrega lint --release が、指定された Release、それがデプロイする Aggregate、およびその Aggregate のインスタンスが使う Components に対して実行します。呼び出し元に要求するキーをターゲットが宣言している各接続について、ルールは両端が参照するもの、すなわち接続が提示する認証情報と、ターゲットが自身のスロットに保持するキーを比較します。両端が異なるシークレットを指している場合と、キーが片方の端にしか宣言されていない場合を報告し、どちらの値も引用しません。どちらの端も相手のアタッチメントを見られないため、両者が一致するのは記述上の規律(通常は 1 つのパラメーターが両方に渡されること)によってのみであり、ビルドはどちらの場合も受け入れます。そのため、この指摘は助言にとどまります。両端が意図的に異なるワークスペースは、ここでオプトアウトします。デフォルトは false です。デフォルト: false |
追加のプロパティは許可されません。
aggrega-config.parse_cache
デーモンのパースキャッシュの追い出し上限です。両方の上限が同時に適用されます。LRU 追い出しループはキャッシュへの挿入のたびに実行され、エントリ数とバイト合計の両方が範囲内に収まるまで、最も長く使われていないエントリを削除します。どちらかが 0 の場合は unbounded on that axis を意味し、キャッシュが 1 回の呼び出しの間だけ存在する CI シナリオで有用です。ディスク上のコンテンツキャッシュである artifact_cache_dir とは別物です。
| プロパティ | 種類 | 必須 | 説明 |
|---|---|---|---|
max_entries | integer | いいえ | キャッシュされるパース結果の数の上限です。デフォルトは 1000 です。0 はエントリ数の軸を無効にします(エントリ数による追い出しは発生しません)。最小値: 0。デフォルト: 1000 |
max_bytes | integer | いいえ | キャッシュが保持するドキュメントの累計サイズ(バイト単位)の上限です。デフォルトは 100000000(100 MB)です。0 はバイトの軸を無効にします(バイト合計による追い出しは発生しません)。最小値: 0。デフォルト: 100000000 |
追加のプロパティは許可されません。
aggrega-config.compiled_module_cache
ディスク上のコンパイル済みモジュールキャッシュのサイズ上限です。これはコンパイラが再利用するマシンコードのストアで、Wasm プラグインをビルドごとではなくマシンごとに 1 回だけコンパイルするためのものです。マシン上のすべてのワークスペースで共有されるため、マシン全体で 1 つの値にしたい場合、このキーはグローバル設定ファイルに置きます。上限は呼び出しごとに 1 回、プラグインが読み込まれる前に、残りが収まるまでコンパイルの古い順にエントリ全体を削除することで適用されます。ビルドのコンパイル中に適用されることはありません。エントリの削除による損失は後の再コンパイルだけなので、上限を下げても安全です。aggrega cache status はストアの現在のサイズを報告し、aggrega cache evict --max-size はコマンドラインで指定した上限までオンデマンドで削減します。artifact_cache_dir(pull したレジストリのコンテンツ)や parse_cache(デーモンのインメモリパースキャッシュ)とは別物です。
| プロパティ | 種類 | 必須 | 説明 |
|---|---|---|---|
max_bytes | integer | いいえ | コンパイル済みモジュールキャッシュがディスク上に保持するバイト数の上限です。デフォルトは 53687091200(50 GiB)で、意識されることを想定した予算ではなく、際限のない増大を止めるための上限です。コンパイル済みプラグイン 1 つで数百メガバイトに達するため、多くのプラグインバージョンをビルドするマシンではギガバイト単位で蓄積します。1 回のビルドがコンパイルする量より大きく設定してください。上限はビルドが何かをコンパイルする前に適用されるため、1 回のビルド自体の作業セットより小さい上限では、毎回のビルドが同じモジュールを破棄して再コンパイルすることになり、ストアは何も節約しなくなります。上限が先に適用され、その後ビルドがコンパイルしたものを書き込むため、ビルドの合間にはストアが上限を超えていることがあります。その場合は次のビルドの開始時に再び削減されます。0 は上限を無効にします(ストアは際限なく増え、自動的に削除されるものはありません)。ストアはすべてのワークスペースが共有する 1 つのディレクトリであるため、プロジェクト自身のファイルに記述されていても、この上限はプロジェクト単位ではありません。値は他のすべてのキーと同じく、より近いファイルが優先される方法で解決されますが、ストアのサイズは 1 つしかありません。有効な上限は直近のビルドのものであるため、異なる上限を設定した 2 つのプロジェクトは交互にそれぞれ有効になり、一方の低い上限はもう一方がコンパイルしたマシンコードを破棄します。グローバル設定ファイルで一度だけ設定すれば、マシン全体で 1 つの値になります。aggrega config show --origin は、各設定の有効な値がどのファイルから来たかを示します。最小値: 0。デフォルト: 53687091200 |
追加のプロパティは許可されません。
aggrega-config.concurrency
デーモンのリクエストディスパッチの並行性設定です。デーモンは単一の stdin ストリームからリクエストを読み取り、上限付きのリクエストキューを処理するワーカープールで各リクエストを実行します。レスポンスは完了順にかかわらず、リクエストの到着順に出力されます。
| プロパティ | 種類 | 必須 | 説明 |
|---|---|---|---|
pool_size | integer | いいえ | リクエストキューを処理するワーカーの数です。デフォルトは 4 で、最大 4 件のリクエストを並行してディスパッチします。1 に設定すると、リクエストは到着順に逐次実行されます。1 未満の値は、デーモンの起動時に 1 に引き上げられます。最小値: 1。デフォルト: 4 |
追加のプロパティは許可されません。
aggrega-config.serve
IDE 統合が利用するサービスとしてのコンパイラであるデーモン(aggrega serve)の動作設定です。
| プロパティ | 種類 | 必須 | 説明 |
|---|---|---|---|
build_on_inspect | 真偽値 | いいえ | IR グラフを検査する際にデーモンがアーティファクトのレンダリング段階を実行するかどうかを指定します。実行すると、aggrega build がレンダリング中に出すアドバイザリもエディタの問題として表示されます。ビルドが停止する原因となるチェックは何も追加されません。どちらの場合もディスクには何も書き込まれず(レンダリング済みアーティファクト、出力ディレクトリ、ロックファイルのいずれも書き込まれません)、レンダリング段階がグラフを変更することもないため、検査がグラフを返す場合、そのグラフはどちらの場合も同じです。デフォルトは false で、aggrega inspect と一致します。このターミナルコマンドはグラフの検査中にレンダリング段階に到達しないため、そのようなアドバイザリも出さず、アドバイザリを出さないエディタの検査はターミナルと同じ内容を表示します。この追加の層をエディタに求める場合は true に設定します。デフォルト: false |
lint_on_validate | 真偽値 | いいえ | カタログエンティティを検証する際にデーモンが公開慣例のチェックを実行するかどうかを指定します。実行すると、aggrega lint がそのエンティティについて報告する指摘もエディタの問題として表示されます。指摘はアドバイザリです。指摘を受けたドキュメントも検証は通り、その Release も引き続き解決およびレンダリングされます。ローカルの内容を読むチェックのみが実行され(レジストリは参照されず、何も取得されず、何も書き込まれません)、ディスク上のファイルではなくエディタが保持するバッファに対して評価されるため、修正した名前は保存前に報告されなくなります。デフォルトは false です。エディタのセッションはドキュメントが正しいかどうかを報告し、2 つ目の層を求めるまでは、エンティティが公開可能かどうかについては何も示しません。それを求める場合は true に設定します。このキーとは無関係に、エディタはいつでもこのチェックを直接要求でき、以前に公開されたバージョンとの公開前比較もこの方法で利用します。デフォルト: false |
追加のプロパティは許可されません。
aggrega-config.mcp
Model Context Protocol サーバー(aggrega mcp)の設定です。transport はサーバーへの到達方法(プロセスの標準入出力経由か HTTP 経由か)を選択し、どちらを選んでも読み取られます。announce_tools も両方のトランスポートで読み取られます。クライアントに提示されるツールは、クライアントがどのように到達したかではなく、サーバーの性質だからです。その他のキーはすべて HTTP トランスポートが開始するリスナーを設定するもので、サーバーが標準入出力で通信している間は使用されません。listen も同様で、そこで読み取られるのは、アドレスが使用されない旨をサーバーがエラーストリームに 1 行で伝えるためだけです。各キーがどちらに当たるかは以下に記載しています。エディタのバックエンドデーモンを設定する serve とは別物です。
| プロパティ | 種類 | 必須 | 説明 |
|---|---|---|---|
transport | string (enum) | いいえ | サーバーへの到達方法です。stdio はプロセスの標準入出力でプロトコルを通信します。これは、コマンドをサブプロセスとして起動するクライアントがサーバーに到達する方法です。http は listen が指定するアドレス上の HTTP で、tls が証明書と鍵を指定する場合は HTTPS でサービスを提供します。aggrega mcp --transport stdio|http は 1 回の呼び出しに限りこのキーを上書きします。デフォルトは stdio のため、トランスポートを指定しないワークスペースは、このブロックに他に何が含まれていても標準入出力でサービスされます。リスナーが起動するのは、ここまたはコマンドラインで http が選ばれた場合のみです。それ以外の値は設定の読み込み時に拒否されます。呼び出し元がネットワーク経由で到達するサーバーの設定では http を設定し、クライアント自身がサーバーを起動する場合は未設定のままにします。stdio が選ばれている場合、listen のアドレスは使用されず、サーバーはそのことをエラーストリームに 1 行で示します。許可される値: "stdio", "http" デフォルト: "stdio" |
listen | string | いいえ | HTTP トランスポートが選ばれた場合にリスナーがバインドするアドレスです。待ち受ける場所を指定するだけで、何も選択しません。トランスポートの選択は transport が担い、stdio が選ばれている場合このキーは使用されません。受け付ける形式は 2 つで、TCP アドレスには host:port、Unix ドメインソケットには unix: の後にファイルシステムパスを続けます。aggrega mcp --listen <address> は 1 回の呼び出しに限りこのキーを上書きします。デフォルトは空で、HTTP トランスポートにはどちらか一方からのアドレスが必要です。どちらもない場合、それを選ぶ起動は何もバインドされる前に拒否されます。平文のアドレス(tls に証明書と鍵がない状態で到達するアドレス)は、ループバック(127.0.0.1、::1、またはそのいずれかに解決される localhost)または Unix ソケットでのみ受け付けられます。これは前段のプロキシが TLS を終端する場合にサーバーが使う形です。それ以外のアドレスは、何もバインドされる前に mcp.tls.cert_file と mcp.tls.key_file を示して拒否されます。authorization.trusted_proxy が設定されている場合も、証明書の有無にかかわらず、受け付けられるのは同じ 2 つの形式のみです。ヘッダーを資格情報として信頼できるのは、プロキシ以外にそれを設定できるものがない場合に限られるためです。デフォルト: "" |
tls | object | いいえ | サービスを提供するプロセス内で TLS を終端するための証明書と鍵です。両方を設定すると、listen が指定するリスナーから直接 HTTPS を提供します。両方を未設定のままにすると平文で提供し、listen はループバックまたは Unix ソケットに限定されます。これは前段のプロキシが証明書を保持する場合に使う形です。どちらのキーもディスク上のファイルへのパスであり、鍵の素材をインラインで保持することはありません。 |
allowed_origins | string[] | いいえ | リクエストの Origin ヘッダーで受け付けるオリジンです。Origin ヘッダーがこのリストにないオリジンを指定するリクエストは 403 で拒否されます。リストにあるオリジンを指定するリクエスト、または Origin ヘッダーをまったく持たないリクエストは処理されます。エントリはヘッダーと完全一致で比較されるため、各エントリはブラウザがオリジンを送る形で記述します。小文字のスキーム、://、小文字のホスト(名前、IPv4 アドレス、または角括弧で囲んだ IPv6 アドレス)、そしてスキームのデフォルトでない場合は : とポートを続け、その後には何も付けません。例: https://app.example.com または http://localhost:3000。それ以外の形のエントリはブラウザが送るものと一致することがないため、設定ファイルの読み込み時にファイルとエントリを示して拒否されます。末尾に / やパスがあるもの(https://app.example.com/)、スキームがないもの(app.example.com)、大文字や空白を含むものが該当します。デフォルトは空のため、どのオリジンも受け付けられず、Origin ヘッダーを送らない呼び出し元のみが処理されます。したがって、ブラウザベースのクライアントはここにオリジンを記載する必要があります。ブラウザ以外のクライアントはそのようなヘッダーを送らないため、エントリは不要です。各エントリはパターン ^[a-z][a-z0-9+.-]*://(?:[a-z0-9._-]+|\[[0-9a-f:.]+\])(?::[0-9]{1,5})?$ に一致します。デフォルト: [] |
limits | object | いいえ | HTTP リスナーが受け付けるトラフィックに適用する上限で、1 つの呼び出し元がサービスを提供するプロセスを枯渇させられないようにします。単一リクエストの大きさ、同時に実行されるリクエストの数、1 つの呼び出し元が送信できる速さを制限します。いずれも無効にすることはできません。 |
authorization | object | いいえ | このサーバーが、呼び出し元の提示するベアラートークンについて宣言する内容です。トークンを発行する認可サーバー、トークンの発行対象となるリソースとしてこのサーバーが自身について公開するアドレス、必要に応じてその認可サーバーの検証鍵を読み込むファイル、そして必要に応じて、前段のプロキシが代わりにトークンを検証する場合にそのプロキシが設定するヘッダーを指定します。HTTP トランスポートが選択されている場合は常に issuer と resource が必須であり、これらがないとリスナーは何もバインドする前に拒否されます。標準入出力で通信するサーバーはこれらをいずれも読み込みません。どちらも、リスナーが提供する OAuth の保護リソースメタデータドキュメントで公開されます。このドキュメントは、HTTP の呼び出し元が資格情報を求められずに受け取る唯一の応答です。クライアントはトークンの取得先を知るためにこれを読むからです。このブロックは秘密情報を保持しません。トークンは呼び出し元が自身のリクエストで提示するものであり、設定フィールドになることはありません。また jwks_file が指すのは公開検証鍵であり、署名するものではありません。 |
deny_reach | string (enum)[] | いいえ | 呼び出し元のトークンの内容にかかわらず、このサーバーが持たない到達範囲の種類です。各操作は自身の効果がどこまで及ぶかを宣言します。読み取りやレンダリングを行い何も残さない操作は none、このプロセスが提供するワークスペース内に書き込む操作は workspace、公開・署名・取り下げを行う操作は registry、ホスト上のすべてのワークスペースが共有するものを変更する操作は machine です。ここに種類を指定すると、その種類のツールはすべてこのサーバーから取り除かれます。取り除かれたツールは、すべての呼び出し元に対して、ツール一覧にも describe-capabilities の応答にも現れず、それでも呼び出すとこの設定を示して拒否されます。どのスコープでも許可できないためです。デフォルトは空であり、サーバーは呼び出し元のスコープが許可するものをすべて提供します。これは、スコープが呼び出し元ごとに設ける制限に加えて、サーバーが自身に課す制限です。読み取りのみを提供するサーバーは、ここに書き込みを行う 3 種類を指定すれば、すべてのスコープを持つトークンの呼び出し元に対しても公開できなくなります。machine の指定は受け付けられますが何も変わりません。その種類のツールは HTTP 上では一切提供されないからであり、これは設定ではなくトランスポートの性質です。リスナーの起動時に読み込まれます。4 種類以外の値は設定の読み込み時に拒否され、変更には再起動が必要です。サーバーが標準入出力で通信している間はまったく読み込まれません。その場合の呼び出し元はプロセスを起動した本人だからです。各エントリに許可される値: "none"、"workspace"、"registry"、"machine"。Default: [] |
announce_tools | string[] | いいえ | このサーバーが告知するツールで、ツール一覧が報告するとおりの名前で指定します。キーを省略すると、このサーバーが持つすべてのツールが告知されます。これはプロトコルに従うクライアントが期待する動作であり、クライアントはツール一覧全体を取得し、そのうちどれだけをモデルに提示するかを自分で決めます。リストを書くと、まさにそのツールだけが告知されます。外されたツールはツール一覧にも describe-capabilities の応答にも現れず、名前で呼び出すとこの設定を示して拒否されます。空のリストを書くと何も告知されません。相手側のクライアントが登録するツール数に上限を設けている場合(接続中のすべてのサーバーをまたいで上限を適用するクライアントもあります)にこれを設定し、そのクライアントが必要とするツールを指定します。これは告知される内容を絞り込むだけです。機能を完全に取り除く deny_reach を広げることも、呼び出し元のトークンが持つスコープを広げることもできません。ここで指定したツールが deny_reach の取り除く種類であれば、ツール一覧には現れず、呼び出すとその設定を示して拒否されます。ここで指定したツールが呼び出し元のスコープで許可されない場合は一覧には載りますが、呼び出すとそれを許可するスコープを示して拒否されます。すべての名前は、このバイナリが持つツールのものでなければなりません。どのツールにも該当しない名前はサーバーの起動時に拒否されます。そうしなければ、より狭い範囲を求めた人に、何の通知もなく別の範囲が提供されてしまうからです。別プロセスで aggrega コマンドを実行する cli- 系の名前は両方のトランスポートで受け付けられますが、HTTP 上では何も告知しません。HTTP ではそのようなツールはどの呼び出し元にも提供されないからです。両方のトランスポートでサーバーの起動時に読み込まれるため、告知されるセットはプロセスの存続中は固定され、変更には再起動が必要です。 |
health | object | いいえ | このプロセスが稼働しているか、呼び出しに応答する準備ができているかをスーパーバイザーが問い合わせる場所です。この 2 つのチェックは専用のアドレスで応答され、listen が指定するアドレスでは決して応答されません。エンドポイントへのリクエストはすべてベアラートークンを伴うため、そこでプローブに応答すると、エンドポイントに到達できるあらゆるものに、認証なしでプロセスの状態を読み取る手段と、プロセスに自由に処理をさせる手段を与えてしまうからです。エンドポイントは /healthz と /readyz に対して、提供しないすべてのパスと同じく、トークンの有無にかかわらず 404 を返します。 |
追加のプロパティは許可されません。
aggrega-config.mcp.tls
サービスを提供するプロセス内で TLS を終端するための証明書と鍵です。両方を設定すると、listen が指定するリスナーから直接 HTTPS を提供します。両方を未設定のままにすると平文で提供し、listen はループバックまたは Unix ソケットに限定されます。これは前段のプロキシが証明書を保持する場合に使う形です。どちらのキーもディスク上のファイルへのパスであり、鍵の素材をインラインで保持することはありません。
| プロパティ | 種類 | 必須 | 説明 |
|---|---|---|---|
cert_file | string | いいえ | リスナーが提示する PEM 証明書チェーンへのパスで、プロセスの起動時に読み込まれます。key_file と一緒に設定します。デフォルトは空であり、その場合リスナーは平文で提供し、listen はループバックまたは Unix ソケットに限定されます。Default: "" |
key_file | string | いいえ | cert_file の証明書に対応する PEM 秘密鍵へのパスで、プロセスの起動時に読み込まれます。それと一緒に設定します。ファイルへのパスであり、インラインの鍵素材ではありません。デフォルトは空であり、その場合リスナーは平文で提供し、listen はループバックまたは Unix ソケットに限定されます。Default: "" |
追加のプロパティは許可されません。
aggrega-config.mcp.limits
HTTP リスナーが受け付けるトラフィックに適用する上限で、1 つの呼び出し元がサービスを提供するプロセスを枯渇させられないようにします。単一リクエストの大きさ、同時に実行されるリクエストの数、1 つの呼び出し元が送信できる速さを制限します。いずれも無効にすることはできません。
| プロパティ | 種類 | 必須 | 説明 |
|---|---|---|---|
max_body_bytes | integer | いいえ | リスナーが受け付けるリクエストボディの最大サイズ(バイト単位)です。ボディがこれを超えるリクエストは 413 で拒否され、ボディは上限を超えて読み込まれません。デフォルトは 4194304(4 MiB)で、オーサリングドキュメント全体を運ぶツール呼び出しを十分に上回り、かつ 1 つの呼び出し元がプロセスのメモリの大きな割合を占有できる値を十分に下回ります。最小値は 1 であり、上限を無効にする値はありません。呼び出し元が正当な理由でより大きなドキュメントを送る場合は引き上げてください。最小値: 1。Default: 4194304 |
max_concurrent_requests | integer | いいえ | リスナーが同時に実行するリクエストの数です。すでにその数のリクエストが処理中のときに到着したリクエストは、キューに入れられずに 503 で拒否されます。これにより、呼び出し元は見えない処理の後ろで待たされることなく、再試行するよう伝えられます。デフォルトは 16 で、複数のツール呼び出しを同時に処理する余地を残しつつ、小さなホストの応答性を保ちます。大きなホストでは引き上げてください。最小値は 1 であり、上限を無効にする値はありません。最小値: 1。Default: 16 |
requests_per_minute | integer | いいえ | 1 つの呼び出し元が 1 分間に送信できるリクエストの数です。サーバー単位ではなく呼び出し元単位で、つまり呼び出し元のトークンが示すサブジェクト、または信頼されたプロキシが表明した ID に対して数えられるため、忙しい呼び出し元が他の呼び出し元の割り当てを消費することはありません。呼び出し元はこの数までまとめて送信できます。その後、割り当ては 60 / requests_per_minute 秒ごとに 1 リクエストずつ一定の割合で回復し、残りがない状態で到着したリクエストは 429 で拒否されます。デフォルトは 120 で、持続的に毎秒 2 リクエストに相当します。これはワークスペースを操作するアシスタントが送信する量をはるかに上回りつつ、ループに陥ったクライアントに対する制限としても機能します。最小値は 1 であり、上限を無効にする値はありません。最小値: 1。Default: 120 |
追加のプロパティは許可されません。
aggrega-config.mcp.authorization
このサーバーが、呼び出し元の提示するベアラートークンについて宣言する内容です。トークンを発行する認可サーバー、トークンの発行対象となるリソースとしてこのサーバーが自身について公開するアドレス、必要に応じてその認可サーバーの検証鍵を読み込むファイル、そして必要に応じて、前段のプロキシが代わりにトークンを検証する場合にそのプロキシが設定するヘッダーを指定します。HTTP トランスポートが選択されている場合は常に issuer と resource が必須であり、これらがないとリスナーは何もバインドする前に拒否されます。標準入出力で通信するサーバーはこれらをいずれも読み込みません。どちらも、リスナーが提供する OAuth の保護リソースメタデータドキュメントで公開されます。このドキュメントは、HTTP の呼び出し元が資格情報を求められずに受け取る唯一の応答です。クライアントはトークンの取得先を知るためにこれを読むからです。このブロックは秘密情報を保持しません。トークンは呼び出し元が自身のリクエストで提示するものであり、設定フィールドになることはありません。また jwks_file が指すのは公開検証鍵であり、署名するものではありません。
| プロパティ | 種類 | 必須 | 説明 |
|---|---|---|---|
issuer | string | いいえ | このリスナーが受け付けるトークンを発行する認可サーバーのアドレスです。そのサーバー自身が示す issuer 識別子のとおりに記述します(例: https://login.example.com)。これは protected-resource メタデータドキュメントの authorization_servers リストに公開され、クライアントはこれによってこのリスナー用のトークンをどこで取得するかを知ります。既定値は空ですが、これは使用可能な値ではありません。スキームとホストを含む完全なアドレスが指定されていない限り、何かがバインドされる前にリスナーは拒否されます。認可サーバーがこのマシン上で動作する場合を除き、https アドレスを指定します。平文の http は localhost、127.0.0.1、::1 などのループバックホストに対してのみ受け付けられ、それ以外のホストでの平文 http の issuer は、何かがバインドされる前に、このキーを示して https アドレスを求める形で拒否されます。これは、鍵を issuer から読み込む場合、jwks_file から読み込む場合、前段の trusted_proxy がトークンを検査する場合のいずれでも同じです。すべてのクライアントはトークンを取得するために issuer へ送られるためです。既定値: "" |
resource | string | いいえ | このサーバーが、呼び出し元から到達されるとおりに自身について公開するアドレスです(例: https://mcp.example.com/mcp)。前段のプロキシが提示するホストを含め、呼び出し元が実際に使うアドレスを記述します。これは、クライアントがこのサーバー用のトークンを要求するときに認可サーバーに渡す識別子であり、protected-resource メタデータドキュメントの resource フィールドとしてそのまま公開されるためです。そのドキュメントが提供される場所は、ホストとパスの間に /.well-known/oauth-protected-resource を挿入することでここから導出されます。https://mcp.example.com/mcp として公開されたサーバーは、https://mcp.example.com/.well-known/oauth-protected-resource/mcp でドキュメントを提供し、さらにその well-known パスの後に何も付けない場所でも提供します。後者はクライアントが 2 番目に参照する場所です。トークンは、このアドレスがそのトークンの示す audience に含まれる場合にのみ受け付けられます。既定値は空ですが、これは使用可能な値ではありません。スキームとホストを含む完全なアドレスが指定されていない限り、何かがバインドされる前にリスナーは拒否されます。既定値: "" |
jwks_file | string | いいえ | このサーバーが受け付けるトークンの検証に使う JSON Web Key Set を保持するファイルへのパスで、プロセスの起動時に読み込まれます。既定値は空で、これが通常のケースです。鍵は認可サーバー自体から読み込まれます。issuer にどこで公開しているかを問い合わせ、示されたアドレスから取得します。保持している鍵セットにない鍵識別子で署名されたトークンが届いた場合は、一度だけ再読み込みされます。ワークスペースがオフラインの場合はこれを設定します。その場合、これがないと何かがバインドされる前にリスナーは拒否されます。オフラインのワークスペースはネットワーク要求を行わず、鍵を取得する他の方法がないためです。このときファイルは受け付ける唯一の鍵を保持し、認可サーバーには一切接続しません。ファイルが保持するのは公開検証鍵であり、署名に使うものは決して含みません。相対パスは、それを宣言した設定ファイルのディレクトリを基準に解決されます。既定値: "" |
trusted_proxy | object | いいえ | ここで bearer トークンを検証する代わりに、前段のプロキシが設定するヘッダーから呼び出し元が誰であるかを読み取ります。次の両方が成り立つ場合にのみ設定します。前段のプロキシ自身がトークンを検証すること、そしてそのプロキシ以外はリスナーに到達できないことです。これを設定した場合、listen はループバックまたは Unix ソケットでなければならず、それ以外のアドレスは、何かがバインドされる前に両方の設定を示して拒否されます。ヘッダーの信頼性は、それを設定できる呼び出し元の範囲にちょうど等しく、ネットワークから到達できるアドレスではどの呼び出し元も任意のヘッダーを設定できます。そのため、そのようなアドレスでこのモードのリスナーを動かすと、どの呼び出し元も誰にでもなりすませてしまいます。これを設定すると、トークンは一切読み取られません。Authorization ヘッダーからも他のどこからも読み取られず、鍵セットも取得されません。呼び出し元の ID は principal_header の値となり、そのヘッダーを持たないリクエストには 401 が返され、読み取られるのはここで指定した 2 つのヘッダーだけです。既定どおり省略すると、このサーバーが bearer トークンを自ら検証します。 |
追加のプロパティは許可されません。
aggrega-config.mcp.authorization.trusted_proxy
ここで bearer トークンを検証する代わりに、前段のプロキシが設定するヘッダーから呼び出し元が誰であるかを読み取ります。次の両方が成り立つ場合にのみ設定します。前段のプロキシ自身がトークンを検証すること、そしてそのプロキシ以外はリスナーに到達できないことです。これを設定した場合、listen はループバックまたは Unix ソケットでなければならず、それ以外のアドレスは、何かがバインドされる前に両方の設定を示して拒否されます。ヘッダーの信頼性は、それを設定できる呼び出し元の範囲にちょうど等しく、ネットワークから到達できるアドレスではどの呼び出し元も任意のヘッダーを設定できます。そのため、そのようなアドレスでこのモードのリスナーを動かすと、どの呼び出し元も誰にでもなりすませてしまいます。これを設定すると、トークンは一切読み取られません。Authorization ヘッダーからも他のどこからも読み取られず、鍵セットも取得されません。呼び出し元の ID は principal_header の値となり、そのヘッダーを持たないリクエストには 401 が返され、読み取られるのはここで指定した 2 つのヘッダーだけです。既定どおり省略すると、このサーバーが bearer トークンを自ら検証します。
| プロパティ | 種類 | 必須 | 説明 |
|---|---|---|---|
principal_header | string | はい | 前段のプロキシが呼び出し元の ID を入れるヘッダーです(例: X-Forwarded-User)。HTTP ヘッダー名として記述します。英字、数字、ハイフン、およびヘッダー名に使えるその他の文字(!#$%&'*+.^_|~ とバッククォート)を使い、空白、コロン、その他の区切り文字は含めません。それ以外の形の名前は、設定ファイルの読み込み時に、ファイルとキーを示して拒否されます。そのようなヘッダーを持てるリクエストは存在しないためです。空の名前も拒否されます。ブロックは前段のプロキシが検証すると述べているのに、このサーバーが自らトークンを検査し続けることになるためです。このモードを無効にするには、trusted_proxy を省略します。ヘッダーの値は書かれたとおりに受け取られ、何とも比較されません。これは、このサーバーが自ら検証するトークンの subject が記録され、何とも比較されないのと同じです。このモードではこれが認証情報のすべてであるため、trusted_proxy を設定する場合は常に必須であり、これを持たずに届いたリクエストには 401 が返されます。パターン: ^[!#$%&'*+.^_`|~0-9A-Za-z-]+$。 |
scopes_header | string | いいえ | 前段のプロキシが呼び出し元に付与されたスコープを空白区切りで入れるヘッダーです(例: X-Forwarded-Scopes)。principal_header と同じ形の HTTP ヘッダー名として記述するか、空のままにします。それ以外の形の名前は、設定ファイルの読み込み時に、ファイルとキーを示して拒否されます。そのようなヘッダーを持てるリクエストは存在せず、どの呼び出し元にもスコープが付与されなくなるためです。既定値は空で、どの呼び出し元にもスコープを付与しません。名前が何であれ、これと principal_header 以外のヘッダーは読み取られません。パターン: ^[!#$%&'*+.^_`|~0-9A-Za-z-]*$。既定値: "" |
追加のプロパティは許可されません。
aggrega-config.mcp.health
このプロセスが稼働しているか、呼び出しに応答する準備ができているかをスーパーバイザーが問い合わせる場所です。この 2 つのチェックは専用のアドレスで応答され、listen が指定するアドレスでは決して応答されません。エンドポイントへのリクエストはすべてベアラートークンを伴うため、そこでプローブに応答すると、エンドポイントに到達できるあらゆるものに、認証なしでプロセスの状態を読み取る手段と、プロセスに自由に処理をさせる手段を与えてしまうからです。エンドポイントは /healthz と /readyz に対して、提供しないすべてのパスと同じく、トークンの有無にかかわらず 404 を返します。
| プロパティ | 種類 | 必須 | 説明 |
|---|---|---|---|
listen | string | いいえ | liveness チェックと readiness チェックに応答するアドレスです。listen と同じ 2 つの形式、すなわち host:port、または unix: に続けてファイルシステムのパスを指定します。デフォルトは空で、この場合 2 つ目のリスナーは起動されず、どちらのチェックにもどこからも応答しません。アドレスを設定すると、GET /healthz にはプロセスが動作を開始した時点から 200 を返し、GET /readyz にはワークスペースの解決とエンドポイントのバインドが完了するまでは 503、それ以降は 200 を返します。これは supervisor が必要とする区別です。起動しているプロセスが、すでに呼び出しに応答できるプロセスであるとは限らないためです。どの応答も本文が空のステータスコードで、トークンは要求されず、ヘッダーも読み取られません。このアドレス上のその他のパスは 404、この 2 つのパスに対するその他のメソッドは 405 になります。listen とは異なり、このアドレスはループバックや Unix ソケットに限定されず、拒否されるアドレスもありません。本来の用途どおりこれらのいずれかを指定してください。また、選んだアドレスに到達できるものはすべて、この 2 つの応答を読み取れることに注意してください。Default: "" |
追加のプロパティは許可されません。
定義
ReleaseCatalogConfig
1 つの Release 専用のカタログディレクトリです。workspace ブロックが持つものと同じ 2 つのキーを、その Release にスコープしたものです。
| プロパティ | 種類 | 必須 | 説明 |
|---|---|---|---|
catalog_dirs | string[] | いいえ | この Release がワークスペースの catalog_dirs の代わりにローカルエンティティを読み込むカタログディレクトリです。各エントリは、それを宣言したファイルからの相対パスとして解決されます。ワークスペースのリストと同じ、順序付きで最初に見つかったものが優先される検索スタックであり、ワークスペースルートの catalog ディレクトリが存在し、かつリスト内のどのエントリにもすでに含まれていない場合は、その後に読み込まれます。省略した場合、Release はワークスペースのリストを使用します。[] と記述した場合、ローカルカタログを一切読み込みません。 |
catalog_dirs_append | string[] | いいえ | この Release のリスト(エントリが記述している場合はその catalog_dirs、そうでなければワークスペースのもの)の後に追加されるカタログディレクトリです。各エントリは、それを宣言したファイルからの相対パスとして解決されます。Default: [] |
追加のプロパティは許可されません。
RegistryConfig
1 つの OCI レジストリホストにスコープした設定と署名の信頼ポリシーです。
| プロパティ | 種類 | 必須 | 説明 |
|---|---|---|---|
host | string | はい | これらの設定が適用されるレジストリホストです(例: hub.aggrega.ai)。プッシュ/プル対象のレジストリホストと照合されるため、その照合で使われる表記で記述します。ドットを含む小文字のホスト名、localhost、ポートが続く単一の名前(registry:5000)、IPv4 アドレス、または角括弧で囲んだ IPv6 アドレスのいずれかで、それぞれ任意で :port を付けられます。スキーム、パス、認証情報、空白、大文字は含めません。HTTPS で接続するホストのポート 443 はそのホストのデフォルトポートであり、これを記述すると、そのように表記されたエントリは決して見つからないため、設定の読み込み時に拒否され、ポートなしで記述すべきホストが示されます。localhost やその他のループバックアドレスはプレーンな HTTP で接続されるため、そこでは 443 は通常のポートであり、そのまま保持されます。aggrega registry add と aggrega config init --registry は、引数で指定されたホストをキーとしてエントリを作成し、この表記に従わないものを拒否します。ホストは表記のみで判断され、名前が解決できるか、そこでレジストリが応答するかは確認されません。パターン: ^(?:(?:(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?|localhost|(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])(?:\.(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])){3}|\[(?:(?:[0-9a-f]{1,4}:){7}[0-9a-f]{1,4}|(?:[0-9a-f]{1,4}:){1,7}:|(?:[0-9a-f]{1,4}:){1,6}:[0-9a-f]{1,4}|(?:[0-9a-f]{1,4}:){1,5}(?::[0-9a-f]{1,4}){1,2}|(?:[0-9a-f]{1,4}:){1,4}(?::[0-9a-f]{1,4}){1,3}|(?:[0-9a-f]{1,4}:){1,3}(?::[0-9a-f]{1,4}){1,4}|(?:[0-9a-f]{1,4}:){1,2}(?::[0-9a-f]{1,4}){1,5}|[0-9a-f]{1,4}:(?::[0-9a-f]{1,4}){1,6}|:(?:(?::[0-9a-f]{1,4}){1,7}|:))\])(?::(?:[1-9][0-9]{0,3}|[1-5][0-9]{4}|6[0-4][0-9]{3}|65[0-4][0-9]{2}|655[0-2][0-9]|6553[0-5]))?|[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?:(?:[1-9][0-9]{0,3}|[1-5][0-9]{4}|6[0-4][0-9]{3}|65[0-4][0-9]{2}|655[0-2][0-9]|6553[0-5]))$。 |
name | string | いいえ | このレジストリの任意のわかりやすい別名です。ホストが識別子であり、name はレジストリを指定するあらゆる箇所(例えば --registry や default_registry)でこのエントリのホストに解決される便宜的なセレクタです。別名はエントリ間で一意でなければなりません。 |
trusted_identities | TrustedIdentity[] | いいえ | このレジストリからプルしたアーティファクトに対して受け入れられるキーレス署名 ID の OR セットです。署名は、その証明書がいずれか 1 つのエントリに一致すれば検証に成功します。キーレス検証パスで使用されます。Default: [] |
trusted_deprecation_identities | TrustedIdentity[] | いいえ | このレジストリからプルしたアーティファクトに対する遡及的な非推奨マーカーへの署名を、追加で認められるキーレス ID の OR セットです。非推奨マーカーは、その署名が元のアーティファクトの署名者、またはここにあるいずれかのエントリに一致した場合に尊重されます。これにより、レジストリの所有者やセキュリティチームは、アーティファクト自体への署名を信頼されることなく、元の公開者がもはや対応できないアーティファクトを取り下げられます。非推奨の検出パスでのみ使用され、アーティファクト署名の信頼セットを広げることはありません。Default: [] |
public_key | string | いいえ | キー付きモードのレジストリ用に固定する cosign 互換の公開鍵で、PEM ブロックとしてインラインで記述します。-----BEGIN PUBLIC KEY----- 行(または -----BEGIN RSA PUBLIC KEY-----)から対応する -----END 行までのテキストで、aggrega registry add --key が鍵ファイルからコピーする形式です。設定すると、このレジストリからの署名はキーレス ID ではなくこの鍵に対してオフラインで検証されます。-----BEGIN … PUBLIC KEY----- 行を含まない値は、設定ファイルの読み込み時にファイルとエントリを示して拒否され、誤ってここに貼り付けられた秘密鍵も同様です。鍵は値に含まれる PEM ブロックから読み込まれ、そのブロックより前のテキストは無視されるため、この行は値のどこにあってもかまいません。ここで確認されるのはその行だけで、ブロックがデコード可能な鍵を保持しているかどうかは、このレジストリからの署名をそれに対して検証する際に判明します。この値は機密(x-aggrega-sensitive)として宣言されているため、拒否された値(とりわけ誤って選ばれた秘密鍵)が引用されることはありません。拒否時には、ファイル、エントリ、値が満たさなかった制約(上記のパターン、または文字列型)が示され、値の位置には <redacted> が表示されます。読み込みに成功した公開鍵は、記述どおりに読み込まれ表示されます。パターン: -----BEGIN [A-Z ]*PUBLIC KEY-----。 |
trusted_root | string | いいえ | エアギャップ環境でのキーレス検証用に固定する Sigstore 信頼ルートバンドルへの任意のパスです。設定すると、キーレスの信頼アンカーはネットワークを使わずにこのファイルから読み込まれます。空の場合は、パブリックグッドの信頼ルートが取得されキャッシュされます。 |
advisory | 真偽値 | いいえ | true の場合、このレジストリでの署名検証の失敗は、プルを停止せずに警告に格下げされます。検証は引き続き実行され、失敗は報告されますが、プルは続行されます。デフォルトは false です。Default: false |
skip_signature_verification | 真偽値 | いいえ | ホスト単位の、署名検証を緊急時に無効化するオプトアウトです。グローバルなものと同じ skip_signature_verification スイッチを、配置によってこのホストにスコープしたものです。トップレベルの signing.required ポリシーを無効にすることはありません。組織が要求する署名は、このスイッチに関係なくこのホストでも検証され、それを無効にできるのはグローバルスイッチだけです。これを同じホストのレジストリ単位の signing.required と併用することは許可されており、プッシュ時の署名必須とプル時の検証スキップを組み合わせることになります。ホスト単位の必須設定は(トップレベルのものと異なり)ホスト単位のスキップの影響を受けるため、検証側ではスキップが優先されます。デフォルトは false です。Default: false |
signing | SigningConfig | いいえ | このレジストリの署名ブロックです。キーレスサービスの URL、任意のキー付き鍵のパス、ホスト単位の信頼スタンスを持ちます。エンドポイントのフィールドは、このホストへのプッシュについてグローバルな signing ブロックを上書きし、CLI フラグは両方を上書きします。required と kinds のスコープは配置から決まります。レジストリエントリの下では、1 つの信頼スタンスをこのホストにスコープします(スコープ内の未署名アーティファクトの公開は拒否され、未署名のものの利用も拒否されます)。これは、トップレベルの signing ブロックがすべてのレジストリについて持つものと同じ概念です。 |
追加のプロパティは許可されません。
SigningConfig
署名ブロックです。キーレスサービスの URL、鍵ファイルへの任意のポインタ、および信頼方針(required と kinds)を持ちます。トップレベルに置くとすべてのレジストリに適用され、registries[] のエントリの下に置くとそのホストに適用されます。各フィールドはスコープを配置から読み取ります。required は両方向を対象とする単一の信頼方針です(署名のないスコープ内の push は拒否され、署名のないスコープ内の pull も拒否されます)。セキュリティ: このブロックは秘密情報を保持しません。OIDC アイデンティティトークンが設定フィールドになることはなく(短命で、実行時に渡されます)、key_path は鍵ファイルへのパスであり、インラインの鍵バイトではありません。これは検証側の非対称性に対応しています。検証側ではインラインの public_key が許可されますが、署名側は鍵のパスのみを持ちます。HTTP 経由で接続される aggrega mcp サーバーはどちらの配置の key_path も参照しないため、そのようなリスナー経由では鍵による署名はできません。リスナーが応答する呼び出しは、その呼び出し自体が持つアイデンティティトークンでのみ署名します。
| プロパティ | 種類 | 必須 | 説明 |
|---|---|---|---|
fulcio_url | string | いいえ | キーレス署名用の Fulcio 認証局の URL です。未設定の場合は public-good の Fulcio インスタンスが使用されます。絶対 https URL として記述します。https://、ホスト、任意でポートとパスから成り、空白は含みません(例: https://fulcio.sigstore.dev)。スキームのないもの(fulcio.example.com)や http:// で始まるものなど、それ以外の形の値は設定ファイルの読み込み時に拒否され、ファイルとキーが示されます。ファイルは他の何かが上に適用される前に検査されるため、AGGREGA_SIGNING_FULCIO_URL、--fulcio-url フラグ、またはエディタやアシスタントからの公開リクエストで渡された同じエンドポイントには、この形は求められません。パターン: ^https://[^\s/?#]+(?:[/?#]\S*)?$。 |
rekor_url | string | いいえ | キーレス署名用の Rekor 透明性ログの URL です。未設定の場合は public-good の Rekor インスタンスが使用されます。絶対 https URL として記述します。https://、ホスト、任意でポートとパスから成り、空白は含みません(例: https://rekor.sigstore.dev)。スキームのないもの(rekor.example.com)や http:// で始まるものなど、それ以外の形の値は設定ファイルの読み込み時に拒否され、ファイルとキーが示されます。ファイルは他の何かが上に適用される前に検査されるため、AGGREGA_SIGNING_REKOR_URL、--rekor-url フラグ、またはエディタやアシスタントからの公開リクエストで渡された同じエンドポイントには、この形は求められません。パターン: ^https://[^\s/?#]+(?:[/?#]\S*)?$。 |
timestamp_url | string | いいえ | キーレス署名用の RFC3161 タイムスタンプ局の URL です。デフォルトはありません。未設定の場合はタイムスタンプ局に接続せず、キーレス署名の信頼される時刻は透明性ログのエントリから得られます。絶対 https URL として記述します。https://、ホスト、任意でポートとパスから成り、空白は含みません(例: https://tsa.example.com/api/v1/timestamp)。スキームのないもの(tsa.example.com)や http:// で始まるものなど、それ以外の形の値は設定ファイルの読み込み時に拒否され、ファイルとキーが示されます。ファイルは他の何かが上に適用される前に検査されるため、AGGREGA_SIGNING_TIMESTAMP_URL、--timestamp-url フラグ、またはエディタやアシスタントからの公開リクエストで渡された同じエンドポイントには、この形は求められません。パターン: ^https://[^\s/?#]+(?:[/?#]\S*)?$。 |
key_path | string | いいえ | オフラインの鍵による署名に使う、保持している ECDSA P-256 秘密鍵 PEM ファイルへのパスです。ファイルへのパスであり、インラインの鍵素材ではありません。未設定の場合はキーレスの経路が使われます。HTTP 経由で接続される aggrega mcp サーバーは、この鍵がどこで設定されていても(トップレベルの signing ブロック、レジストリエントリの署名ブロック、または AGGREGA_SIGNING_KEY_PATH)参照しません。そのようなリスナーが応答する呼び出しは、呼び出し自体が持つアイデンティティトークンでのみ署名するか、拒否されます。標準入出力経由で接続されるサーバーは、ターミナルと同様にこの鍵で署名します。 |
required | 真偽値 | いいえ | このブロックのスコープに対する単一の信頼方針です。true の場合、スコープ内のアーティファクト種別の公開には署名が必要となり(署名のないスコープ内の push は拒否されます)、その利用にも署名が必要となります(署名のないスコープ内の pull は拒否されます)。スコープは配置から読み取られます。トップレベルの signing ブロックではすべてのレジストリを対象とし、registries[] エントリの signing ブロックではその 1 つのホストを対象とします。1 つの名前、1 つの役割で、両方のスコープに対応します。トップレベルの方針は設定のカスケード全体で単調に合成されます。いずれかの層が true に設定すると実効値は true になり、優先度の低い層がそれを元に戻すことはできません。そのため、通常の設定編集では解除できません。デフォルトは false です。Default: false |
kinds | string[] | いいえ | required の対象を特定のアーティファクト種別に絞ります。空、または all のエントリ 1 つの場合は署名可能なすべての種別を意味します。それ以外の場合、方針は列挙された種別にのみ適用され、エンティティの kind: の値と照合されます(例: Component、Feature、Recipe、FeatureRecipe、SchemaLibrary、MappingLibrary、Aggregate、Plugin)。トップレベルの signing ブロックでは、カスケード全体で和集合として合成されます。層はスコープを広げることはできますが、狭めることはできません。スコープは required と同様に配置から読み取られます。Default: [] |
追加のプロパティは許可されません。
TrustedIdentity
受け入れ可能なキーレス署名アイデンティティ 1 つです。証明書のサブジェクト(OIDC アイデンティティ)と、それを保証した OIDC 発行者の組です。
| プロパティ | 種類 | 必須 | 説明 |
|---|---|---|---|
identity | string | いいえ | 正確な証明書のサブジェクト代替名です。短命の署名証明書に結び付けられた OIDC アイデンティティです(例: メンテナーのメールアドレスや CI ワークフローの URI)。 |
identity_regexp | string | いいえ | 証明書のサブジェクトと照合される正規表現で、正確な identity の代わりに使います(例: ある組織配下の任意のワークフローを受け入れる場合)。 |
issuer | string | はい | アイデンティティトークンを発行した OIDC 発行者の URL です(例: https://accounts.google.com や https://token.actions.githubusercontent.com)。 |
追加のプロパティは許可されません。
PluginRef
アタッチメントがエントリ関数を指定できるソケット(governance リストと linter リスト)にアタッチされる Wasm プラグインへの参照です。エントリポイントが固定されているソケットでは、代わりに FixedEntryPluginRef を使用します。これは同じフィールドを function なしで持ちます。uri と capability の組み合わせでプラグインを選択します。uri のみの場合は直接アタッチです(その識別子のプラグインがそのままアタッチされます。横断的ソケットのプラグインは提供する capability を宣言しないため、これらのソケットではこの方法を使います)。capability のみの場合は、その capability を提供するプラグインが解決されます(Recipe が spec.capability でバインドする素の capability 名。例: helm)。両方を指定すると曖昧さが解消されます。複数のプラグインがその capability を提供するフェデレーションカタログにおいて、capability が解決対象を指定し、uri がそのプラグインの素の識別子によって、どのパブリッシャーのプラグインがそれを提供するかを選択します。function はソケットのデフォルトのエントリ関数を上書きします。省略した場合は、ソケットのドキュメントに記載されたデフォルトが適用されます。governance エントリでは、そのデフォルトは role から決まります。role は governance のアタッチメントロールを指定し、governance エントリでのみ読み取られます。with は、プラグインが読み取るアタッチ時の任意の入力を保持します。
| プロパティ | 種類 | 必須 | 説明 |
|---|---|---|---|
uri | string | いいえ | プラグイン識別子: Plugin エンティティの素の識別子(<pluginType>/<name> 形式のパス。例: governance/redact や provider/helm)、ローカルファイルシステムのパス、またはレジストリのエイリアスです。任意: エントリは代わりに capability でプラグインを選択することもできます。末尾に任意で :version を付けると、他のバージョン指定と同じ 3 つの形式(指定なし、完全一致 :1.0.0、メジャー互換範囲 :^1.0.0)でバージョンを固定します。 |
role | string (enum) | いいえ | governance アタッチメントがバインドされるパイプラインロールで、governance エントリでのみ読み取られます。annotation-transform はアノテーション展開の前に解決済みコンポーネントへアノテーションを注入するため、バインドされた注入は Feature のアタッチメントになります。label-transform はトポロジー構築時にトポロジーグラフのノードラベルを自動でタグ付けします。ir-verdict は静的解析時に IR グラフに対する受理/拒否の判定を下します。render-verdict はレンダリング時にレンダリング済みアーティファクトに対する判定を下します。プラグインが出力できる内容を決めるのは、プラグインが宣言する kind ではなくロールです。判定ロールの出力は判定としてのみ読み取られ、変更として適用されることはありません。変換ロールの出力は、ホストによってそのファセット(アノテーションまたはラベル)に限定されます。ロールはデフォルトのエントリ関数も選択します(annotation-transform → transform_annotations、label-transform → mutate、ir-verdict → verdict_ir、render-verdict → verdict_render)。許可される値: "annotation-transform"、"label-transform"、"ir-verdict"、"render-verdict" |
capability | string | いいえ | このエントリがプラグインを選択する対象の provider capability です。Recipe が spec.capability でバインドする素の capability 名です(例: helm、compose)。任意: エントリは代わりに uri でプラグインを直接アタッチすることもできます。provider バインディングは、フェデレーションカタログにおいてどのパブリッシャーのプラグインが capability を提供するかを選択するためにこれを使用します。横断的ソケットではこれを空のままにし、uri でアタッチします。 |
function | string | いいえ | ソケットのデフォルトのエントリ関数に対する任意の上書きです。省略した場合は、ソケットのドキュメントに記載されたデフォルトが適用されます(governance annotation-transform → transform_annotations、governance label-transform → mutate、governance ir-verdict → verdict_ir、governance render-verdict → verdict_render、linter → lint_rules)。上書きではプラグインが宣言する任意のエクスポートを指定できますが、指定したエクスポートはそのソケットが読み取る出力形状を返す必要があります。その出力に形状が宣言していないトップレベルのフィールドが含まれる場合、呼び出されたエクスポートと想定外のフィールドを示してビルドが停止します。このチェックはどのトップレベルのフィールド名が存在するかを読み取るもので、どれが欠けているかやその下に何がネストしているかは読み取らないため、出力の完全な検証ではありません。 |
with | PluginRefWith | いいえ | プラグインが読み取るアタッチ時の任意の入力です。両メンバーとも任意でソケットに依存しないため、どのソケットでもこの仕組みを再利用できます。 |
追加のプロパティは許可されません。
FixedEntryPluginRef
エントリポイントがアタッチメントによって指定されるのではなく固定されているソケット(importer リストと providers バインディング)にアタッチされる Wasm プラグインへの参照です。PluginRef と同じフィールドを function なしで持ちます。importer ソケットはそのソケット契約が指定する 1 つのエントリ関数を呼び出し、provider は選択可能な 1 つのエントリではなくフェーズごとの固定されたエクスポート群を駆動するため、どちらのリストにも function が指定するエントリは存在せず、このキーはそこでは受け付けられません。uri と capability の組み合わせでプラグインを選択します。uri のみの場合は直接アタッチです(その識別子のプラグインがそのままアタッチされます。importer ソケットのプラグインは提供する capability を宣言しないため、このソケットではこの方法を使います)。capability のみの場合は、その capability を提供するプラグインが解決されます(Recipe が spec.capability でバインドする素の capability 名。例: helm)。両方を指定すると曖昧さが解消されます。複数のプラグインがその capability を提供するフェデレーションカタログにおいて、capability が解決対象を指定し、uri がそのプラグインの素の識別子によって、どのパブリッシャーのプラグインがそれを提供するかを選択します。role はここで受け付けられますが、この形状を使うどちらのリストでも読み取られません。これが指定する governance のアタッチメントロールは PluginRef を使う governance エントリで読み取られるため、これらのエントリに設定したロールは効果を持ちません。with はプラグインが読み取るアタッチ時の任意の入力を保持します。provider バインディングはレンダリング設定を代わりに Recipe から取得するため、provider バインディングに with: を指定すると読み込み時に拒否されます。
| プロパティ | 種類 | 必須 | 説明 |
|---|---|---|---|
uri | string | いいえ | プラグイン識別子: Plugin エンティティの素の識別子(<pluginType>/<name> 形式のパス。例: governance/redact や provider/helm)、ローカルファイルシステムのパス、またはレジストリのエイリアスです。任意: エントリは代わりに capability でプラグインを選択することもできます。末尾に任意で :version を付けると、他のバージョン指定と同じ 3 つの形式(指定なし、完全一致 :1.0.0、メジャー互換範囲 :^1.0.0)でバージョンを固定します。 |
role | string (enum) | いいえ | governance のアタッチメントロールです。この形状を使うどちらのリストもこれを読み取りません。ロールは governance エントリで読み取られ、それらのエントリは PluginRef を使用するため、ここに設定したロールは受け付けられますが効果を持ちません。許可される値は 4 つの governance ロールで、それぞれの意味は PluginRef で説明しています。許可される値: "annotation-transform"、"label-transform"、"ir-verdict"、"render-verdict" |
capability | string | いいえ | このエントリがプラグインを選択する対象の provider capability です。Recipe が spec.capability でバインドする素の capability 名です(例: helm、compose)。任意: エントリは代わりに uri でプラグインを直接アタッチすることもできます。provider バインディングは、フェデレーションカタログにおいてどのパブリッシャーのプラグインが capability を提供するかを選択するためにこれを使用します。横断的ソケットではこれを空のままにし、uri でアタッチします。 |
with | PluginRefWith | いいえ | プラグインが読み取るアタッチ時の任意の入力です。両メンバーとも任意でソケットに依存しないため、どのソケットでもこの仕組みを再利用できます。 |
追加のプロパティは許可されません。
CLIPluginRef
トップレベルの aggrega コマンドとしてインストールされる、ピン留めされた CLI 拡張プラグインです。コマンドが解決して実行する、解決済みでバージョンがピン留めされたアーティファクト参照と、インストール時にその参照が解決したゲストのバイト列のコンテンツダイジェストから成ります。この 2 つによって、コマンドが実行するバイト列が厳密にピン留めされます。ダイジェストは、ゲストを読み込まずにコマンドの名前とヘルプを提供する describe キャッシュのキーにもなります。
| プロパティ | 種類 | 必須 | 説明 |
|---|---|---|---|
uri | string | はい | コマンドが解決して実行する、解決済みでバージョンがピン留めされたアーティファクト参照です(例: oci://hub.aggrega.ai/plugin/cli/<name>:1.2.0)。インストール時にピン留めされます。 |
digest | string | はい | インストール時に参照が解決したゲストの .wasm バイト列のコンテンツダイジェストで、sha256: の後にバイト列の SHA-256 を表す 64 桁の小文字の 16 進数を続けて記述します。これは aggrega plugin add cli が記録する表記であり、解決されたバイト列との比較に使われる表記です。これ以外の表記のダイジェスト(sha256: 接頭辞のない 16 進数のみ、大文字、または異なる長さ)は決して一致しないため、設定ファイルの読み込み時に、ファイルとエントリを示して拒否されます。このダイジェストはコマンドが実行するバイト列を厳密にピン留めし(後の解決でバイト列のハッシュが異なればコマンドは停止します)、ゲストを読み込まずにコマンドのヘルプを表示する describe キャッシュへのキーとなります。パターン: ^sha256:[0-9a-f]{64}$。 |
追加のプロパティは許可されません。
PluginRefWith
プラグインが読み取る、アタッチ時の任意の入力です。両メンバーとも任意で、この仕組みは汎用的なため、どのソケットでも再利用できます。
| プロパティ | 種類 | 必須 | 説明 |
|---|---|---|---|
sources | string[] | いいえ | ホストがコンパイル時に読み取り、プラグインに渡す定義ファイルのパスです。各エントリは、宣言している設定ファイルのディレクトリを基準に解決されるファイルシステムパスです。 |
settings | object | いいえ | そのままプラグインに渡される自由形式の設定オブジェクトです。ホストはその形を解釈せず、読み取るキーはプラグインが定義します。 |
追加のプロパティは許可されません。