AI サブシステム
Astar の AI は単発の補完機能ではなく、エージェント基盤として実装されています。設計原則は一貫していて、Anthropic 公式や Claude Code と機能で競合しないことです。差別化軸は組織レイヤー（RLS・権限・MCP・コンテキスト保持）だけに絞っています。
マルチプロバイダー
AIProviderType は1つの enum に統一されていて、実運用で使うのは主に次の4系統です。
| プロバイダ | 認証 | 特徴 |
|---|---|---|
| Google Vertex AI / Azure OpenAI / AWS Bedrock / Anthropic Direct / OpenAI Direct | プラットフォーム側の資格情報 | 本番の主経路 |
| OpenRouter | Astar 自身のキー（BYOK ではない） | GLM/Kimi 等の厳選された open-weight モデルへのゲートウェイ。ZDR（データ保持なし）を組織設定 + リクエストごとの zdr フラグの二重で強制 |
| Claude Code local / Codex local | ユーザー自身のサブスクリプション | Go Agent 経由でユーザーの端末上の CLI を直接動かす。バックエンドから API キーは送らない |
| STT (Gemini / Azure Whisper / ElevenLabs Scribe) | プラットフォーム側 | 音声・通話の文字起こし。ElevenLabs は話者分離 (diarization) 用 |
ローカル CLI プロバイダ（Claude Code / Codex）は LocalCliOrchestrator がイベントを 1:1 で SSE ストリームに転送する形で、通常のプラットフォームプロバイダとは別の実行経路を持ちます。ツール実行は CLI サブプロセス側で完結します。
dev/local 環境では実プロバイダへの課金呼び出しは既定でブロックされています（DevExternalLlmGuard）。検証は scripted LLM や seed データが基本です。
エージェントループとオーケストレーション
| 構成要素 | 役割 |
|---|---|
エージェントループ (AgentLoopRunner) | マルチターンのツール実行・結果解釈を反復する中核 |
Plan Mode (PlanModeOrchestrator) | 計画生成 → 人の承認 → 実行 |
サブエージェント (SubAgentExecutionService / AgentOrchestrator) | 並列 AI ワーカーへのタスク委譲。ツールループを回す唯一の choke point で、単発 LLM 呼び出し（ツールを回さない）は代わりに AiSkillExecutor が担う |
メモリ (AiMemoryService / MemoryFlushService / MemoryConsolidationService) | 個人/組織 2層の永続記憶。夜間統合が既定 ON |
スキル (SkillRegistry + .astar/skills) | 単発 LLM 作業の統一実行系。テナントごとに上書き可能 |
自動化 (core/automation/) | イベント/スケジュール駆動ルール。ルール単位で AI メンバーを割り当てられる |
AI ディスパッチは常にスキル/サブエージェント経由で、ツールやサービスに埋め込まれたその場限りの LLM 呼び出しは規約違反です。モデルを呼び出す側は「ツールを呼ばない1回きりの呼び出しか」「モデル自身がツールを呼んで反復するか」で AiSkillExecutor と SubAgentExecutionService のどちらを使うかを選びます。
.astar ワークスペース — Claude Code の .claude/ に相当
各テナントは非表示のワークスペース .astar を自動で持ちます。AI ハーネス資産（スキル・サブエージェント・自動化・AI 自身のメモリ）を置く場所で、コード内のコメントがその意図をそのまま言い表しています。
"This workspace is the destination for AI harness assets ... it is Astar's analogue of Claude Code's
.claude/directory."
| パス | 内容 |
|---|---|
.astar/skills/{slug} | INLINE スキル定義（呼び出し元エージェントがその場で指示として実行） |
.astar/agents/{slug} | DELEGATED サブエージェント定義（新しい実行コンテキストを生成し、allowedTools/maxToolCalls/timeoutSeconds をサーバー側で強制） |
.astar/automations/* | JS/TS スクリプト本体 |
.astar/automation-rules/{slug}.json | 自動化ルール設定（トリガー + 呼び出し先） |
.astar/ai/memory/, .astar/ai/wiki/ | AI 自身が学習・記録した内容。専用ツール経由でのみアクセス |
スキルとサブエージェントは同じデータ構造（SkillDefinition）で、フォルダ配置（skills/ か agents/ か）だけが実行モードを決めます。並行するフラグは存在しません。カスタマーの端末で実際の Claude Code CLI にエクスポートするときは、INLINE → .claude/skills/{slug}/SKILL.md、DELEGATED → .claude/agents/{slug}.md と、Claude Code 自身のオンディスク規約にマッピングされます。
MCP ツール群
core/mcp/ に 250+ ツール（37 グループ）が定義されています。この MCP ツール定義が AI（内製・BYO 問わず）と astar CLI の両方が乗る、唯一の統一 API 面です。ツール名は {group}_{resource}_{action}（snake_case）で、astar CLI からは astar group resource action としてそのまま叩けます。
新しいツールを追加するときは @Tool + @McpTool（capability: READ_ONLY / SIDE_EFFECTING の宣言）+ McpToolsConfig への登録の3点セットが必要です。ノード型の作成ツールは個別に増やさず、node_create --type X に一元化されています。詳しい規約は backend/CLAUDE.md の MCP Tool Convention 節を参照してください。
tool 承認ゲート
副作用のあるツール呼び出しは、既定では 人間の確認を経由します。
- ツールは
confirm: Boolean?パラメータとchangePreview: ChangePreview?を持ち、プレビューはツール自身が組み立てます - astar CLI からの直接呼び出し（
POST /api/v1/cli）は Unix のrmと同じ発想でautoConfirm=trueを自動注入します。AI agent 経路は手動確認のままです - DELEGATED スキル（
sideEffectsAllowed=true）や Code Mode スクリプト（autoCommitMutations=true）から呼ばれた確認必須ツールはconfirmが自動注入されますが、alwaysConfirmTools（bot_message_sendなどの外部プラットフォームへの送信、skill_create/automation_create/automation_bundle_import_applyのようなスキル/自動化自体を無人で自己増殖させ得るツール）だけは例外で、必ずプレビューのみの応答に落ちます
AI コード実行サンドボックス
.astar/automations/ のスクリプトや対話的な code-exec は、ロックダウンされた GraalVM JS Context 上で in-process 実行されます（allowHostAccess(EXPLICIT)、allowIO(NONE)、スレッド/プロセス生成不可、環境変数アクセス不可）。実システムへの唯一の出口は astar.* ブリッジ（SandboxToolCallBridge）で、すべての呼び出しは通常のエージェントツール呼び出しと同じ ToolExecutionService を経由します——@PreAuthorize・RLS・監査/クレジットフックがすべて同じように効きます。
この JS サンドボックスの脅威モデルは明示的に定義されています。
"Trust model: this is a SOFT boundary (same JVM/heap), suitable for TRUSTED code — i.e. the AI member running under its own identity. Untrusted/customer code needs a hard boundary (separate process / Cloudflare Dynamic Workers) behind this same port."
つまり、このサンドボックスは「テナント自身の AI がテナント自身の権限を誤用する」というバグに対する防御であり、赤の他人が任意コードを実行する敵対的シナリオ向けのハードバウンダリではありません。より隔離度の高い実行が必要な場面（顧客提供コードの実行など）向けには、別途コンテナベースの AI ランタイム（docker/ai-runtime/）があり、こちらは独立プロセス + seccomp プロファイルでより強い分離を持ちます。
レイテンシ予算
AI チャットは first_event（ユーザー入力 → 最初の SSE イベント）を p95 15秒未満に抑える設計目標を持ち、読み取り専用ツールのファンアウトは並列実行が必須です（coroutineScope { ... }.awaitAll()、逐次 forEach は禁止）。詳細な設計ルールとインシデント経緯は docs/ai/latency-budget.md を参照してください。