diff --git a/MEMORY.md b/MEMORY.md index 4966414..a7e7b74 100644 --- a/MEMORY.md +++ b/MEMORY.md @@ -14,6 +14,12 @@ ## 책임과 개발 범위 +2026-11-19 구현·로컬 검증 완료: [Run별 capability 범위](docs/development/capability-scope.md), [PR #144](https://github.com/PlateerLab/xgen-cli/pull/144). +`run --capability ID`는 선택한 정의와 instance만 planner/admission에 등록하고 manifest와 +실행 profile에 결속한다. 기본 전체 catalog·기존 승인·Receipt를 유지하며 resume은 저장한 범위를 +복원한다. 이번 검증 결과·한계는 [ADR-0087](docs/adr/0087-run-capability-scope.md)을 따른다. +초기 별도 호스트의 요청 크기 수치는 PR의 선행 기록이며 실제 모델 품질·운영 채택은 미검증이다. + | 구성 요소 | 책임 | 별도로 추적할 개선 | | --- | --- | --- | | xgen CLI | 연결·인증 관리, 도구 호출 계약, 권한·승인, 실행, Receipt, 최종 응답, 사용자 경험 | 연결 흐름, 어댑터, 결과 검증, 배포·자동 실행 | @@ -186,3 +192,7 @@ - 알려진 흔들림(기존 main에도 있음): `smoke-inline-tui.py --rapid-resize`의 `heldout-burst-restored`가 burst 중간 크기의 입력창 조각이 화면에 남아 가끔 시간 초과한다. 맥 로컬 main 8회 중 1회, 수정본 14회 중 1회. 원인은 연속 reflow를 프런트엔드가 다 따라가지 못해 지울 위치를 잘못 잡는 것(미해결). 같은 스크립트의 `stty.txt` 읽기 경합(파일 생성 직후 빈 내용 읽음)은 고쳤다. - TUI 사용성(사용자 요청, 2026-11-03, 미구현): Claude Code `/model`처럼 화살표로 고르는 model 선택기. opencode는 TypeScript/Go라 그대로 못 가져온다. 같은 Rust인 OpenAI Codex CLI TUI(ratatui, Apache-2.0)가 참고·이식 후보 — 셀 단위 diff 렌더링이라 지우고 다시 그리는 깜빡임 구조 자체가 없다. 한 단계씩: 깜빡임 수정 → `/model` 선택기 → 렌더러 교체 여부는 ADR로 따로 판단. - 18초 응답(사용자 보고, 2026-11-03): 시간 전부가 한 번의 HTTP 호출 안이었다(usage elapsedMillis 18324, 출력 52 token). 같은 경로를 tmux TUI·`xgen run`으로 다시 재면 2~5초, 직접 호출 1.5~2초라 일회성 provider 지연으로 본다(원인 확정 아님). + +- xgen-cli 자체 개발 순서(2026-11-19, 사용자 승인): 미완료 #144 검증·정리 후 실행 중 후속 지시 반영을 다음 큰 작업으로 둔다. 독립 Run 병렬 실행·상위 Router는 이후 후보이며 아직 구현하지 않았다. +- #144 정리(구현·로컬 검증 완료): 최초 CI는 test의 빈 String 생성에 대한 Clippy1건에서 중단됐다. 최신 main을 병합해 수정했으며, 범위 밖 도구를 지시하는 안내와 필수 completion 검사 모순도 실제 실행에서 재현해 고쳤다. read/stat 승인·resume, 선택 write의 별도 승인, 숨긴 write 차단, HTTP 원문·요청 크기 검증을 진행한다. 독립 diff 검토 도구는 인증 오류로 이용하지 못했으며 직접 코드 검토와 회귀 검사를 수행한다. +- #144 최종 로컬 검증: Rust798개(4 ignored), Python162개(9 skipped), Clippy·fmt·protocol·문서·workflow 검사 통과. 이전 rc.6의 미완료 HTTP Run을 새 바이너리로 재개해 catalog digest와 API 본문이 유지됨을 두 fixture에서 확인했다. 실제 모델 판단 품질·토큰 금액 절감은 미측정이다. 작업은 기존 `/home/son/projects/xgen-cli-wt/capability-scope`의 `codex/capability-scope`에서 진행했다. diff --git a/README.md b/README.md index cbbbf67..28f4a48 100644 --- a/README.md +++ b/README.md @@ -150,6 +150,10 @@ durable completion에 저장해. 기존 기본 출력은 유지해. 검증이 누락·실패했거나 이후 변경으로 낡았으면 완료를 거절해. [완료 검증 조건](docs/development/receipt-completion-checks.md)을 확인해. +필요한 도구가 정해진 headless 실행은 `run --capability ID`를 반복해 도구 범위를 제한할 수 있다. +모델에 제공하는 목록과 실제 실행 가능한 목록이 함께 제한되며, 재개할 때도 저장된 범위를 사용한다. +각 도구의 승인은 별도로 필요하다. [Run별 capability 범위](docs/development/capability-scope.md). + ## 제품 원칙 - 사용자는 `xgen` 하나만 설치합니다. diff --git a/crates/xgen-cli/src/allow_path.rs b/crates/xgen-cli/src/allow_path.rs index 7a37c54..8f14cfc 100644 --- a/crates/xgen-cli/src/allow_path.rs +++ b/crates/xgen-cli/src/allow_path.rs @@ -53,7 +53,7 @@ impl WorkspaceReadAuthorization { if files.iter().any(|path| directories.contains(path)) { return Err(WorkspaceReadAuthorizationError::DuplicateEntry); } - let planner_scope_hint = planner_scope_hint(&files, &directories)?; + let planner_scope_hint = planner_scope_hint(&files, &directories, true)?; let entries = files .iter() .map(|path| CatalogEntry { kind: "file", path }) @@ -84,6 +84,11 @@ impl WorkspaceReadAuthorization { &self.planner_scope_hint } + pub(crate) fn scoped_planner_scope_hint(&self) -> String { + planner_scope_hint(&self.files, &self.directories, false) + .expect("validated path catalog has a bounded serializable hint") + } + pub(crate) fn authorizes_material( &self, capability: &CapabilityRef, @@ -205,6 +210,7 @@ pub(crate) enum WorkspaceReadAuthorizationError { fn planner_scope_hint( files: &BTreeSet, directories: &BTreeSet, + include_tool_guidance: bool, ) -> Result { let directories = directories .iter() @@ -218,9 +224,15 @@ fn planner_scope_hint( .map_err(|_| WorkspaceReadAuthorizationError::Canonicalization)?; let files = serde_json::to_string(&files) .map_err(|_| WorkspaceReadAuthorizationError::Canonicalization)?; - let hint = format!( - "Caller-authorized directory roots (list/search targets and descendant stat/read/write-atomic/apply-patch targets): {directories}. Additional exact files (stat/read only): {files}. write-atomic requires expectedDigest=null for creation or the exact digest previously read for replacement. apply-patch requires the exact whole-file digest previously read (read-text digest or read-text-lines fileDigest) and 1..={MAX_APPLY_PATCH_EDITS} non-overlapping edits; every oldText must occur exactly once." - ); + let hint = if include_tool_guidance { + format!( + "Caller-authorized directory roots (list/search targets and descendant stat/read/write-atomic/apply-patch targets): {directories}. Additional exact files (stat/read only): {files}. write-atomic requires expectedDigest=null for creation or the exact digest previously read for replacement. apply-patch requires the exact whole-file digest previously read (read-text digest or read-text-lines fileDigest) and 1..={MAX_APPLY_PATCH_EDITS} non-overlapping edits; every oldText must occur exactly once." + ) + } else { + format!( + "Caller-authorized directory roots and descendants: {directories}. Additional exact files (read only): {files}. Use these paths only with the capabilities offered in this Run." + ) + }; if hint.len() > MAX_PLANNER_SCOPE_HINT_BYTES { return Err(WorkspaceReadAuthorizationError::PlannerHintTooLarge); } diff --git a/crates/xgen-cli/src/allow_process.rs b/crates/xgen-cli/src/allow_process.rs index ad39cc4..e762fd5 100644 --- a/crates/xgen-cli/src/allow_process.rs +++ b/crates/xgen-cli/src/allow_process.rs @@ -146,6 +146,7 @@ impl fmt::Debug for ProcessTooling { pub(crate) struct ProcessExecutionAuthorization { canonical_resources: BTreeSet, planner_scope_hint: String, + logical_ids_json: String, catalog_digest: String, web_search_enabled: bool, } @@ -191,6 +192,7 @@ impl ProcessExecutionAuthorization { Ok(Self { canonical_resources, planner_scope_hint, + logical_ids_json: encoded_ids, catalog_digest: sha256_digest(&canonical), web_search_enabled: ids.contains(WEB_SEARCH_EXECUTABLE_ID), }) @@ -208,6 +210,17 @@ impl ProcessExecutionAuthorization { &self.planner_scope_hint } + pub(crate) fn scoped_planner_scope_hint(&self, execute_offered: bool) -> String { + if execute_offered { + self.planner_scope_hint().to_owned() + } else { + format!( + "Caller-catalogued process executable logical IDs: {}. Use executable IDs only with the capabilities offered in this Run.", + self.logical_ids_json + ) + } + } + pub(crate) fn catalog_digest(&self) -> &str { &self.catalog_digest } @@ -221,6 +234,7 @@ impl fmt::Debug for ProcessExecutionAuthorization { .field("web_search_enabled", &self.web_search_enabled) .field("resources", &"") .field("planner_scope_hint", &"") + .field("logical_ids_json", &"") .field("catalog_digest", &self.catalog_digest) .finish() } @@ -285,6 +299,9 @@ mod tests { ); assert!(!debug.contains(&executable.to_string_lossy().into_owned())); assert!(!debug.contains("test-helper")); + let scoped = tooling.authorization().scoped_planner_scope_hint(false); + assert!(scoped.contains("test-helper")); + assert!(!scoped.contains("process.execute")); assert!(ProcessTooling::build(directory.path(), "primary", ["test=relative"]).is_err()); assert!( ProcessTooling::build( diff --git a/crates/xgen-cli/src/capability_scope.rs b/crates/xgen-cli/src/capability_scope.rs new file mode 100644 index 0000000..3a70ac7 --- /dev/null +++ b/crates/xgen-cli/src/capability_scope.rs @@ -0,0 +1,100 @@ +//! Optional host-selected capability subset, committed before planning and admission. +use std::collections::BTreeSet; + +use xgen_runtime::CapabilityRegistry; + +pub(crate) fn normalize(ids: Vec) -> Result>, ()> { + if ids.is_empty() { + return Ok(None); + } + let mut sorted = ids; + sorted.sort(); + if !valid(&sorted) { + return Err(()); + } + Ok(Some(sorted)) +} + +pub(crate) fn valid(ids: &[String]) -> bool { + !ids.is_empty() + && ids.len() <= 128 + && ids.windows(2).all(|p| p[0] < p[1]) + && ids.iter().all(|id| { + !id.is_empty() + && id.len() <= 256 + && id + .bytes() + .all(|c| c.is_ascii_alphanumeric() || b"._/-:".contains(&c)) + }) +} + +pub(crate) fn validate_available<'a>( + ids: Option<&[String]>, + available: impl Iterator, +) -> Result<(), ()> { + if let Some(ids) = ids { + let available = available.collect::>(); + if !valid(ids) || ids.iter().any(|id| !available.contains(id.as_str())) { + return Err(()); + } + } + Ok(()) +} + +pub(crate) fn apply( + registry: CapabilityRegistry, + ids: Option<&[String]>, +) -> Result { + let Some(ids) = ids else { return Ok(registry) }; + validate_available( + Some(ids), + registry.definitions().map(|d| d.metadata.id.as_str()), + )?; + let mut scoped = CapabilityRegistry::new(); + for definition in registry + .definitions() + .filter(|d| ids.contains(&d.metadata.id)) + { + scoped + .register_schema_validated_definition(definition.clone()) + .map_err(|_| ())?; + } + for instance in registry + .instances() + .filter(|i| ids.contains(&i.definition.capability_id)) + { + scoped + .register_schema_validated_instance(instance.clone()) + .map_err(|_| ())?; + } + Ok(scoped) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn default_and_canonical_scope() { + assert_eq!(normalize(vec![]), Ok(None)); + assert_eq!( + normalize(vec!["b/read".into(), "a/read".into()]), + Ok(Some(vec!["a/read".into(), "b/read".into()])) + ); + for ids in [ + vec!["a/read".into(), "a/read".into()], + vec![String::new()], + vec!["a read".into()], + ] { + assert!(normalize(ids).is_err()); + } + } + + #[test] + fn unknown_scope_never_falls_back_to_full_catalog() { + for id in ["missing/read", "missing/write"] { + assert!(validate_available(Some(&[id.into()]), ["a/read"].into_iter()).is_err()); + assert!(apply(CapabilityRegistry::new(), Some(&[id.into()])).is_err()); + } + } +} diff --git a/crates/xgen-cli/src/composition.rs b/crates/xgen-cli/src/composition.rs index 7ad794e..eeafae6 100644 --- a/crates/xgen-cli/src/composition.rs +++ b/crates/xgen-cli/src/composition.rs @@ -154,6 +154,8 @@ pub struct LocalRunRequest { /// one. The REPL has always turned this on; `run` could not, so the same /// question answered interactively failed as a single invocation. pub conversation_responses: bool, + /// Optional capability IDs; empty retains the full catalog. Saved for resume. + pub capabilities: Vec, } impl LocalRunRequest { @@ -189,6 +191,7 @@ impl LocalRunRequest { final_response_schema: None, completion_checks: None, conversation_responses: false, + capabilities: Vec::new(), } } } @@ -1062,6 +1065,8 @@ where }); } validate_goal(&request.goal)?; + let capability_scope = crate::capability_scope::normalize(request.capabilities.clone()) + .map_err(|()| PublicRunError::Configuration)?; let workspace_id = WorkspaceId::new(WORKSPACE_ID).map_err(|_| PublicRunError::Internal)?; let workspace = WorkspaceRoot::open_ambient(&request.workspace, workspace_id.clone()) @@ -1104,7 +1109,11 @@ where } else { config }; - validate_completion_catalog(request.completion_checks.as_deref(), process.as_ref())?; + validate_completion_catalog( + request.completion_checks.as_deref(), + process.as_ref(), + capability_scope.as_deref(), + )?; let config = final_response_contract( config, request.final_response_schema.as_ref(), @@ -1119,6 +1128,7 @@ where &discovery_snapshots, &http_connections, &request.bearer_env_for, + capability_scope.as_deref(), )?; let run_id = generate_run_id().map_err(|_| PublicRunError::Internal)?; let manifest = RunManifest::new( @@ -1136,6 +1146,8 @@ where ) .map_err(|_| PublicRunError::Configuration)?; let manifest = manifest + .with_capability_scope(capability_scope) + .map_err(|_| PublicRunError::Configuration)? .with_tool_discovery_snapshots(discovery_snapshots) .map_err(|_| PublicRunError::Configuration)? .with_http_read_connections(http_connections) @@ -1382,6 +1394,7 @@ where manifest.tool_discovery_snapshots(), manifest.http_read_connections(), manifest.http_bearer_overrides(), + manifest.capability_scope(), )? { let current = process @@ -1441,7 +1454,11 @@ where catalog.workspace_discovery() || process.is_some(), )?; let config = response_contract(config, manifest.conversation_responses())?; - validate_completion_catalog(manifest.completion_checks(), process.as_ref())?; + validate_completion_catalog( + manifest.completion_checks(), + process.as_ref(), + manifest.capability_scope(), + )?; let config = final_response_contract( config, manifest.final_response_schema(), @@ -1667,7 +1684,10 @@ fn continue_incomplete( .and_then(|catalog| catalog.with_connections(manifest.http_read_connections().clone())) .and_then(|catalog| catalog.with_bearer_overrides(manifest.http_bearer_overrides().clone())) .map_err(|()| PublicRunError::Integrity)?; - let discovery = if discovery.is_empty() { + let search_offered = manifest + .capability_scope() + .is_none_or(|ids| ids.iter().any(|id| id == graph_discovery::SEARCH)); + let discovery = if discovery.is_empty() || !search_offered { discovery } else { let goal = store @@ -1684,33 +1704,81 @@ fn continue_incomplete( &mut verifiers, &mut route, )?; + capabilities = crate::capability_scope::apply(capabilities, manifest.capability_scope()) + .map_err(|()| PublicRunError::Configuration)?; + let offered = |id: &str| { + capabilities + .definitions() + .any(|definition| definition.metadata.id == id) + }; + let offered_scope = |scopes: &[&str]| { + capabilities.definitions().any(|definition| { + definition + .spec + .effect + .resource_selectors + .iter() + .any(|selector| scopes.contains(&selector.scope.as_str())) + }) + }; + let filesystem_offered = offered_scope(&[FILESYSTEM_READ_SCOPE, FILESYSTEM_WRITE_SCOPE]); let mut planning_constraints = catalog .workspace_authorization() + .filter(|_| filesystem_offered) .map(|authorization| { - PlanningConstraint::new("workspace.fs-scope", authorization.planner_scope_hint()) + let hint = if manifest.capability_scope().is_some() { + authorization.scoped_planner_scope_hint() + } else { + authorization.planner_scope_hint().to_owned() + }; + PlanningConstraint::new("workspace.fs-scope", hint) }) .transpose() .map_err(|_| PublicRunError::Internal)? .into_iter() .collect::>(); - if !discovery.is_empty() { + if !discovery.is_empty() + && let Some(hint) = discovery.hint_for_capabilities( + offered(graph_discovery::SEARCH), + offered(graph_discovery::DESCRIBE), + ) + { planning_constraints.push( - PlanningConstraint::new("tools.discovery-snapshots", discovery.hint()) + PlanningConstraint::new("tools.discovery-snapshots", hint) .map_err(|_| PublicRunError::Internal)?, ); } - if discovery.has_connections() { - planning_constraints.push(PlanningConstraint::new("http.read-connections", "Host-approved read connections are available through xgen.http/read. First describe the tool, check http_read.supported, use its exact contract_digest as contractDigest, and pass parameters.path and parameters.query. For explicitly host-approved POST reads, also pass body according to http_read.request_body. A successful HTTP Receipt and schema-valid body are required before claiming API results. Credentials are resolved only by the host.").map_err(|_| PublicRunError::Internal)?); + if discovery.has_connections() && offered(crate::http_read::READ) { + let hint = if offered(graph_discovery::DESCRIBE) { + "Host-approved read connections are available through xgen.http/read. First describe the tool, check http_read.supported, use its exact contract_digest as contractDigest, and pass parameters.path and parameters.query. For explicitly host-approved POST reads, also pass body according to http_read.request_body. A successful HTTP Receipt and schema-valid body are required before claiming API results. Credentials are resolved only by the host." + } else { + "Host-approved read connections are available through xgen.http/read. This Run does not offer describe: use an exact host-supplied tool contract and contractDigest, or report the missing prerequisite; never guess. Pass parameters.path and parameters.query and, for host-approved POST reads, the specified body. A successful HTTP Receipt and schema-valid body are required before claiming API results. Credentials are resolved only by the host." + }; + planning_constraints.push( + PlanningConstraint::new("http.read-connections", hint) + .map_err(|_| PublicRunError::Internal)?, + ); } - if let Some(process) = process { + if let Some(process) = process + && offered_scope(&[PROCESS_EXECUTE_SCOPE, WEB_SEARCH_SCOPE, TERMINAL_SCOPE]) + { planning_constraints.push( PlanningConstraint::new( "process.executable-catalog", - process.authorization().planner_scope_hint(), + process + .authorization() + .scoped_planner_scope_hint(offered(PROCESS_EXECUTE_CAPABILITY_ID)), ) .map_err(|_| PublicRunError::Internal)?, ); } + if manifest.capability_scope().is_some() && (catalog.workspace_discovery() || process.is_some()) + { + planning_constraints.push( + PlanningConstraint::new("run.capability-scope", "Use only the capabilities offered in this Run's catalog. Report missing prerequisites; capability selection does not grant permission.") + .map_err(|_| PublicRunError::Internal)?, + ); + } let resolver = LocalResourceResolver { discovery: discovery.clone(), filesystem: workspace.resolver(), @@ -2202,8 +2270,12 @@ fn final_response_contract( fn validate_completion_catalog( checks: Option<&[xgen_provider_openai::CompletionCheck]>, process: Option<&ProcessTooling>, + scope: Option<&[String]>, ) -> Result<(), PublicRunError> { if let Some(checks) = checks { + if scope.is_some_and(|ids| !ids.iter().any(|id| id == PROCESS_EXECUTE_CAPABILITY_ID)) { + return Err(PublicRunError::Configuration); + } let process = process.ok_or(PublicRunError::Configuration)?; for check in checks { let executable = check.argv.first().ok_or(PublicRunError::Configuration)?; @@ -3154,15 +3226,30 @@ fn execution_profile_with_discovery( snapshots: &graph_discovery::Snapshots, connections: &crate::http_read::Connections, overrides: &crate::http_read::BearerOverrides, + scope: Option<&[String]>, ) -> Result { let local_digest = local_execution_profile_digest(workspace, catalog, process)?; - if snapshots.is_empty() { - return Ok(local_digest); - } + let discovery = DiscoveryCatalog::saved(snapshots.clone()) .and_then(|catalog| catalog.with_connections(connections.clone())) .and_then(|catalog| catalog.with_bearer_overrides(overrides.clone())) .map_err(|()| PublicRunError::Configuration)?; + if scope.is_some() { + let product = local_tool_product(workspace, catalog, process)?; + let specs = discovery_specs(&discovery)?; + crate::capability_scope::validate_available( + scope, + product + .capabilities + .definitions() + .map(|d| d.metadata.id.as_str()) + .chain(specs.iter().map(|(d, _)| d.metadata.id.as_str())), + ) + .map_err(|()| PublicRunError::Configuration)?; + } + if snapshots.is_empty() { + return bind_capability_scope_digest(local_digest, scope); + } let mut profile = serde_json::json!({ "domain":"xgen.cli.local-and-tool-discovery-execution-profile/v1", "local_profile_digest":local_digest, @@ -3180,6 +3267,18 @@ fn execution_profile_with_discovery( .ok_or(PublicRunError::Internal)? .remove("http_read_profile"); } + bind_capability_scope_digest( + sha256_digest(&serde_jcs::to_vec(&profile).map_err(|_| PublicRunError::Internal)?), + scope, + ) +} + +fn bind_capability_scope_digest( + base: String, + scope: Option<&[String]>, +) -> Result { + let Some(scope) = scope else { return Ok(base) }; + let profile = serde_json::json!({"domain":"xgen.cli.capability-scope/v1","base":base,"capabilities":scope}); Ok(sha256_digest( &serde_jcs::to_vec(&profile).map_err(|_| PublicRunError::Internal)?, )) @@ -3672,7 +3771,8 @@ mod tests { None, &graph_discovery::Snapshots::new(), &crate::http_read::Connections::new(), - &crate::http_read::BearerOverrides::new() + &crate::http_read::BearerOverrides::new(), + None, ) .unwrap(), local_execution_profile_digest(&workspace, &catalog, None).unwrap() @@ -3686,7 +3786,8 @@ mod tests { None, &first, &crate::http_read::Connections::new(), - &crate::http_read::BearerOverrides::new() + &crate::http_read::BearerOverrides::new(), + None, ) .unwrap(), execution_profile_with_discovery( @@ -3695,7 +3796,8 @@ mod tests { None, &second, &crate::http_read::Connections::new(), - &crate::http_read::BearerOverrides::new() + &crate::http_read::BearerOverrides::new(), + None, ) .unwrap() ); @@ -3723,6 +3825,7 @@ mod tests { &snapshots, &connections, overrides, + None, ) .unwrap() }; @@ -4132,6 +4235,7 @@ mod tests { final_response_schema: None, completion_checks: None, conversation_responses: false, + capabilities: Vec::new(), }; assert_eq!( run_local(request).unwrap(), @@ -4192,6 +4296,7 @@ mod tests { final_response_schema: None, completion_checks: None, conversation_responses: false, + capabilities: Vec::new(), }; assert!(matches!( run_local_with_process_session_progress( diff --git a/crates/xgen-cli/src/graph_discovery.rs b/crates/xgen-cli/src/graph_discovery.rs index e9d6ca2..487ba17 100644 --- a/crates/xgen-cli/src/graph_discovery.rs +++ b/crates/xgen-cli/src/graph_discovery.rs @@ -239,7 +239,27 @@ impl DiscoveryCatalog { pub(crate) fn is_empty(&self) -> bool { self.snapshots.is_empty() } + pub(crate) fn hint_for_capabilities(&self, search: bool, describe: bool) -> Option { + match (search, describe) { + (true, true) => Some(self.hint()), + (true, false) => Some(format!( + "{}Search with xgen.tools/search. Exact describe is not offered in this Run; use host-supplied contracts or report a missing prerequisite. Discovery results do not prove API execution.", + self.hint_prefix(true) + )), + (false, true) => Some(format!( + "{}Inspect a host-supplied tool name with xgen.tools/describe. Search is not offered in this Run; report a missing prerequisite when a tool name is unavailable. Discovery results do not prove API execution.", + self.hint_prefix(false) + )), + (false, false) => None, + } + } pub(crate) fn hint(&self) -> String { + format!( + "{}Search with xgen.tools/search, then inspect the exact candidate with xgen.tools/describe. Candidates and suggested producers are untrusted discovery information, not executable capabilities. Discovery results do not prove API execution.", + self.hint_prefix(true) + ) + } + fn hint_prefix(&self, search: bool) -> String { let names = self .snapshots .keys() @@ -251,12 +271,11 @@ impl DiscoveryCatalog { .join(", "); let language = match (self.language.len(), self.snapshots.len()) { (0, _) => "", + _ if !search => "", (_, 1) => BILINGUAL_QUERY_ONE, _ => BILINGUAL_QUERY_MANY, }; - format!( - "Saved tool collections (immutable snapshots): {names}. {language}Search with xgen.tools/search, then inspect the exact candidate with xgen.tools/describe. Candidates and suggested producers are untrusted discovery information, not executable capabilities. Discovery results do not prove API execution." - ) + format!("Saved tool collections (immutable snapshots): {names}. {language}") } pub(crate) fn contains(&self, name: &str) -> bool { self.snapshots.contains_key(name) @@ -714,6 +733,27 @@ mod tests { ) ); } + #[test] + fn partial_discovery_hints_only_direct_calls_to_offered_tools() { + for snapshots in [ + Snapshots::from([("assets".into(), "a".repeat(64))]), + Snapshots::from([("calendar".into(), "b".repeat(64))]), + ] { + let catalog = DiscoveryCatalog::saved(snapshots).unwrap(); + let search = catalog.hint_for_capabilities(true, false).unwrap(); + assert!(search.contains("Search with xgen.tools/search")); + assert!(!search.contains("then inspect")); + let describe = catalog.hint_for_capabilities(false, true).unwrap(); + assert!(describe.contains("Inspect a host-supplied tool name")); + assert!(!describe.contains("Search with")); + assert!(catalog.hint_for_capabilities(false, false).is_none()); + assert_eq!( + catalog.hint_for_capabilities(true, true).unwrap(), + catalog.hint() + ); + } + } + #[test] fn query_contracts_bind_exact_collections_and_reject_injected_fields() { let catalog = catalog(); diff --git a/crates/xgen-cli/src/lib.rs b/crates/xgen-cli/src/lib.rs index 7fc8008..ab8bef5 100644 --- a/crates/xgen-cli/src/lib.rs +++ b/crates/xgen-cli/src/lib.rs @@ -3,6 +3,7 @@ mod allow_file; mod allow_path; mod allow_process; +mod capability_scope; mod change_report; mod composition; mod driver; diff --git a/crates/xgen-cli/src/main.rs b/crates/xgen-cli/src/main.rs index 9568ef7..33ab115 100644 --- a/crates/xgen-cli/src/main.rs +++ b/crates/xgen-cli/src/main.rs @@ -280,6 +280,9 @@ struct RunArgs { /// Explicitly allow goal/context/tool output transfer to the remote model boundary. #[arg(long)] allow_remote_model_egress: bool, + /// Restrict this Run to these capability IDs; repeat for more. Resume keeps the saved subset. + #[arg(long = "capability", value_name = "ID")] + capabilities: Vec, /// Approve each one-shot read-only action selected within the declared file/directory scope. #[arg(long)] allow_read: bool, @@ -761,6 +764,7 @@ impl repl::ReplHost for InteractiveHost { // The interactive driver admits this contract regardless; said // here so the request describes the Run it actually starts. conversation_responses: true, + capabilities: Vec::new(), }, &process_session, |run_id| { @@ -1297,6 +1301,7 @@ fn run_command(args: RunArgs, debug: bool) -> ExitCode { final_response_schema, completion_checks, conversation_responses: args.conversation_responses, + capabilities: args.capabilities, }; let started = |run_id: &str| eprintln!("XGEN_STARTED run_id={run_id}"); present(run_local_with_progress( diff --git a/crates/xgen-cli/src/manifest.rs b/crates/xgen-cli/src/manifest.rs index f8ec069..b6d003c 100644 --- a/crates/xgen-cli/src/manifest.rs +++ b/crates/xgen-cli/src/manifest.rs @@ -39,6 +39,8 @@ struct RunManifestRecord { http_read_connections: crate::http_read::Connections, #[serde(default, skip_serializing_if = "std::collections::BTreeMap::is_empty")] http_bearer_overrides: crate::http_read::BearerOverrides, + #[serde(default, skip_serializing_if = "Option::is_none")] + capability_scope: Option>, budget: ManifestBudget, #[serde(default, skip_serializing_if = "std::ops::Not::not")] conversation_responses: bool, @@ -167,6 +169,7 @@ impl RunManifest { tool_discovery_snapshots: crate::graph_discovery::Snapshots::new(), http_read_connections: crate::http_read::Connections::new(), http_bearer_overrides: crate::http_read::BearerOverrides::new(), + capability_scope: None, budget, conversation_responses: false, final_response_schema: None, @@ -180,6 +183,20 @@ impl RunManifest { }) } + pub(crate) fn with_capability_scope( + mut self, + scope: Option>, + ) -> Result { + self.record.capability_scope = scope; + validate_record(&self.record)?; + self.record_digest = digest_record(&self.record)?; + Ok(self) + } + + pub(crate) fn capability_scope(&self) -> Option<&[String]> { + self.record.capability_scope.as_deref() + } + pub(crate) fn with_http_bearer_overrides( mut self, overrides: crate::http_read::BearerOverrides, @@ -396,6 +413,13 @@ fn validate_record(record: &RunManifestRecord) -> Result<(), ManifestError> { }) { return Err(ManifestError::Invalid); } + if record + .capability_scope + .as_ref() + .is_some_and(|ids| !crate::capability_scope::valid(ids)) + { + return Err(ManifestError::Invalid); + } if !crate::http_read::valid_bearer_overrides( &record.http_bearer_overrides, &record.http_read_connections, @@ -545,6 +569,38 @@ mod tests { } } + #[test] + fn capability_scope_is_optional_bound_and_validated() { + let legacy = fixture(); + assert!(legacy.capability_scope().is_none()); + assert!( + !String::from_utf8(legacy.to_bytes().unwrap()) + .unwrap() + .contains("capabilityScope") + ); + for scope in [ + vec!["generic/read".into()], + vec!["generic/describe".into(), "generic/search".into()], + ] { + let bound = legacy.clone().with_capability_scope(Some(scope)).unwrap(); + assert_ne!(legacy.authority(), bound.authority()); + assert_eq!( + RunManifest::from_bytes(&bound.to_bytes().unwrap()).unwrap(), + bound + ); + let mut tampered: Value = serde_json::from_slice(&bound.to_bytes().unwrap()).unwrap(); + tampered["record"]["capabilityScope"] = serde_json::json!(["generic/write"]); + assert!(RunManifest::from_bytes(&serde_json::to_vec(&tampered).unwrap()).is_err()); + } + for ids in [ + vec![], + vec!["b".into(), "a".into()], + vec!["a".into(), "a".into()], + ] { + assert!(legacy.clone().with_capability_scope(Some(ids)).is_err()); + } + } + #[test] fn http_connections_are_optional_pinned_and_not_credentials() { let legacy = fixture(); diff --git a/crates/xgen-cli/tests/workspace_discovery.rs b/crates/xgen-cli/tests/workspace_discovery.rs index d53c9f6..f0bd3a3 100644 --- a/crates/xgen-cli/tests/workspace_discovery.rs +++ b/crates/xgen-cli/tests/workspace_discovery.rs @@ -20,6 +20,314 @@ const COMPLETION: &str = "workspace discovery completed"; const TEST_TIMEOUT: Duration = Duration::from_secs(60); const PROCESS_TIMEOUT: Duration = Duration::from_secs(180); +#[test] +fn capability_scope_persists_across_approval_and_resume_without_changing_receipts() { + for capability in ["xgeny.fs/read-text", "xgeny.fs/stat"] { + let fixture = tempdir().unwrap(); + let state = fixture.path().join("state"); + let workspace = fixture.path().join("workspace"); + fs::create_dir(&workspace).unwrap(); + fs::write(workspace.join("sample.txt"), "scope validation content").unwrap(); + let server = SequentialServer::spawn_responses(vec![ + plan_response( + "inspect", + "Inspect a file", + capability, + &json!({"path":"sample.txt"}), + ), + completion_response(), + ]); + let first = bounded_output(xgen(&state).args([ + "run", + "--workspace", + path_text(&workspace), + "--base-url", + &server.base_url, + "--model", + MODEL, + "--tokenizer", + TOKENIZER, + "--allow-dir", + ".", + "--allow-executable", + &format!("verifier={}", std::env::current_exe().unwrap().display()), + "--capability", + capability, + "--allow-remote-model-egress", + "Inspect the specified file.", + ])) + .unwrap(); + assert_eq!(first.status.code(), Some(10), "{}", stderr(&first)); + let run_id = extract_run_id(&stderr(&first)); + let initial = planning_context(&server.requests.recv_timeout(TEST_TIMEOUT).unwrap()); + assert_eq!(capability_ids(&initial), vec![capability]); + let constraints = initial["planningConstraints"].to_string(); + assert!( + !constraints.contains("process.executable-catalog"), + "unoffered process hint: {constraints}" + ); + assert!( + !constraints.contains("write-atomic"), + "unoffered write hint: {constraints}" + ); + let resumed = bounded_output(xgen(&state).args([ + "resume", + &run_id, + "--workspace", + path_text(&workspace), + "--base-url", + &server.base_url, + "--allow-dir", + ".", + "--allow-read", + "--allow-executable", + &format!("verifier={}", std::env::current_exe().unwrap().display()), + "--allow-remote-model-egress", + ])) + .unwrap(); + assert!(resumed.status.success(), "{}", stderr(&resumed)); + let completed = planning_context(&server.requests.recv_timeout(TEST_TIMEOUT).unwrap()); + assert_eq!(capability_ids(&completed), vec![capability]); + assert_eq!(completed["catalogDigest"], initial["catalogDigest"]); + assert_eq!(completed["toolOutputs"].as_array().unwrap().len(), 1); + assert_eq!( + completed["toolOutputs"][0]["capability"]["capabilityId"], + capability + ); + let replay = bounded_output(xgen(&state).args(["resume", &run_id])).unwrap(); + assert!(replay.status.success()); + server.handle.join().unwrap(); + } +} + +#[test] +fn capability_scope_exact_file_mode_preserves_provider_constraint_requirements() { + for executable in [None, Some("verifier"), Some("alternate")] { + let fixture = tempdir().unwrap(); + let workspace = fixture.path().join("workspace"); + fs::create_dir(&workspace).unwrap(); + fs::write(workspace.join("sample.txt"), "scoped exact file").unwrap(); + let state = fixture.path().join("state"); + let server = SequentialServer::spawn_responses(vec![ + plan_response( + "read", + "Read exact file", + "xgeny.fs/read-text", + &json!({"path":"sample.txt"}), + ), + completion_response(), + ]); + let mut command = xgen(&state); + command.args([ + "run", + "Read the exact allowed file", + "--workspace", + path_text(&workspace), + "--base-url", + &server.base_url, + "--model", + MODEL, + "--tokenizer", + TOKENIZER, + "--allow-file", + "sample.txt", + "--allow-read", + "--allow-remote-model-egress", + "--capability", + "xgeny.fs/read-text", + ]); + if let Some(id) = executable { + command.args([ + "--allow-executable", + &format!("{id}={}", std::env::current_exe().unwrap().display()), + ]); + } + let result = bounded_output(&mut command).unwrap(); + assert!( + result.status.success(), + "executable={executable:?}: {}", + stderr(&result) + ); + for _ in 0..2 { + let request = planning_context(&server.requests.recv_timeout(TEST_TIMEOUT).unwrap()); + assert_eq!(capability_ids(&request), vec!["xgeny.fs/read-text"]); + if executable.is_some() { + assert!( + request["planningConstraints"] + .as_array() + .is_some_and(|constraints| !constraints.is_empty()) + ); + assert!( + !request["planningConstraints"] + .to_string() + .contains("process.executable-catalog") + ); + } + } + server.handle.join().unwrap(); + } +} + +#[test] +fn capability_scope_rejects_completion_checks_without_process_capability_before_inference() { + for capability in ["xgeny.fs/read-text", "xgeny.fs/stat"] { + let fixture = tempdir().unwrap(); + let contract = fixture.path().join("contract.json"); + fs::write(&contract, json!({"response_schema":{"type":"object","properties":{"result":{"type":"string"}},"required":["result"],"additionalProperties":false},"checks":[{"id":"verify","argv":["verifier"]}]}).to_string()).unwrap(); + let state = fixture.path().join("state"); + let output = bounded_output(xgen(&state).args([ + "run", + "Verify the result", + "--workspace", + path_text(fixture.path()), + "--base-url", + "http://127.0.0.1:1/v1", + "--model", + MODEL, + "--tokenizer", + TOKENIZER, + "--allow-dir", + ".", + "--allow-remote-model-egress", + "--capability", + capability, + "--allow-executable", + &format!("verifier={}", std::env::current_exe().unwrap().display()), + "--completion-contract", + path_text(&contract), + ])) + .unwrap(); + assert_eq!(output.status.code(), Some(64), "{}", stderr(&output)); + assert!(!stderr(&output).contains("XGEN_STARTED")); + } +} + +#[test] +fn capability_scope_rejects_unoffered_action_even_with_write_permission() { + let fixture = tempdir().unwrap(); + let state = fixture.path().join("state"); + let workspace = fixture.path().join("workspace"); + fs::create_dir(&workspace).unwrap(); + let server = SequentialServer::spawn_responses((0..=xgen_cli::MAX_REJECTED_RESPONSE_RETRIES) + .map(|_| plan_response("write", "Unselected action", "xgeny.fs/write-atomic", + &json!({"path":"unwanted.txt","content":"must not execute","expectedDigest":null}))).collect()); + let output = bounded_output(xgen(&state).args([ + "run", + "--workspace", + path_text(&workspace), + "--base-url", + &server.base_url, + "--model", + MODEL, + "--tokenizer", + TOKENIZER, + "--allow-dir", + ".", + "--allow-write", + "--capability", + "xgeny.fs/read-text", + "--allow-remote-model-egress", + "Inspect only.", + ])) + .unwrap(); + assert_eq!(output.status.code(), Some(20), "{}", stderr(&output)); + assert!(!workspace.join("unwanted.txt").exists()); + for _ in 0..=xgen_cli::MAX_REJECTED_RESPONSE_RETRIES { + let request = server.requests.recv_timeout(TEST_TIMEOUT).unwrap(); + assert_eq!( + capability_ids(&planning_context(&request)), + vec!["xgeny.fs/read-text"] + ); + } + server.handle.join().unwrap(); +} + +#[test] +fn selected_write_still_requires_its_own_permission() { + let fixture = tempdir().unwrap(); + let state = fixture.path().join("state"); + let server = SequentialServer::spawn_responses(vec![ + plan_response( + "write", + "Write selected file", + "xgeny.fs/write-atomic", + &json!({"path":"selected.txt","content":"selected write","expectedDigest":null}), + ), + completion_response(), + ]); + let first = bounded_output(xgen(&state).args([ + "run", + "Write the requested file", + "--workspace", + path_text(fixture.path()), + "--base-url", + &server.base_url, + "--model", + MODEL, + "--tokenizer", + TOKENIZER, + "--allow-dir", + ".", + "--allow-read", + "--allow-remote-model-egress", + "--capability", + "xgeny.fs/write-atomic", + ])) + .unwrap(); + assert_eq!(first.status.code(), Some(10), "{}", stderr(&first)); + assert!(!fixture.path().join("selected.txt").exists()); + let run_id = extract_run_id(&stderr(&first)); + let resumed = bounded_output(xgen(&state).args([ + "resume", + &run_id, + "--workspace", + path_text(fixture.path()), + "--allow-dir", + ".", + "--base-url", + &server.base_url, + "--allow-write", + "--allow-remote-model-egress", + ])) + .unwrap(); + assert!(resumed.status.success(), "{}", stderr(&resumed)); + assert_eq!( + fs::read_to_string(fixture.path().join("selected.txt")).unwrap(), + "selected write" + ); + server.handle.join().unwrap(); +} + +#[test] +fn capability_scope_unknown_or_duplicate_ids_fail_before_provider_access() { + for scope in [ + vec!["absent/read"], + vec!["xgen.http/read"], + vec!["xgeny.fs/stat", "xgeny.fs/stat"], + ] { + let fixture = tempdir().unwrap(); + let mut command = xgen(&fixture.path().join("state")); + command.args([ + "run", + "--workspace", + path_text(fixture.path()), + "--base-url", + "http://127.0.0.1:1/v1", + "--model", + MODEL, + "--allow-dir", + ".", + "--allow-remote-model-egress", + ]); + for id in scope { + command.args(["--capability", id]); + } + let output = bounded_output(command.arg("No provider access")).unwrap(); + assert_eq!(output.status.code(), Some(64), "{}", stderr(&output)); + assert!(!stderr(&output).contains("XGEN_STARTED")); + } +} + #[test] fn invocation_diagnostics_distinguish_schema_and_resource_failures_without_values() { let cases = [ diff --git a/docs/adr/0087-run-capability-scope.md b/docs/adr/0087-run-capability-scope.md new file mode 100644 index 0000000..96aa665 --- /dev/null +++ b/docs/adr/0087-run-capability-scope.md @@ -0,0 +1,55 @@ +# ADR-0087: Run별 capability 범위 고정 + +- 날짜: 2026-11-19 +- 상태: 채택, 구현·로컬 검증 완료 +- 범위: 일반 호스트 설정. 도메인별 도구 선택 규칙이나 모델의 자동 검색은 포함하지 않는다. + +## 문제와 결정 + +일부 도구만 필요한 실행에도 전체 capability schema가 planning context에 들어갔다. +`xgen run --capability ID`를 반복 지정하면 원래 등록 가능한 정의와 instance의 부분집합만 +CapabilityRegistry에 등록한다. 같은 registry를 모델 카탈로그와 proposal admission에 사용한다. +숨긴 도구의 제안은 실행 전에 거절한다. API 원문·tool output·Receipt 내용은 축약하지 않는다. + +목록은 최대128개·ID256 bytes, 정렬·중복 검사·가용성 검증을 거친다. 잘못되거나 등록되지 않은 ID는 +Run 생성·모델 호출 전에 거절한다. 기본 empty 입력은 None이며 기존 전체 카탈로그를 유지한다. +선택은 권한 부여가 아니다. 선택된 write도 별도 write 승인이 필요하고, 범위 밖 write는 승인 여부와 +무관하게 admission에서 거절한다. + +정렬한 scope를 manifest의 선택 필드 capabilityScope와 authority·execution profile digest에 +결합한다. resume은 새 범위 옵션을 받지 않고 저장된 범위를 복원한다. 기본 None은 직렬화에서 +생략하고 기존 profile digest를 유지한다. 완료된 Run의 offline replay도 유지한다. + +## 안내와 필수 조건의 일치 + +등록된 capability의 ID·resource selector에서 planning 안내의 적용 대상을 유도한다. +파일 도구가 없으면 workspace 안내를, process 도구가 없으면 실행 파일 안내를 보내지 않는다. +명시적 파일 subset에는 경로 범위만 알려 주고 개별 도구 계약은 선택된 definition에 맡긴다. +terminal·web만 제공한 Run에는 executable ID 목록을 알리되 process.execute 사용을 지시하지 않는다. +search/describe는 각각 실제 제공 여부에 맞춰 안내하며, search가 없으면 검색어 언어 힌트 조회도 생략한다. +기본 전체 카탈로그의 안내 문장은 기존과 동일하다. 명시적 범위와 기존 constrained composition의 +조합에는 범위 안내를 추가해, 다른 안내가 모두 제외되어도 provider의 nonempty constraint 계약을 지킨다. +정확한 allow-file 모드와 제외된 실행 파일 catalog를 함께 쓰는 경우에도 실행·재개가 가능하다. + +HTTP read만 선택할 수 있다. 호스트가 정확한 contractDigest·입력을 제공하면 원본 계약으로 검증한다. +필요한 describe가 없고 계약도 없으면 선행조건 부족을 보고해야 한다. 계약을 추측해 호출할 권한은 없다. + +completion contract의 필수 process 검사가 있는데 process.execute를 제외한 설정은 모순이다. +이 조합은 모델 호출 전에 거절한다. 일반 선택 범위에 임의의 선행 도구를 자동 추가하지 않는다. + +## 검증과 한계 + +설계 검사에서 read-text/stat의 승인 대기·재개·동일 catalog·완료 replay, 선택된 write의 별도 승인, +범위 밖 write 차단, 모르는/미등록/중복 ID·manifest 변조·필수 검사 모순을 검증한다. +선택하지 않은 process·write 안내와 필수 검사 충돌은 수정 전 실행에서도 실패를 재현했다. + +별도 shipment/sensor fixture의 실제 loopback API·결정적 모델에서 HTTP read-only/describe-only +범위와 안내 일치, 기본 대비 요청 크기 감소, 동일 API 입력·응답 본문 유지를 확인한다. +실제 LLM의 판단 품질·성공률·금액 절감은 측정하지 않는다. 큰 본문·누적 기록은 별도로 입력 한도를 넘을 수 있다. + +독립 diff 검토 도구는 인증 오류로 실행하지 못했다. 코드 직접 검토와 native·CLI 회귀 검증으로 확인한다. + +최종 로컬 검증: Rust798개 통과(4 ignored), system Python3.14+pinned graph-tool-call0.47.0+컴파일 CLI의 +Python162개 검사 통과(9 skipped), Clippy·fmt·protocol·문서·workflow 검사 통과. 이전 rc.6 바이너리로 +시작한 미완료 HTTP Run도 두 fixture에서 새 바이너리로 동일 catalog·API 계약을 유지해 재개했다. +Python3.14 검사 중 SQLite ResourceWarning이 출력됐지만 검사 실패는 없었다. diff --git a/docs/development/capability-scope.md b/docs/development/capability-scope.md new file mode 100644 index 0000000..1ae08d3 --- /dev/null +++ b/docs/development/capability-scope.md @@ -0,0 +1,33 @@ +# Run별 capability 범위 + +`run --capability ID`로 계획과 실행에 등록할 capability ID를 제한해. 여러 번 지정할 수 있어. +옵션을 생략하면 기존 전체 catalog를 유지해. 특정 업무나 모델에 종속되지 않는 일반 기능이야. + +```sh +xgen run --workspace . --allow-dir . --allow-read --allow-remote-model-egress \ + --capability xgeny.fs/read-text 'README.md를 읽고 요약해' +``` + +선택은 원래 등록 가능한 정의와 instance의 부분집합이야. 모르는 ID·중복 ID는 Run을 만들거나 +모델에 요청하기 전에 거절해. capability를 선택해도 파일·HTTP·실행 승인 조건은 그대로 필요해. +모델이 목록 밖의 작업을 제안하면 admission에서 거절해. + +정렬된 목록을 manifest, authority, 실행 profile digest에 결속해. `resume`은 저장된 범위를 +복원하고 새 범위 옵션을 받지 않아. 기본값은 manifest에 새 필드를 저장하지 않아 이전 Run과 +전체 catalog 경로를 유지해. 도구 반환값·Receipt·원문은 수정하거나 요약하지 않아. + +HTTP read만 선택한 호스트는 `tools describe`로 확인한 정확한 요청·contractDigest를 goal에 +전달할 수 있어. describe가 범위 밖이고 계약도 없다면 에이전트는 선행조건 부족을 보고해야 해. +범위 선택은 부족한 계약을 추측하거나 HTTP 권한을 부여하는 기능이 아니야. + +선택 범위에 맞춰 workspace·process·검색·describe 안내도 제한해. search가 없으면 검색어 언어 힌트를 +조회하지 않아. 필수 완료 검사에 process.execute가 필요한데 이를 제외하면 모델 호출 전에 거절해. +기존 write/read 승인·credential·연결 drift 검사는 그대로 적용해. + +검증은 [ADR-0087](../adr/0087-run-capability-scope.md)을 참고해. read/stat 승인 후 재개·선택 write의 +별도 승인·범위 밖 write 차단과 shipment/sensor의 HTTP 입력·본문 동일성, 요청 크기 감소를 확인해. +실제 모델의 판단 품질 향상·토큰 과금 절감은 측정하지 않았어. + +검증 결과: Rust798개 통과(4 ignored), Python162개 검사 통과(9 skipped), Clippy·fmt·문서·workflow +검사 통과. 기존 rc.6 바이너리에서 시작한 범위 미지정 Run의 재개도 두 HTTP fixture에서 확인했어. +이 기능은 rc.6 배포 이후의 main 변경이야. diff --git a/scripts/tests/test_capability_scope.py b/scripts/tests/test_capability_scope.py new file mode 100644 index 0000000..30c96dd --- /dev/null +++ b/scripts/tests/test_capability_scope.py @@ -0,0 +1,78 @@ +"""Capability selection on held-out HTTP fixtures; only loopback endpoints are used.""" +import json +import os +import unittest + +import test_http_read_tools as http + + +@unittest.skipUnless(os.environ.get("XGEN_TOOL_TEST_BINARY"), "compiled CLI opt-in") +class CapabilityScopeHttpTests(unittest.TestCase): + setUp = http.HttpCliTests.setUp + server = http.HttpCliTests.server + cli = http.HttpCliTests.cli + install = http.HttpCliTests.install + plan = staticmethod(http.HttpCliTests.plan) + context = staticmethod(http.HttpCliTests.context) + run_cli = http.HttpCliTests.run_cli + + def test_only_offered_discovery_and_http_hints_reach_the_model(self): + for name in ("shipments", "sensors"): + arguments = self.install(name) + self.response = {"tracking":"A42", "delivered":True} if name == "shipments" else {"values":[1.5]} + for capability in ("xgen.http/read", "xgen.tools/describe"): + self.requests.clear(); self.calls.clear() + args = arguments if capability == "xgen.http/read" else {"collection":name, "tool":arguments["tool"]} + self.proposals = [self.plan("inspect", capability, args)] + result = self.run_cli(extra=("--capability", capability)) + self.assertEqual(result.returncode, 0, result.stderr.decode()) + for request in self.requests: + context = self.context(request) + self.assertEqual([item["capability"]["capabilityId"] for item in context["capabilities"]], [capability]) + constraints = {item["constraintId"]:item["description"] for item in context["planningConstraints"]} + self.assertNotIn("workspace.fs-scope", constraints) + self.assertNotIn("process.executable-catalog", constraints) + if capability == "xgen.http/read": + self.assertNotIn("tools.discovery-snapshots", constraints) + self.assertNotIn("First describe", constraints["http.read-connections"]) + else: + self.assertNotIn("http.read-connections", constraints) + self.assertNotIn("Search with", constraints["tools.discovery-snapshots"]) + self.assertEqual(len(self.calls), int(capability == "xgen.http/read")) + + def test_smaller_requests_preserve_actual_api_input_and_response(self): + for name in ("shipments", "sensors"): + arguments = self.install(name) + self.response = {"tracking":"A42", "delivered":True} if name == "shipments" else {"values":[2.5]} + sizes, calls, bodies = [], [], [] + for extra in ((), ("--capability", "xgen.http/read")): + self.requests.clear(); self.calls.clear() + self.proposals = [self.plan("inspect", "xgen.http/read", arguments)] + result = self.run_cli(extra=extra) + self.assertEqual(result.returncode, 0, result.stderr.decode()) + sizes.append(len(json.dumps(self.requests[0], ensure_ascii=False).encode())) + calls.append(self.calls.copy()) + outputs = self.context(self.requests[-1])["toolOutputs"] + bodies.append(outputs[0]["output"]["body"]) + self.assertEqual(outputs[0]["output"]["request"], arguments) + self.assertLess(sizes[1], sizes[0]) + self.assertTrue(calls[0] == calls[1], "API requests changed with capability scope") + self.assertEqual(bodies, [self.response, self.response]) + + @unittest.skipUnless(os.environ.get("XGEN_SCOPE_PREVIOUS_BINARY"), "previous unscoped binary opt-in") + def test_previous_unscoped_runs_resume_with_the_same_catalog_and_api_contract(self): + for name in ("shipments", "sensors"): + arguments = self.install(name) + self.response = {"tracking":"A42", "delivered":True} if name == "shipments" else {"values":[3.5]} + self.requests.clear(); self.calls.clear() + self.proposals = [self.plan("inspect", "xgen.http/read", arguments)] + paused = self.run_cli(allow=False, binary=os.environ["XGEN_SCOPE_PREVIOUS_BINARY"]) + self.assertEqual(paused.returncode, 10, paused.stderr.decode()) + run_id = next(line.split("run_id=", 1)[1].split()[0] for line in paused.stderr.decode().splitlines() if line.startswith("XGEN_STARTED ")) + first = self.context(self.requests[0]) + resumed = self.cli("resume", run_id, "--workspace", str(self.workspace), "--allow-dir", ".", "--allow-read", "--allow-remote-model-egress", "--base-url", f"http://127.0.0.1:{self.model.server_port}/v1", check=False) + self.assertEqual(resumed.returncode, 0, resumed.stderr.decode()) + final = self.context(self.requests[-1]) + self.assertEqual(first["catalogDigest"], final["catalogDigest"]) + self.assertEqual(final["toolOutputs"][0]["output"]["body"], self.response) + self.assertEqual(len(self.calls), 1)