From 2b265bfa18f820295db1c61e8ba7270f3d15a8b6 Mon Sep 17 00:00:00 2001 From: Saber5656 Date: Fri, 17 Jul 2026 20:52:28 +0900 Subject: [PATCH] [issue #98] Unify Saihai naming and align setup/classify docs with implementation --- README.ja.md | 21 +++++++++++---------- README.md | 23 ++++++++++++----------- docs/configuration.md | 21 +++++++++++++++------ 3 files changed, 38 insertions(+), 27 deletions(-) diff --git a/README.ja.md b/README.ja.md index a4c4366..c1cac83 100644 --- a/README.ja.md +++ b/README.ja.md @@ -1,8 +1,8 @@ -# Sahai +# Saihai [English](README.md) | [日本語](README.ja.md) -Sahai は、プロンプトを実行権限として扱うのではなく、typed artifact、明示的な承認、durable state、監査可能な evidence を通じて AI エージェントの作業を実行するためのローカル orchestrator / organization runtime リポジトリです。 +Saihai は、プロンプトを実行権限として扱うのではなく、typed artifact、明示的な承認、durable state、監査可能な evidence を通じて AI エージェントの作業を実行するためのローカル orchestrator / organization runtime リポジトリです。 このリポジトリには Agent-Teams-Viewer（ATV）由来のローカル status viewer も残っていますが、現在の主要な product surface は deterministic frontdoor、durable workflow run、制約された main-agent bridge、typed report / evidence gate です。pre-release の記録では、historical artifact や compatibility alias を指す際に ATV の名称が残っている場合があります。 @@ -43,7 +43,8 @@ daemon scheduling、tmux worker execution、package distribution、automatic pub ```sh python3 scripts/setup_directory_paths.py --help -# Supply all nine required directory options, then validate the catalog. +# configuration guide に示す8個の directory option を指定してから catalog を +# 検証する。SAIHAI_ROOT の default は primary checkout。 python3 scripts/setup_directory_paths.py --check ``` @@ -64,7 +65,7 @@ setup command は非破壊的で、owner-only file を書き込みます。proce | 機能 | 現在の挙動 | |---|---| -| Prompt classification | `scripts/configure_organization.py classify` と `/api/decide` が作業を `fast`、`strict`、`maintenance` に分類する。どの mode でも適用される task record と Vault record が必要 | +| Prompt classification | `scripts/configure_organization.py classify` と `/api/decide` は、`fast` / `strict` の execution mode と、`enabled` / `disabled` / `maintenance` の organization state を別々に返す。どの mode / state でも適用される task record と Vault record が必要 | | Workflow selection | `workflow_selector.py` が typed classification を active workflow template へ deterministic に対応付ける。raw prompt は selection authority にならない | | Frontdoor proposal | prompt 起点の request は `proposed` または `waiting_human` まで進むか、`blocked` として fail closed する。`propose` は approved activation を生成せず、workflow run も作成しない | | Approval | `approve` は proposal digest から導出した challenge を検証する。許可される activation source は `human_ui`、`manual_cli`、`orchestrator-start`、trusted execution principal は `human_operator`、`manual_operator`、`orchestrator_start`。narrow CLI の default は `human_operator` / `human-ui` / `local_ui` | @@ -204,8 +205,8 @@ provider CLI の1回の実行は既定30分で、1秒から24時間まで設定 ```sh python3 scripts/configure_organization.py status python3 scripts/configure_organization.py runtime-paths -python3 scripts/configure_organization.py classify --prompt "Review the latest forecast" -AGENT_ORG_MAINTENANCE=1 python3 scripts/configure_organization.py classify --prompt "Repair a hook" +python3 scripts/configure_organization.py classify --prompt "Review the latest forecast" --mode strict --organization-state enabled +python3 scripts/configure_organization.py classify --prompt "Repair a hook" --organization-state maintenance python3 scripts/configure_organization.py validate-all python3 scripts/configure_organization.py workflow-selector validate-contracts python3 scripts/configure_organization.py workflow-frontdoor --help @@ -215,7 +216,7 @@ python3 scripts/configure_organization.py workflow-frontdoor --help |---|---| | `status` | organization settings、role/policy count、repository root を JSON で出力する | | `runtime-paths` | ITB runtime、workflow selector/frontdoor/server、operator CLI、registry mirror を検証する | -| `classify` | prompt を `fast`、`strict`、`maintenance` に分類する | +| `classify` | optional な `--mode {fast,strict}` と、独立した `--organization-state {enabled,disabled,maintenance}` control を使って prompt を分類する | | `validate-all` | offline suite、contract validation、Python compile check を実行する | | `workflow-selector` | workflow contract を検証し、deterministic selection と activation-envelope operation を行う | | `workflow-frontdoor` | host-owned な frontdoor / recovery surface 全体を提供する | @@ -269,7 +270,7 @@ Codex profile、必須のadministrator deployment、canary、worker policy-domai ### Scoped worker backend -live scoped-worker backend は、host operator が以下の asset を手動設定するまで fail closed します。Sahai は key や credential を生成しません。 +live scoped-worker backend は、host operator が以下の asset を手動設定するまで fail closed します。Saihai は key や credential を生成しません。 executor implementationはshippedですが、live `managed_worker` claimはsuppressされています。Codex 0.144.1ではsame-rootfsなlocal `git push`の絶対拒否を証明できません。currentなworker commissioningはevidenceを記録できても、`commission-seal`が`worker_denial_facts_not_promotable`でfail closedします。currentな`external_mutation`、`git_commit`、`git_push`、`credential_access` factは`result=fail`でhost observationもinconclusiveです。特に`workspace_profile_and_network_disabled_not_same_rootfs_isolation`と`dedicated_auth_deny_configured_not_mechanically_proven`は機械的なdeny evidenceではなく、明示的なnon-claimです。active worker claimには別のisolated policy domainで得たevidenceが必要です。shipped local action gatewayにはそのdomainへのautomatic transportがないため、current releaseは自動接続済みのend-to-end worker systemではありません。 @@ -277,7 +278,7 @@ executor implementationはshippedですが、live `managed_worker` claimはsuppr |---|---| | `SAIHAI_SCOPED_EXECUTOR_KEY_FILE` | regular、non-symlink、`0600` file に保存された32 bytes以上の capability HMAC key | | `SAIHAI_SCOPED_WORKTREE_ROOT` | host が task/run-bound worktree path を導出する canonical root | -| `SAIHAI_SCOPED_REPO_ROOT` | host-owned absolute repository path。default は Sahai repository root | +| `SAIHAI_SCOPED_REPO_ROOT` | host-owned absolute repository path。default は Saihai repository root | | `SAIHAI_SCOPED_CODEX_EXECUTABLE` | digest が work order と capability に bind される absolute pinned Codex CLI path。group/world-writable binary は拒否される | | `SAIHAI_SCOPED_CODEX_HOME` | dedicated worker runtime/auth root。main-agent profile は継承しない | | `SAIHAI_ENABLE_SCOPED_WORKER_LIVE=1` | 明示的な live-execution gate。未設定時は deterministic fake harness だけが利用可能 | @@ -369,7 +370,7 @@ ITB session discovery は `~/.claude/state/itb` と `~/.codex/state/itb` を読 | `GET /api/org?session=` | team role state、active task、busy count | | `GET /api/role?session=&role=` | role metadata、inbox、latest report、provider evidence | | `GET /api/config` | organization settings と role/policy index | -| `GET /api/decide?prompt=` | `fast`、`strict`、`maintenance` classification | +| `GET /api/decide?prompt=` | `fast` / `strict` mode と、独立した `enabled` / `disabled` / `maintenance` organization state を返す decision | | `GET /api/workflow-runs?session=&task=&state=` | thin read-only workflow-run summary | | `GET /api/workflow-run?session=&run=` | work order、report、provider evidence、transition metadata | | `GET /api/workflow-lock` | 設定済み orchestrator root ごとの global workflow-lock status | diff --git a/README.md b/README.md index 11c50e2..a2e7a6c 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ -# Sahai +# Saihai [English](README.md) | [Japanese](README.ja.md) -Sahai is a local orchestrator and organization-runtime repository for running +Saihai is a local orchestrator and organization-runtime repository for running AI-agent work through typed artifacts, explicit approval, durable state, and auditable evidence instead of treating a prompt as execution authority. @@ -12,7 +12,7 @@ deterministic frontdoor, durable workflow runs, the constrained main-agent bridge, and typed report and evidence gates. Pre-release records may still use the ATV name for historical artifacts and compatibility aliases. -Sahai uses only the Python 3.10+ standard library for normal operation. No +Saihai uses only the Python 3.10+ standard library for normal operation. No `pip install` step is required. ## Release @@ -85,7 +85,8 @@ Linked worktrees reuse the primary checkout's catalog. ```sh python3 scripts/setup_directory_paths.py --help -# Supply all nine required directory options, then validate the catalog. +# Supply the eight directory options shown in the configuration guide, then +# validate the catalog. SAIHAI_ROOT defaults to the primary checkout. python3 scripts/setup_directory_paths.py --check ``` @@ -115,7 +116,7 @@ for the complete path audit. | Capability | Current behavior | |---|---| -| Prompt classification | `scripts/configure_organization.py classify` and `/api/decide` classify work as `fast`, `strict`, or `maintenance`. Every mode still requires the applicable task and Vault records. | +| Prompt classification | `scripts/configure_organization.py classify` and `/api/decide` report a `fast` or `strict` execution mode separately from the `enabled`, `disabled`, or `maintenance` organization state. Every mode and state still requires the applicable task and Vault records. | | Workflow selection | `workflow_selector.py` deterministically maps a typed classification to an active workflow template. A raw prompt is never selection authority. | | Frontdoor proposal | Prompt-originated requests stop at `proposed` or `waiting_human`, or fail closed as `blocked`. `propose` cannot produce an approved activation or create a workflow run. | | Approval | `approve` verifies a challenge derived from the proposal digest. Accepted activation sources are `human_ui`, `manual_cli`, and `orchestrator-start`, with trusted execution principals `human_operator`, `manual_operator`, and `orchestrator_start`. The narrow CLI defaults to `human_operator` / `human-ui` / `local_ui`. | @@ -284,8 +285,8 @@ skills, automation, and the existing runtime. ```sh python3 scripts/configure_organization.py status python3 scripts/configure_organization.py runtime-paths -python3 scripts/configure_organization.py classify --prompt "Review the latest forecast" -AGENT_ORG_MAINTENANCE=1 python3 scripts/configure_organization.py classify --prompt "Repair a hook" +python3 scripts/configure_organization.py classify --prompt "Review the latest forecast" --mode strict --organization-state enabled +python3 scripts/configure_organization.py classify --prompt "Repair a hook" --organization-state maintenance python3 scripts/configure_organization.py validate-all python3 scripts/configure_organization.py workflow-selector validate-contracts python3 scripts/configure_organization.py workflow-frontdoor --help @@ -295,7 +296,7 @@ python3 scripts/configure_organization.py workflow-frontdoor --help |---|---| | `status` | Print organization settings, role and policy counts, and repository root as JSON. | | `runtime-paths` | Verify the ITB runtime, workflow selector/frontdoor/server, operator CLI, and registry mirrors. | -| `classify` | Classify a prompt as `fast`, `strict`, or `maintenance`. | +| `classify` | Classify a prompt with optional `--mode {fast,strict}` and the separate `--organization-state {enabled,disabled,maintenance}` control. | | `validate-all` | Run the offline suites, contract validation, and Python compile check. | | `workflow-selector` | Validate workflow contracts and perform deterministic selection and activation-envelope operations. | | `workflow-frontdoor` | Provide the complete host-owned frontdoor and recovery surface. | @@ -386,7 +387,7 @@ is added and attested. ### Scoped worker backend The live scoped-worker backend fails closed until a host operator manually -configures the following assets. Sahai never generates keys or credentials. +configures the following assets. Saihai never generates keys or credentials. The executor implementation is shipped, but the live `managed_worker` claim is suppressed. Codex 0.144.1 cannot prove absolute denial of a same-rootfs local @@ -407,7 +408,7 @@ worker system. |---|---| | `SAIHAI_SCOPED_EXECUTOR_KEY_FILE` | Capability HMAC key in a regular, non-symlink, `0600` file containing at least 32 bytes. | | `SAIHAI_SCOPED_WORKTREE_ROOT` | Canonical root from which the host derives the task/run-bound worktree path. | -| `SAIHAI_SCOPED_REPO_ROOT` | Host-owned absolute repository path. Defaults to the Sahai repository root. | +| `SAIHAI_SCOPED_REPO_ROOT` | Host-owned absolute repository path. Defaults to the Saihai repository root. | | `SAIHAI_SCOPED_CODEX_EXECUTABLE` | Absolute pinned Codex CLI path whose digest is bound into the work order and capability. Group/world-writable binaries are rejected. | | `SAIHAI_SCOPED_CODEX_HOME` | Dedicated worker runtime/auth root; the main-agent profile is not inherited. | | `SAIHAI_ENABLE_SCOPED_WORKER_LIVE=1` | Explicit live-execution gate. Without it, only the deterministic fake harness is available. | @@ -524,7 +525,7 @@ canonical root loaded from the primary checkout catalog. | `GET /api/org?session=` | Team role state, active task, and busy count. | | `GET /api/role?session=&role=` | Role metadata, inbox, latest report, and provider evidence. | | `GET /api/config` | Organization settings and role/policy indexes. | -| `GET /api/decide?prompt=` | `fast`, `strict`, or `maintenance` classification. | +| `GET /api/decide?prompt=` | Decision with a `fast` or `strict` mode and a separate `enabled`, `disabled`, or `maintenance` organization state. | | `GET /api/workflow-runs?session=&task=&state=` | Thin read-only workflow-run summaries. | | `GET /api/workflow-run?session=&run=` | Work order, report, provider evidence, and transition metadata. | | `GET /api/workflow-lock` | Global workflow-lock status for each configured orchestrator root. | diff --git a/docs/configuration.md b/docs/configuration.md index 7d52aa0..6a080e9 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -28,6 +28,12 @@ audit is in Create the file in the primary checkout, or validate an existing file: +The setup command requires the eight directory options shown below. +`SAIHAI_ROOT`, the ninth required canonical path, defaults to the primary +checkout that contains the catalog; pass `--saihai-root` only to override that +default. Every supplied path must already exist as a readable directory, and +the Agents Vault must also be writable. + ```sh python3 scripts/setup_directory_paths.py \ --agents-vault /absolute/path/to/Agents-Vault \ @@ -48,8 +54,8 @@ The setup command refuses to overwrite an existing file. The loader locates the catalog in this order: -1. path supplied by process variable `SAIHAI_DIRECTORY_PATH_ENV` (or legacy `SAHAI_DIRECTORY_PATH_ENV`); -2. `directory-path.env` below process `SAIHAI_ROOT` or legacy `SAHAI_ROOT`; +1. path supplied by process variable `SAIHAI_DIRECTORY_PATH_ENV`; +2. `directory-path.env` below process `SAIHAI_ROOT`; 3. `directory-path.env` in the current Saihai checkout; 4. `directory-path.env` in the primary checkout of a linked Git worktree; 5. no file. @@ -79,8 +85,10 @@ values. Normal Saihai entrypoints fail closed unless all nine canonical directory paths listed as required below exist and are readable. `AGENTS_VAULT_ROOT` must also -be writable. Bootstrap-only consumers may load the catalog without enforcing -the complete contract so that recovery remains possible. +be writable. The setup command applies the same checks before creating the +catalog and refuses to overwrite an existing file. Bootstrap-only consumers +may load the catalog without enforcing the complete contract so that recovery +remains possible. ## Canonical variables @@ -111,6 +119,7 @@ emits value-free deprecation diagnostics. | `YASU_VAULT_ROOT` | `USER_VAULT_ROOT` | | `SKILLS_REPO_SKILLS_ROOT` | `SKILLS_ROOT` | | `DEV_REPO_ROOT` | `DEV_ROOT` | +| `SAHAI_DIRECTORY_PATH_ENV` | `SAIHAI_DIRECTORY_PATH_ENV` | | `SAHAI_ORCH_STATE_ROOT` | `SAIHAI_ORCH_STATE_ROOT` | | `SAHAI_ITB_STATE_ROOTS` | `SAIHAI_ITB_STATE_ROOTS` | @@ -132,5 +141,5 @@ python3 scripts/setup_directory_paths.py --check ``` To recover from an invalid explicit selector, unset -`SAIHAI_DIRECTORY_PATH_ENV` (and legacy `SAHAI_DIRECTORY_PATH_ENV`) so normal -primary-checkout discovery can resume. +`SAIHAI_DIRECTORY_PATH_ENV` so normal primary-checkout discovery can resume. +Compatibility selector names are listed only in the table above.