From e39379327f11183525881d055148b77776a0f98b Mon Sep 17 00:00:00 2001 From: Chojan Shang Date: Wed, 2 Sep 2026 15:24:38 +0800 Subject: [PATCH 01/17] feat(scope): add durable organization and bindings --- .../builtin/persistence/tables.py | 86 +++++- src/powercontext/builtin/scope/__init__.py | 52 ++++ src/powercontext/builtin/scope/application.py | 246 +++++++++++++++ src/powercontext/builtin/scope/errors.py | 57 ++++ src/powercontext/builtin/scope/models.py | 232 ++++++++++++++ src/powercontext/builtin/scope/repository.py | 289 ++++++++++++++++++ src/powercontext/limits.py | 8 + tests/builtin/test_scope_application.py | 238 +++++++++++++++ 8 files changed, 1207 insertions(+), 1 deletion(-) create mode 100644 src/powercontext/builtin/scope/__init__.py create mode 100644 src/powercontext/builtin/scope/application.py create mode 100644 src/powercontext/builtin/scope/errors.py create mode 100644 src/powercontext/builtin/scope/models.py create mode 100644 src/powercontext/builtin/scope/repository.py create mode 100644 tests/builtin/test_scope_application.py diff --git a/src/powercontext/builtin/persistence/tables.py b/src/powercontext/builtin/persistence/tables.py index 99e1013a6..5085d1561 100644 --- a/src/powercontext/builtin/persistence/tables.py +++ b/src/powercontext/builtin/persistence/tables.py @@ -39,7 +39,15 @@ MAX_EXTERNAL_SKILL_HOST_ID_LENGTH, MAX_EXTERNAL_SKILL_LOCATOR_LENGTH, MAX_EXTERNAL_SKILL_NAME_LENGTH, + MAX_SCOPE_BINDING_EXTERNAL_ID_LENGTH, + MAX_SCOPE_BINDING_INTEGRATION_LENGTH, + MAX_SCOPE_BINDING_KIND_LENGTH, + MAX_SCOPE_EXTERNAL_REFERENCE_KIND_LENGTH, + MAX_SCOPE_EXTERNAL_REFERENCE_VALUE_LENGTH, MAX_SCOPE_ID_LENGTH, + MAX_SCOPE_IDEMPOTENCY_KEY_LENGTH, + MAX_SCOPE_SUMMARY_LENGTH, + MAX_SCOPE_TITLE_LENGTH, MAX_SOURCE_ID_LENGTH, MAX_SOURCE_TYPE_LENGTH, ) @@ -75,6 +83,82 @@ def _entry_text_type(): return Text().with_variant(MEDIUMTEXT(), "mysql") +SCOPES_TABLE = Table( + "pc_scopes", + SHARED_METADATA, + Column("scope_id", identity_string(MAX_SCOPE_ID_LENGTH), primary_key=True), + Column("title", String(MAX_SCOPE_TITLE_LENGTH), nullable=False), + Column("summary", String(MAX_SCOPE_SUMMARY_LENGTH), nullable=False), + Column("parent_scope_id", identity_string(MAX_SCOPE_ID_LENGTH)), + Column("version", Integer, nullable=False), + ForeignKeyConstraint( + ("parent_scope_id",), + ("pc_scopes.scope_id",), + ondelete="RESTRICT", + ), + CheckConstraint("version > 0", name="ck_pc_scopes_version_positive"), +) + +SCOPE_CONTEXT_REFERENCES_TABLE = Table( + "pc_scope_context_references", + SHARED_METADATA, + Column("scope_id", identity_string(MAX_SCOPE_ID_LENGTH), primary_key=True), + Column("referenced_scope_id", identity_string(MAX_SCOPE_ID_LENGTH), primary_key=True), + ForeignKeyConstraint(("scope_id",), ("pc_scopes.scope_id",), ondelete="CASCADE"), + ForeignKeyConstraint(("referenced_scope_id",), ("pc_scopes.scope_id",), ondelete="RESTRICT"), + CheckConstraint("scope_id <> referenced_scope_id", name="ck_pc_scope_context_references_not_self"), +) + +SCOPE_EXTERNAL_REFERENCES_TABLE = Table( + "pc_scope_external_references", + SHARED_METADATA, + Column("scope_id", identity_string(MAX_SCOPE_ID_LENGTH), primary_key=True), + Column("ordinal", Integer, primary_key=True), + Column("kind", identity_string(MAX_SCOPE_EXTERNAL_REFERENCE_KIND_LENGTH), nullable=False), + Column("value", String(MAX_SCOPE_EXTERNAL_REFERENCE_VALUE_LENGTH), nullable=False), + Column("value_digest", identity_string(64), nullable=False), + ForeignKeyConstraint(("scope_id",), ("pc_scopes.scope_id",), ondelete="CASCADE"), + UniqueConstraint("scope_id", "kind", "value_digest", name="uq_pc_scope_external_references_value"), + CheckConstraint("ordinal >= 0", name="ck_pc_scope_external_references_ordinal_nonnegative"), +) + +SCOPE_CREATION_REQUESTS_TABLE = Table( + "pc_scope_creation_requests", + SHARED_METADATA, + Column("idempotency_key", identity_string(MAX_SCOPE_IDEMPOTENCY_KEY_LENGTH), primary_key=True), + Column("request_digest", identity_string(64), nullable=False), + Column("scope_id", identity_string(MAX_SCOPE_ID_LENGTH), nullable=False), + ForeignKeyConstraint(("scope_id",), ("pc_scopes.scope_id",), ondelete="RESTRICT"), +) + +SCOPE_SETTINGS_TABLE = Table( + "pc_scope_settings", + SHARED_METADATA, + Column("name", identity_string(64), primary_key=True), + Column("scope_id", identity_string(MAX_SCOPE_ID_LENGTH), nullable=False), + ForeignKeyConstraint(("scope_id",), ("pc_scopes.scope_id",), ondelete="RESTRICT"), +) + +SCOPE_BINDINGS_TABLE = Table( + "pc_scope_bindings", + SHARED_METADATA, + Column("integration", identity_string(MAX_SCOPE_BINDING_INTEGRATION_LENGTH), primary_key=True), + Column("kind", identity_string(MAX_SCOPE_BINDING_KIND_LENGTH), primary_key=True), + Column("external_id", identity_string(MAX_SCOPE_BINDING_EXTERNAL_ID_LENGTH), primary_key=True), + Column("scope_id", identity_string(MAX_SCOPE_ID_LENGTH), nullable=False), + ForeignKeyConstraint(("scope_id",), ("pc_scopes.scope_id",), ondelete="RESTRICT"), +) + +SCOPE_TABLES = ( + SCOPES_TABLE, + SCOPE_CONTEXT_REFERENCES_TABLE, + SCOPE_EXTERNAL_REFERENCES_TABLE, + SCOPE_CREATION_REQUESTS_TABLE, + SCOPE_SETTINGS_TABLE, + SCOPE_BINDINGS_TABLE, +) + + SOURCES_TABLE = Table( "pc_sources", SHARED_METADATA, @@ -452,4 +536,4 @@ def _entry_text_type(): STATISTICS_TABLES = (MODEL_USAGE_DAILY_TABLE, RECALL_TOKEN_DAILY_TABLE) -BUILTIN_TABLES = SHARED_TABLES + MEMORY_TABLES + STATISTICS_TABLES +BUILTIN_TABLES = SCOPE_TABLES + SHARED_TABLES + MEMORY_TABLES + STATISTICS_TABLES diff --git a/src/powercontext/builtin/scope/__init__.py b/src/powercontext/builtin/scope/__init__.py new file mode 100644 index 000000000..04d76b375 --- /dev/null +++ b/src/powercontext/builtin/scope/__init__.py @@ -0,0 +1,52 @@ +# Copyright (c) 2026 OceanBase. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +"""Durable Scope organization and binding.""" + +from powercontext.builtin.scope.application import ScopeApplication, generate_scope_id +from powercontext.builtin.scope.errors import ( + ScopeBindingNotFoundError, + ScopeError, + ScopeIdempotencyConflictError, + ScopeNotFoundError, + ScopeRelationshipError, + ScopeVersionConflictError, +) +from powercontext.builtin.scope.models import ( + ScopeBinding, + ScopeBindingKey, + ScopeDescriptor, + ScopeDraft, + ScopeExternalReference, + ScopeMutation, + ScopeSelection, +) + +__all__ = [ + "ScopeApplication", + "ScopeBinding", + "ScopeBindingKey", + "ScopeBindingNotFoundError", + "ScopeDescriptor", + "ScopeDraft", + "ScopeError", + "ScopeExternalReference", + "ScopeIdempotencyConflictError", + "ScopeMutation", + "ScopeNotFoundError", + "ScopeRelationshipError", + "ScopeSelection", + "ScopeVersionConflictError", + "generate_scope_id", +] diff --git a/src/powercontext/builtin/scope/application.py b/src/powercontext/builtin/scope/application.py new file mode 100644 index 000000000..34b406734 --- /dev/null +++ b/src/powercontext/builtin/scope/application.py @@ -0,0 +1,246 @@ +# Copyright (c) 2026 OceanBase. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +"""Application service for Scope ownership, organization, and binding.""" + +from __future__ import annotations + +import asyncio +import hashlib +import secrets +from collections import deque +from collections.abc import Callable, Sequence + +from powercontext.builtin.persistence.database import AsyncDatabase +from powercontext.builtin.scope.errors import ( + ScopeBindingNotFoundError, + ScopeIdempotencyConflictError, + ScopeNotFoundError, + ScopeRelationshipError, + ScopeVersionConflictError, +) +from powercontext.builtin.scope.models import ( + ScopeBinding, + ScopeBindingKey, + ScopeDescriptor, + ScopeDraft, + ScopeMutation, + ScopeSelection, +) +from powercontext.builtin.scope.repository import ScopeRepository + +ScopeIdFactory = Callable[[], str] +_CROCKFORD = "0123456789abcdefghjkmnpqrstvwxyz" +_DEFAULT_IDEMPOTENCY_KEY = "powercontext.default-scope.v1" + + +class ScopeApplication: + def __init__( + self, + database: AsyncDatabase, + *, + repository: ScopeRepository | None = None, + id_factory: ScopeIdFactory | None = None, + ) -> None: + self._database = database + self._repository = ScopeRepository() if repository is None else repository + self._id_factory = generate_scope_id if id_factory is None else id_factory + self._write_lock = asyncio.Lock() + + async def bootstrap_default(self) -> ScopeDescriptor: + existing = await self.default_scope() + if existing is not None: + return existing + created = await self.create( + ScopeDraft( + title="Default", + summary="Default context", + idempotency_key=_DEFAULT_IDEMPOTENCY_KEY, + ) + ) + await self.set_default(created.scope_id) + return created + + async def create(self, draft: ScopeDraft, /) -> ScopeDescriptor: + async with self._write_lock: + return await self._create(draft) + + async def _create(self, draft: ScopeDraft) -> ScopeDescriptor: + digest = _draft_digest(draft) + async with self._database.transaction() as connection: + existing = await self._repository.creation(connection, draft.idempotency_key) + if existing is not None: + existing_digest, scope_id = existing + if existing_digest != digest: + raise ScopeIdempotencyConflictError(draft.idempotency_key) + return await self._required(connection, scope_id) + await self._validate_relationships( + connection, + scope_id=None, + parent_scope_id=draft.parent_scope_id, + context_references=draft.context_references, + ) + return await self._repository.add(connection, self._id_factory(), draft, digest) + + async def get(self, scope_id: str, /) -> ScopeDescriptor: + async with self._database.transaction() as connection: + return await self._required(connection, scope_id) + + async def list(self) -> tuple[ScopeDescriptor, ...]: + async with self._database.transaction() as connection: + return await self._repository.list(connection) + + async def update(self, scope_id: str, mutation: ScopeMutation, /) -> ScopeDescriptor: + async with self._write_lock: + return await self._update(scope_id, mutation) + + async def _update(self, scope_id: str, mutation: ScopeMutation) -> ScopeDescriptor: + async with self._database.transaction() as connection: + current = await self._required(connection, scope_id) + if current.version != mutation.expected_version: + raise ScopeVersionConflictError(scope_id, mutation.expected_version, current.version) + await self._validate_relationships( + connection, + scope_id=scope_id, + parent_scope_id=mutation.parent_scope_id, + context_references=mutation.context_references, + ) + if not await self._repository.replace(connection, scope_id, mutation): + refreshed = await self._required(connection, scope_id) + raise ScopeVersionConflictError(scope_id, mutation.expected_version, refreshed.version) + return await self._required(connection, scope_id) + + async def default_scope(self) -> ScopeDescriptor | None: + async with self._database.transaction() as connection: + scope_id = await self._repository.default_scope_id(connection) + return None if scope_id is None else await self._required(connection, scope_id) + + async def set_default(self, scope_id: str, /) -> ScopeDescriptor: + async with self._write_lock, self._database.transaction() as connection: + scope = await self._required(connection, scope_id) + await self._repository.set_default(connection, scope_id) + return scope + + async def bind(self, key: ScopeBindingKey, scope_id: str, /) -> ScopeBinding: + async with self._write_lock, self._database.transaction() as connection: + await self._required(connection, scope_id) + return await self._repository.set_binding(connection, key, scope_id) + + async def binding(self, key: ScopeBindingKey, /) -> ScopeBinding | None: + async with self._database.transaction() as connection: + return await self._repository.binding(connection, key) + + async def clear_binding(self, key: ScopeBindingKey, /) -> bool: + async with self._write_lock, self._database.transaction() as connection: + return await self._repository.clear_binding(connection, key) + + async def resolve_binding( + self, + *, + explicit_scope_id: str | None = None, + binding_keys: Sequence[ScopeBindingKey] = (), + ) -> ScopeDescriptor: + async with self._database.transaction() as connection: + if explicit_scope_id is not None: + return await self._required(connection, explicit_scope_id) + for key in binding_keys: + binding = await self._repository.binding(connection, key) + if binding is not None: + return await self._required(connection, binding.scope_id) + default_scope_id = await self._repository.default_scope_id(connection) + if default_scope_id is None: + raise ScopeBindingNotFoundError + return await self._required(connection, default_scope_id) + + async def resolve_selection(self, selection: ScopeSelection, /) -> tuple[ScopeDescriptor, ...]: + async with self._database.transaction() as connection: + if selection.mode == "all": + return await self._repository.list(connection) + if selection.mode == "exact": + resolved = await self._repository.get_many(connection, selection.scope_ids) + found = {scope.scope_id for scope in resolved} + if missing := next((scope_id for scope_id in selection.scope_ids if scope_id not in found), None): + raise ScopeNotFoundError(missing) + return resolved + root_scope_id = selection.root_scope_id + if root_scope_id is None: + raise AssertionError + scopes = await self._repository.list(connection) + return _subtree(scopes, root_scope_id) + + async def _required(self, connection, scope_id: str) -> ScopeDescriptor: + scope = await self._repository.get(connection, scope_id) + if scope is None: + raise ScopeNotFoundError(scope_id) + return scope + + async def _validate_relationships( + self, + connection, + *, + scope_id: str | None, + parent_scope_id: str | None, + context_references: tuple[str, ...], + ) -> None: + if scope_id is not None and parent_scope_id == scope_id: + raise ScopeRelationshipError("Parent", "a Scope cannot parent itself") + if parent_scope_id is not None: + parent = await self._required(connection, parent_scope_id) + while parent.parent_scope_id is not None: + if parent.parent_scope_id == scope_id: + raise ScopeRelationshipError("Parent", "relationships must be acyclic") + parent = await self._required(connection, parent.parent_scope_id) + for referenced_scope_id in context_references: + if referenced_scope_id == scope_id: + raise ScopeRelationshipError( # noqa: TRY003 + "Context Reference", + "a Scope cannot reference itself", + ) + await self._required(connection, referenced_scope_id) + + +def generate_scope_id() -> str: + """Generate the RFC-defined 128-bit opaque Scope identity.""" + + value = int.from_bytes(secrets.token_bytes(16), "big") + encoded = "".join(_CROCKFORD[(value >> shift) & 31] for shift in range(125, -1, -5)) + return f"scp_{encoded}" + + +def _draft_digest(draft: ScopeDraft) -> str: + payload = draft.model_dump_json(exclude={"idempotency_key"}) + return hashlib.sha256(payload.encode()).hexdigest() + + +def _subtree(scopes: tuple[ScopeDescriptor, ...], root_scope_id: str) -> tuple[ScopeDescriptor, ...]: + by_id = {scope.scope_id: scope for scope in scopes} + root = by_id.get(root_scope_id) + if root is None: + raise ScopeNotFoundError(root_scope_id) + children: dict[str, list[ScopeDescriptor]] = {} + for scope in scopes: + if scope.parent_scope_id is not None: + children.setdefault(scope.parent_scope_id, []).append(scope) + resolved = [root] + pending = deque([root.scope_id]) + visited = {root.scope_id} + while pending: + parent_scope_id = pending.popleft() + for child in children.get(parent_scope_id, ()): + if child.scope_id in visited: + continue + visited.add(child.scope_id) + resolved.append(child) + pending.append(child.scope_id) + return tuple(resolved) diff --git a/src/powercontext/builtin/scope/errors.py b/src/powercontext/builtin/scope/errors.py new file mode 100644 index 000000000..a55548877 --- /dev/null +++ b/src/powercontext/builtin/scope/errors.py @@ -0,0 +1,57 @@ +# Copyright (c) 2026 OceanBase. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +"""Stable failures for Scope organization and binding.""" + +from __future__ import annotations + +from powercontext.errors import PowerContextError + + +class ScopeError(PowerContextError): + """Base failure for Scope operations.""" + + +class ScopeNotFoundError(ScopeError, LookupError): + def __init__(self, scope_id: str) -> None: + self.scope_id = scope_id + super().__init__("scope was not found") + + +class ScopeVersionConflictError(ScopeError, RuntimeError): + def __init__(self, scope_id: str, expected: int, actual: int) -> None: + self.scope_id = scope_id + self.expected = expected + self.actual = actual + super().__init__("scope metadata changed since it was read") + + +class ScopeIdempotencyConflictError(ScopeError, RuntimeError): + def __init__(self, idempotency_key: str) -> None: + self.idempotency_key = idempotency_key + super().__init__("scope creation key was reused with different parameters") + + +class ScopeRelationshipError(ScopeError, ValueError): + def __init__(self, relationship: str, issue: str) -> None: + self.relationship = relationship + self.issue = issue + super().__init__(f"invalid Scope {relationship}: {issue}") + + +class ScopeBindingNotFoundError(ScopeError, LookupError): + """Raised when no explicit, durable, or default binding can be resolved.""" + + def __init__(self) -> None: + super().__init__("no Scope binding is available") diff --git a/src/powercontext/builtin/scope/models.py b/src/powercontext/builtin/scope/models.py new file mode 100644 index 000000000..a3e6b192e --- /dev/null +++ b/src/powercontext/builtin/scope/models.py @@ -0,0 +1,232 @@ +# Copyright (c) 2026 OceanBase. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +"""Domain values for Scope organization, observation, and external binding.""" + +from __future__ import annotations + +from typing import Literal + +from pydantic import BaseModel, ConfigDict, Field, StrictInt, field_validator, model_serializer, model_validator + +from powercontext.builtin.sources import validate_scope_id +from powercontext.limits import ( + MAX_SCOPE_BINDING_EXTERNAL_ID_LENGTH, + MAX_SCOPE_BINDING_INTEGRATION_LENGTH, + MAX_SCOPE_BINDING_KIND_LENGTH, + MAX_SCOPE_EXTERNAL_REFERENCE_KIND_LENGTH, + MAX_SCOPE_EXTERNAL_REFERENCE_VALUE_LENGTH, + MAX_SCOPE_IDEMPOTENCY_KEY_LENGTH, + MAX_SCOPE_SUMMARY_LENGTH, + MAX_SCOPE_TITLE_LENGTH, +) + + +class _ScopeValue(BaseModel): + model_config = ConfigDict(extra="forbid", frozen=True) + + +class ScopeExternalReference(_ScopeValue): + kind: str + value: str + + @field_validator("kind") + @classmethod + def validate_kind(cls, value: str) -> str: + return _required_text("kind", value, MAX_SCOPE_EXTERNAL_REFERENCE_KIND_LENGTH) + + @field_validator("value") + @classmethod + def validate_value(cls, value: str) -> str: + return _required_text("value", value, MAX_SCOPE_EXTERNAL_REFERENCE_VALUE_LENGTH) + + +class ScopeDraft(_ScopeValue): + title: str + summary: str + parent_scope_id: str | None = None + context_references: tuple[str, ...] = () + external_references: tuple[ScopeExternalReference, ...] = () + idempotency_key: str + + @field_validator("title") + @classmethod + def validate_title(cls, value: str) -> str: + return _required_text("title", value, MAX_SCOPE_TITLE_LENGTH) + + @field_validator("summary") + @classmethod + def validate_summary(cls, value: str) -> str: + return _required_text("summary", value, MAX_SCOPE_SUMMARY_LENGTH) + + @field_validator("parent_scope_id") + @classmethod + def validate_parent(cls, value: str | None) -> str | None: + return None if value is None else validate_scope_id(value) + + @field_validator("context_references") + @classmethod + def validate_context_references(cls, values: tuple[str, ...]) -> tuple[str, ...]: + normalized = tuple(validate_scope_id(value) for value in values) + if len(set(normalized)) != len(normalized): + raise ValueError("Context References must be unique") # noqa: TRY003 + return tuple(sorted(normalized)) + + @field_validator("external_references") + @classmethod + def validate_external_references( + cls, + values: tuple[ScopeExternalReference, ...], + ) -> tuple[ScopeExternalReference, ...]: + if len(set(values)) != len(values): + raise ValueError("external references must be unique") # noqa: TRY003 + return values + + @field_validator("idempotency_key") + @classmethod + def validate_idempotency_key(cls, value: str) -> str: + return _required_text("idempotency_key", value, MAX_SCOPE_IDEMPOTENCY_KEY_LENGTH) + + +class ScopeMutation(_ScopeValue): + expected_version: StrictInt = Field(ge=1) + title: str + summary: str + parent_scope_id: str | None = None + context_references: tuple[str, ...] = () + external_references: tuple[ScopeExternalReference, ...] = () + + @field_validator("title") + @classmethod + def validate_title(cls, value: str) -> str: + return _required_text("title", value, MAX_SCOPE_TITLE_LENGTH) + + @field_validator("summary") + @classmethod + def validate_summary(cls, value: str) -> str: + return _required_text("summary", value, MAX_SCOPE_SUMMARY_LENGTH) + + @field_validator("parent_scope_id") + @classmethod + def validate_parent(cls, value: str | None) -> str | None: + return None if value is None else validate_scope_id(value) + + @field_validator("context_references") + @classmethod + def validate_context_references(cls, values: tuple[str, ...]) -> tuple[str, ...]: + normalized = tuple(validate_scope_id(value) for value in values) + if len(set(normalized)) != len(normalized): + raise ValueError("Context References must be unique") # noqa: TRY003 + return tuple(sorted(normalized)) + + @field_validator("external_references") + @classmethod + def validate_external_references( + cls, + values: tuple[ScopeExternalReference, ...], + ) -> tuple[ScopeExternalReference, ...]: + if len(set(values)) != len(values): + raise ValueError("external references must be unique") # noqa: TRY003 + return values + + +class ScopeDescriptor(_ScopeValue): + scope_id: str + title: str + summary: str + parent_scope_id: str | None = None + context_references: tuple[str, ...] = () + external_references: tuple[ScopeExternalReference, ...] = () + version: StrictInt = Field(ge=1) + + @field_validator("scope_id") + @classmethod + def validate_scope_id(cls, value: str) -> str: + return validate_scope_id(value) + + +class ScopeBindingKey(_ScopeValue): + integration: str + kind: str + external_id: str + + @field_validator("integration") + @classmethod + def validate_integration(cls, value: str) -> str: + return _required_text("integration", value, MAX_SCOPE_BINDING_INTEGRATION_LENGTH) + + @field_validator("kind") + @classmethod + def validate_kind(cls, value: str) -> str: + return _required_text("kind", value, MAX_SCOPE_BINDING_KIND_LENGTH) + + @field_validator("external_id") + @classmethod + def validate_external_id(cls, value: str) -> str: + return _required_text("external_id", value, MAX_SCOPE_BINDING_EXTERNAL_ID_LENGTH) + + +class ScopeBinding(_ScopeValue): + key: ScopeBindingKey + scope_id: str + + @field_validator("scope_id") + @classmethod + def validate_scope_id(cls, value: str) -> str: + return validate_scope_id(value) + + +class ScopeSelection(_ScopeValue): + mode: Literal["all", "exact", "subtree"] + scope_ids: tuple[str, ...] = () + root_scope_id: str | None = None + + @field_validator("scope_ids") + @classmethod + def validate_scope_ids(cls, values: tuple[str, ...]) -> tuple[str, ...]: + normalized = tuple(validate_scope_id(value) for value in values) + if len(set(normalized)) != len(normalized): + raise ValueError("exact Scope selection must be unique") # noqa: TRY003 + return tuple(sorted(normalized)) + + @field_validator("root_scope_id") + @classmethod + def validate_root_scope_id(cls, value: str | None) -> str | None: + return None if value is None else validate_scope_id(value) + + @model_validator(mode="after") + def validate_shape(self) -> ScopeSelection: + if self.mode == "all" and (self.scope_ids or self.root_scope_id is not None): + raise ValueError("all selection accepts no Scope arguments") # noqa: TRY003 + if self.mode == "exact" and (not self.scope_ids or self.root_scope_id is not None): + raise ValueError("exact selection requires scope_ids only") # noqa: TRY003 + if self.mode == "subtree" and (self.root_scope_id is None or self.scope_ids): + raise ValueError("subtree selection requires root_scope_id only") # noqa: TRY003 + return self + + @model_serializer(mode="plain") + def serialize(self) -> dict[str, object]: + if self.mode == "exact": + return {"mode": self.mode, "scope_ids": self.scope_ids} + if self.mode == "subtree": + return {"mode": self.mode, "root_scope_id": self.root_scope_id} + return {"mode": self.mode} + + +def _required_text(field: str, value: str, maximum: int) -> str: + if not value.strip() or value != value.strip(): + raise ValueError(f"{field} must be non-empty without surrounding whitespace") # noqa: TRY003 + if len(value) > maximum: + raise ValueError(f"{field} must not exceed {maximum} characters") # noqa: TRY003 + return value diff --git a/src/powercontext/builtin/scope/repository.py b/src/powercontext/builtin/scope/repository.py new file mode 100644 index 000000000..f1e7f2008 --- /dev/null +++ b/src/powercontext/builtin/scope/repository.py @@ -0,0 +1,289 @@ +# Copyright (c) 2026 OceanBase. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +"""Relational persistence for durable Scope organization.""" + +from __future__ import annotations + +from collections import defaultdict +from hashlib import sha256 + +from sqlalchemy import delete, insert, select, update +from sqlalchemy.ext.asyncio import AsyncConnection + +from powercontext.builtin.persistence.tables import ( + SCOPE_BINDINGS_TABLE, + SCOPE_CONTEXT_REFERENCES_TABLE, + SCOPE_CREATION_REQUESTS_TABLE, + SCOPE_EXTERNAL_REFERENCES_TABLE, + SCOPE_SETTINGS_TABLE, + SCOPES_TABLE, +) +from powercontext.builtin.scope.models import ( + ScopeBinding, + ScopeBindingKey, + ScopeDescriptor, + ScopeDraft, + ScopeExternalReference, + ScopeMutation, +) + +_DEFAULT_SETTING = "default" + + +class ScopeRepository: + async def get(self, connection: AsyncConnection, scope_id: str, /) -> ScopeDescriptor | None: + scopes = await self.get_many(connection, (scope_id,)) + return None if not scopes else scopes[0] + + async def get_many( + self, + connection: AsyncConnection, + scope_ids: tuple[str, ...], + /, + ) -> tuple[ScopeDescriptor, ...]: + if not scope_ids: + return () + return await self._load( + connection, + select(SCOPES_TABLE).where(SCOPES_TABLE.c.scope_id.in_(scope_ids)).order_by(SCOPES_TABLE.c.scope_id), + ) + + async def list(self, connection: AsyncConnection, /) -> tuple[ScopeDescriptor, ...]: + return await self._load(connection, select(SCOPES_TABLE).order_by(SCOPES_TABLE.c.scope_id)) + + async def _load(self, connection: AsyncConnection, statement, /) -> tuple[ScopeDescriptor, ...]: + rows = tuple((await connection.execute(statement)).mappings()) + scope_ids = tuple(str(row["scope_id"]) for row in rows) + if not scope_ids: + return () + context_references: dict[str, list[str]] = defaultdict(list) + for row in await connection.execute( + select( + SCOPE_CONTEXT_REFERENCES_TABLE.c.scope_id, + SCOPE_CONTEXT_REFERENCES_TABLE.c.referenced_scope_id, + ) + .where(SCOPE_CONTEXT_REFERENCES_TABLE.c.scope_id.in_(scope_ids)) + .order_by( + SCOPE_CONTEXT_REFERENCES_TABLE.c.scope_id, + SCOPE_CONTEXT_REFERENCES_TABLE.c.referenced_scope_id, + ) + ): + context_references[str(row.scope_id)].append(str(row.referenced_scope_id)) + external_references: dict[str, list[ScopeExternalReference]] = defaultdict(list) + for row in await connection.execute( + select( + SCOPE_EXTERNAL_REFERENCES_TABLE.c.scope_id, + SCOPE_EXTERNAL_REFERENCES_TABLE.c.kind, + SCOPE_EXTERNAL_REFERENCES_TABLE.c.value, + ) + .where(SCOPE_EXTERNAL_REFERENCES_TABLE.c.scope_id.in_(scope_ids)) + .order_by( + SCOPE_EXTERNAL_REFERENCES_TABLE.c.scope_id, + SCOPE_EXTERNAL_REFERENCES_TABLE.c.ordinal, + ) + ): + external_references[str(row.scope_id)].append( + ScopeExternalReference(kind=str(row.kind), value=str(row.value)) + ) + return tuple( + ScopeDescriptor( + scope_id=scope_id, + title=str(row["title"]), + summary=str(row["summary"]), + parent_scope_id=None if row["parent_scope_id"] is None else str(row["parent_scope_id"]), + context_references=tuple(context_references[scope_id]), + external_references=tuple(external_references[scope_id]), + version=int(row["version"]), + ) + for row, scope_id in zip(rows, scope_ids, strict=True) + ) + + async def creation(self, connection: AsyncConnection, idempotency_key: str, /) -> tuple[str, str] | None: + row = ( + await connection.execute( + select( + SCOPE_CREATION_REQUESTS_TABLE.c.request_digest, + SCOPE_CREATION_REQUESTS_TABLE.c.scope_id, + ).where(SCOPE_CREATION_REQUESTS_TABLE.c.idempotency_key == idempotency_key) + ) + ).one_or_none() + return None if row is None else (str(row.request_digest), str(row.scope_id)) + + async def add( + self, + connection: AsyncConnection, + scope_id: str, + draft: ScopeDraft, + request_digest: str, + /, + ) -> ScopeDescriptor: + await connection.execute( + insert(SCOPES_TABLE).values( + scope_id=scope_id, + title=draft.title, + summary=draft.summary, + parent_scope_id=draft.parent_scope_id, + version=1, + ) + ) + await self._replace_relationships( + connection, + scope_id, + draft.context_references, + draft.external_references, + ) + await connection.execute( + insert(SCOPE_CREATION_REQUESTS_TABLE).values( + idempotency_key=draft.idempotency_key, + request_digest=request_digest, + scope_id=scope_id, + ) + ) + created = await self.get(connection, scope_id) + if created is None: + raise AssertionError + return created + + async def replace( + self, + connection: AsyncConnection, + scope_id: str, + mutation: ScopeMutation, + /, + ) -> bool: + result = await connection.execute( + update(SCOPES_TABLE) + .where( + SCOPES_TABLE.c.scope_id == scope_id, + SCOPES_TABLE.c.version == mutation.expected_version, + ) + .values( + title=mutation.title, + summary=mutation.summary, + parent_scope_id=mutation.parent_scope_id, + version=mutation.expected_version + 1, + ) + ) + if result.rowcount != 1: + return False + await self._replace_relationships( + connection, + scope_id, + mutation.context_references, + mutation.external_references, + ) + return True + + async def default_scope_id(self, connection: AsyncConnection, /) -> str | None: + value = ( + await connection.execute( + select(SCOPE_SETTINGS_TABLE.c.scope_id).where(SCOPE_SETTINGS_TABLE.c.name == _DEFAULT_SETTING) + ) + ).scalar_one_or_none() + return None if value is None else str(value) + + async def set_default(self, connection: AsyncConnection, scope_id: str, /) -> None: + result = await connection.execute( + update(SCOPE_SETTINGS_TABLE) + .where(SCOPE_SETTINGS_TABLE.c.name == _DEFAULT_SETTING) + .values(scope_id=scope_id) + ) + if result.rowcount == 0: + await connection.execute(insert(SCOPE_SETTINGS_TABLE).values(name=_DEFAULT_SETTING, scope_id=scope_id)) + + async def binding(self, connection: AsyncConnection, key: ScopeBindingKey, /) -> ScopeBinding | None: + value = ( + await connection.execute( + select(SCOPE_BINDINGS_TABLE.c.scope_id).where( + SCOPE_BINDINGS_TABLE.c.integration == key.integration, + SCOPE_BINDINGS_TABLE.c.kind == key.kind, + SCOPE_BINDINGS_TABLE.c.external_id == key.external_id, + ) + ) + ).scalar_one_or_none() + return None if value is None else ScopeBinding(key=key, scope_id=str(value)) + + async def set_binding( + self, + connection: AsyncConnection, + key: ScopeBindingKey, + scope_id: str, + /, + ) -> ScopeBinding: + result = await connection.execute( + update(SCOPE_BINDINGS_TABLE) + .where( + SCOPE_BINDINGS_TABLE.c.integration == key.integration, + SCOPE_BINDINGS_TABLE.c.kind == key.kind, + SCOPE_BINDINGS_TABLE.c.external_id == key.external_id, + ) + .values(scope_id=scope_id) + ) + if result.rowcount == 0: + await connection.execute( + insert(SCOPE_BINDINGS_TABLE).values( + integration=key.integration, + kind=key.kind, + external_id=key.external_id, + scope_id=scope_id, + ) + ) + return ScopeBinding(key=key, scope_id=scope_id) + + async def clear_binding(self, connection: AsyncConnection, key: ScopeBindingKey, /) -> bool: + result = await connection.execute( + delete(SCOPE_BINDINGS_TABLE).where( + SCOPE_BINDINGS_TABLE.c.integration == key.integration, + SCOPE_BINDINGS_TABLE.c.kind == key.kind, + SCOPE_BINDINGS_TABLE.c.external_id == key.external_id, + ) + ) + return result.rowcount == 1 + + async def _replace_relationships( + self, + connection: AsyncConnection, + scope_id: str, + context_references: tuple[str, ...], + external_references: tuple[ScopeExternalReference, ...], + ) -> None: + await connection.execute( + delete(SCOPE_CONTEXT_REFERENCES_TABLE).where(SCOPE_CONTEXT_REFERENCES_TABLE.c.scope_id == scope_id) + ) + if context_references: + await connection.execute( + insert(SCOPE_CONTEXT_REFERENCES_TABLE), + [ + {"scope_id": scope_id, "referenced_scope_id": referenced_scope_id} + for referenced_scope_id in context_references + ], + ) + await connection.execute( + delete(SCOPE_EXTERNAL_REFERENCES_TABLE).where(SCOPE_EXTERNAL_REFERENCES_TABLE.c.scope_id == scope_id) + ) + if external_references: + await connection.execute( + insert(SCOPE_EXTERNAL_REFERENCES_TABLE), + [ + { + "scope_id": scope_id, + "ordinal": ordinal, + "kind": reference.kind, + "value": reference.value, + "value_digest": sha256(reference.value.encode()).hexdigest(), + } + for ordinal, reference in enumerate(external_references) + ], + ) diff --git a/src/powercontext/limits.py b/src/powercontext/limits.py index f71ed0fe2..5550c3507 100644 --- a/src/powercontext/limits.py +++ b/src/powercontext/limits.py @@ -15,6 +15,14 @@ """Shared identity limits that remain safe for utf8mb4 relational indexes.""" MAX_SCOPE_ID_LENGTH = 256 +MAX_SCOPE_TITLE_LENGTH = 256 +MAX_SCOPE_SUMMARY_LENGTH = 2_000 +MAX_SCOPE_EXTERNAL_REFERENCE_KIND_LENGTH = 128 +MAX_SCOPE_EXTERNAL_REFERENCE_VALUE_LENGTH = 2_000 +MAX_SCOPE_IDEMPOTENCY_KEY_LENGTH = 256 +MAX_SCOPE_BINDING_INTEGRATION_LENGTH = 128 +MAX_SCOPE_BINDING_KIND_LENGTH = 64 +MAX_SCOPE_BINDING_EXTERNAL_ID_LENGTH = 256 MAX_SOURCE_ID_LENGTH = 256 MAX_SOURCE_TYPE_LENGTH = 128 MAX_ARTIFACT_FAMILY_LENGTH = 128 diff --git a/tests/builtin/test_scope_application.py b/tests/builtin/test_scope_application.py new file mode 100644 index 000000000..a56c5735a --- /dev/null +++ b/tests/builtin/test_scope_application.py @@ -0,0 +1,238 @@ +# Copyright (c) 2026 OceanBase. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +from __future__ import annotations + +import asyncio +import re + +import pytest + +from powercontext.builtin.persistence.sqlite import SQLiteConfig, SQLiteProfile +from powercontext.builtin.persistence.tables import BUILTIN_TABLES +from powercontext.builtin.scope import ( + ScopeApplication, + ScopeBindingKey, + ScopeBindingNotFoundError, + ScopeDraft, + ScopeIdempotencyConflictError, + ScopeMutation, + ScopeRelationshipError, + ScopeSelection, +) + + +def test_scope_bootstrap_creates_one_ordinary_default() -> None: + async def scenario() -> None: + async with SQLiteProfile.open(SQLiteConfig(), tables=BUILTIN_TABLES) as profile: + scopes = ScopeApplication(profile.database) + + first = await scopes.bootstrap_default() + second = await scopes.bootstrap_default() + + assert first == second + assert re.fullmatch(r"scp_[0-7][0-9a-hjkmnp-tv-z]{25}", first.scope_id) + assert first.parent_scope_id is None + assert first.context_references == () + assert await scopes.list() == (first,) + + asyncio.run(scenario()) + + +def test_scope_creation_is_idempotent_but_not_ambiguous() -> None: + async def scenario() -> None: + async with SQLiteProfile.open(SQLiteConfig(), tables=BUILTIN_TABLES) as profile: + scopes = ScopeApplication(profile.database) + draft = ScopeDraft(title="Feature", summary="Implement search", idempotency_key="feature-search") + + assert await scopes.create(draft) == await scopes.create(draft) + with pytest.raises(ScopeIdempotencyConflictError): + await scopes.create( + ScopeDraft(title="Feature", summary="Different work", idempotency_key="feature-search") + ) + + asyncio.run(scenario()) + + +def test_concurrent_scope_creation_returns_one_scope(tmp_path) -> None: + async def scenario() -> None: + config = SQLiteConfig(url=f"sqlite+aiosqlite:///{tmp_path / 'runtime.db'}") + async with SQLiteProfile.open(config, tables=BUILTIN_TABLES) as profile: + scopes = ScopeApplication(profile.database) + draft = ScopeDraft(title="Feature", summary="Concurrent creation", idempotency_key="concurrent") + + created = await asyncio.gather(*(scopes.create(draft) for _ in range(8))) + + assert len({scope.scope_id for scope in created}) == 1 + + asyncio.run(scenario()) + + +def test_parent_organizes_without_sharing_and_cannot_form_a_cycle() -> None: + async def scenario() -> None: + async with SQLiteProfile.open(SQLiteConfig(), tables=BUILTIN_TABLES) as profile: + scopes = ScopeApplication(profile.database) + root = await scopes.create(ScopeDraft(title="Root", summary="Root result", idempotency_key="root")) + child = await scopes.create( + ScopeDraft( + title="Child", + summary="Independent result", + parent_scope_id=root.scope_id, + idempotency_key="child", + ) + ) + + assert child.context_references == () + with pytest.raises(ScopeRelationshipError, match="acyclic"): + await scopes.update( + root.scope_id, + ScopeMutation( + expected_version=root.version, + title=root.title, + summary=root.summary, + parent_scope_id=child.scope_id, + ), + ) + + asyncio.run(scenario()) + + +def test_concurrent_parent_updates_cannot_form_a_cycle() -> None: + async def scenario() -> None: + async with SQLiteProfile.open(SQLiteConfig(), tables=BUILTIN_TABLES) as profile: + scopes = ScopeApplication(profile.database) + left = await scopes.create(ScopeDraft(title="Left", summary="Left", idempotency_key="left")) + right = await scopes.create(ScopeDraft(title="Right", summary="Right", idempotency_key="right")) + + updates = await asyncio.gather( + scopes.update( + left.scope_id, + ScopeMutation( + expected_version=left.version, + title=left.title, + summary=left.summary, + parent_scope_id=right.scope_id, + ), + ), + scopes.update( + right.scope_id, + ScopeMutation( + expected_version=right.version, + title=right.title, + summary=right.summary, + parent_scope_id=left.scope_id, + ), + ), + return_exceptions=True, + ) + + assert sum(isinstance(result, ScopeRelationshipError) for result in updates) == 1 + + asyncio.run(scenario()) + + +def test_context_reference_order_does_not_change_scope_creation() -> None: + async def scenario() -> None: + async with SQLiteProfile.open(SQLiteConfig(), tables=BUILTIN_TABLES) as profile: + scopes = ScopeApplication(profile.database) + shared = await scopes.create(ScopeDraft(title="Shared", summary="Shared facts", idempotency_key="shared")) + middle = await scopes.create( + ScopeDraft( + title="Middle", + summary="Direct reader", + context_references=(shared.scope_id,), + idempotency_key="middle", + ) + ) + current = await scopes.create( + ScopeDraft( + title="Current", + summary="Reads only Middle", + context_references=(middle.scope_id, shared.scope_id), + idempotency_key="current", + ) + ) + + assert current.context_references == tuple(sorted((middle.scope_id, shared.scope_id))) + assert ( + await scopes.create( + ScopeDraft( + title="Current", + summary="Reads only Middle", + context_references=(shared.scope_id, middle.scope_id), + idempotency_key="current", + ) + ) + == current + ) + + asyncio.run(scenario()) + + +def test_exact_selection_is_a_canonical_set() -> None: + async def scenario() -> None: + async with SQLiteProfile.open(SQLiteConfig(), tables=BUILTIN_TABLES) as profile: + scopes = ScopeApplication(profile.database) + left = await scopes.create(ScopeDraft(title="Left", summary="Left", idempotency_key="left")) + right = await scopes.create(ScopeDraft(title="Right", summary="Right", idempotency_key="right")) + + first = ScopeSelection(mode="exact", scope_ids=(left.scope_id, right.scope_id)) + second = ScopeSelection(mode="exact", scope_ids=(right.scope_id, left.scope_id)) + + assert first == second + assert await scopes.resolve_selection(first) == await scopes.resolve_selection(second) + + asyncio.run(scenario()) + + +def test_binding_resolution_uses_explicit_durable_then_default_precedence() -> None: + async def scenario() -> None: + async with SQLiteProfile.open(SQLiteConfig(), tables=BUILTIN_TABLES) as profile: + scopes = ScopeApplication(profile.database) + default = await scopes.bootstrap_default() + durable = await scopes.create( + ScopeDraft(title="Durable", summary="Durable binding", idempotency_key="durable") + ) + explicit = await scopes.create( + ScopeDraft(title="Explicit", summary="Explicit binding", idempotency_key="explicit") + ) + missing_key = ScopeBindingKey(integration="codex", kind="session", external_id="missing") + durable_key = ScopeBindingKey(integration="codex", kind="workspace", external_id="workspace") + await scopes.bind(durable_key, durable.scope_id) + + assert ( + await scopes.resolve_binding( + explicit_scope_id=explicit.scope_id, + binding_keys=(durable_key,), + ) + == explicit + ) + assert await scopes.resolve_binding(binding_keys=(missing_key, durable_key)) == durable + assert await scopes.resolve_binding(binding_keys=(missing_key,)) == default + + await scopes.clear_binding(durable_key) + assert await scopes.resolve_binding(binding_keys=(durable_key,)) == default + + asyncio.run(scenario()) + + +def test_binding_resolution_fails_without_any_binding() -> None: + async def scenario() -> None: + async with SQLiteProfile.open(SQLiteConfig(), tables=BUILTIN_TABLES) as profile: + scopes = ScopeApplication(profile.database) + + with pytest.raises(ScopeBindingNotFoundError): + await scopes.resolve_binding() + + asyncio.run(scenario()) From a1d0fb0f6d97fb1e52a5df8007ee56d5316cc78b Mon Sep 17 00:00:00 2001 From: Chojan Shang Date: Wed, 2 Sep 2026 15:27:35 +0800 Subject: [PATCH 02/17] feat(migration): register existing runtime scopes --- src/powercontext/builtin/scope/application.py | 13 +++++ src/powercontext/builtin/scope/repository.py | 50 ++++++++++++++++++- tests/builtin/test_scope_application.py | 29 ++++++++++- 3 files changed, 90 insertions(+), 2 deletions(-) diff --git a/src/powercontext/builtin/scope/application.py b/src/powercontext/builtin/scope/application.py index 34b406734..6c68451bd 100644 --- a/src/powercontext/builtin/scope/application.py +++ b/src/powercontext/builtin/scope/application.py @@ -62,6 +62,9 @@ async def bootstrap_default(self) -> ScopeDescriptor: existing = await self.default_scope() if existing is not None: return existing + scopes = await self.list() + if len(scopes) == 1: + return await self.set_default(scopes[0].scope_id) created = await self.create( ScopeDraft( title="Default", @@ -72,6 +75,16 @@ async def bootstrap_default(self) -> ScopeDescriptor: await self.set_default(created.scope_id) return created + async def register_existing(self) -> tuple[ScopeDescriptor, ...]: + """Register Scope identities already present in durable runtime data.""" + + async with self._write_lock, self._database.transaction() as connection: + scope_ids = await self._repository.unregistered_runtime_scope_ids(connection) + registered = [] + for scope_id in scope_ids: + registered.append(await self._repository.register_existing(connection, scope_id)) + return tuple(registered) + async def create(self, draft: ScopeDraft, /) -> ScopeDescriptor: async with self._write_lock: return await self._create(draft) diff --git a/src/powercontext/builtin/scope/repository.py b/src/powercontext/builtin/scope/repository.py index f1e7f2008..765610ed4 100644 --- a/src/powercontext/builtin/scope/repository.py +++ b/src/powercontext/builtin/scope/repository.py @@ -19,16 +19,24 @@ from collections import defaultdict from hashlib import sha256 -from sqlalchemy import delete, insert, select, update +from sqlalchemy import delete, insert, select, union, update from sqlalchemy.ext.asyncio import AsyncConnection from powercontext.builtin.persistence.tables import ( + ARTIFACT_CANDIDATE_VERSIONS_TABLE, + ARTIFACTS_TABLE, + EXTERNAL_SKILL_REGISTRATIONS_TABLE, + MODEL_USAGE_DAILY_TABLE, + RECALL_TOKEN_DAILY_TABLE, SCOPE_BINDINGS_TABLE, SCOPE_CONTEXT_REFERENCES_TABLE, SCOPE_CREATION_REQUESTS_TABLE, SCOPE_EXTERNAL_REFERENCES_TABLE, SCOPE_SETTINGS_TABLE, SCOPES_TABLE, + SOURCE_CURSORS_TABLE, + SOURCE_JOURNAL_HEADS_TABLE, + SOURCES_TABLE, ) from powercontext.builtin.scope.models import ( ScopeBinding, @@ -40,9 +48,49 @@ ) _DEFAULT_SETTING = "default" +_RUNTIME_SCOPE_TABLES = ( + SOURCES_TABLE, + SOURCE_JOURNAL_HEADS_TABLE, + ARTIFACTS_TABLE, + ARTIFACT_CANDIDATE_VERSIONS_TABLE, + SOURCE_CURSORS_TABLE, + EXTERNAL_SKILL_REGISTRATIONS_TABLE, + MODEL_USAGE_DAILY_TABLE, + RECALL_TOKEN_DAILY_TABLE, +) class ScopeRepository: + async def unregistered_runtime_scope_ids(self, connection: AsyncConnection, /) -> tuple[str, ...]: + discovered = union(*(select(table.c.scope_id) for table in _RUNTIME_SCOPE_TABLES)).subquery() + values = await connection.execute( + select(discovered.c.scope_id) + .outerjoin(SCOPES_TABLE, SCOPES_TABLE.c.scope_id == discovered.c.scope_id) + .where(SCOPES_TABLE.c.scope_id.is_(None)) + .order_by(discovered.c.scope_id) + ) + return tuple(str(scope_id) for scope_id in values.scalars()) + + async def register_existing( + self, + connection: AsyncConnection, + scope_id: str, + /, + ) -> ScopeDescriptor: + await connection.execute( + insert(SCOPES_TABLE).values( + scope_id=scope_id, + title=scope_id, + summary="Registered from existing runtime data.", + parent_scope_id=None, + version=1, + ) + ) + registered = await self.get(connection, scope_id) + if registered is None: + raise AssertionError + return registered + async def get(self, connection: AsyncConnection, scope_id: str, /) -> ScopeDescriptor | None: scopes = await self.get_many(connection, (scope_id,)) return None if not scopes else scopes[0] diff --git a/tests/builtin/test_scope_application.py b/tests/builtin/test_scope_application.py index a56c5735a..c6ccef741 100644 --- a/tests/builtin/test_scope_application.py +++ b/tests/builtin/test_scope_application.py @@ -20,7 +20,7 @@ import pytest from powercontext.builtin.persistence.sqlite import SQLiteConfig, SQLiteProfile -from powercontext.builtin.persistence.tables import BUILTIN_TABLES +from powercontext.builtin.persistence.tables import BUILTIN_TABLES, SOURCES_TABLE from powercontext.builtin.scope import ( ScopeApplication, ScopeBindingKey, @@ -50,6 +50,33 @@ async def scenario() -> None: asyncio.run(scenario()) +def test_existing_runtime_scope_is_registered_and_reused_as_default() -> None: + async def scenario() -> None: + async with SQLiteProfile.open(SQLiteConfig(), tables=BUILTIN_TABLES) as profile: + async with profile.database.transaction() as connection: + await connection.execute( + SOURCES_TABLE.insert().values( + scope_id="legacy-scope", + source_type="text", + source_id="source-1", + payload=b"existing", + journal_position=1, + ) + ) + scopes = ScopeApplication(profile.database) + + registered = await scopes.register_existing() + default = await scopes.bootstrap_default() + + assert tuple(scope.scope_id for scope in registered) == ("legacy-scope",) + assert await scopes.register_existing() == () + assert default.scope_id == "legacy-scope" + assert default.title == "legacy-scope" + assert default.summary == "Registered from existing runtime data." + + asyncio.run(scenario()) + + def test_scope_creation_is_idempotent_but_not_ambiguous() -> None: async def scenario() -> None: async with SQLiteProfile.open(SQLiteConfig(), tables=BUILTIN_TABLES) as profile: From 99e4088ac13637913da05273c4718605e4255bcb Mon Sep 17 00:00:00 2001 From: Chojan Shang Date: Wed, 2 Sep 2026 15:32:56 +0800 Subject: [PATCH 03/17] feat(artifact): publish exact revisions across scopes --- src/powercontext/__init__.py | 2 + src/powercontext/artifacts/__init__.py | 3 +- src/powercontext/artifacts/models.py | 28 ++- .../builtin/persistence/artifacts.py | 97 ++++++++ .../builtin/persistence/errors.py | 9 + .../builtin/persistence/tables.py | 38 +++ src/powercontext/builtin/publication.py | 221 ++++++++++++++++++ tests/builtin/test_publication.py | 138 +++++++++++ 8 files changed, 534 insertions(+), 2 deletions(-) create mode 100644 src/powercontext/builtin/publication.py create mode 100644 tests/builtin/test_publication.py diff --git a/src/powercontext/__init__.py b/src/powercontext/__init__.py index 9ae96033b..c22b37893 100644 --- a/src/powercontext/__init__.py +++ b/src/powercontext/__init__.py @@ -16,6 +16,7 @@ from powercontext.artifacts import ( Artifact, + ArtifactAddress, ArtifactCatalog, ArtifactDraft, ArtifactLineage, @@ -52,6 +53,7 @@ __all__ = [ "Artifact", + "ArtifactAddress", "ArtifactCatalog", "ArtifactDraft", "ArtifactError", diff --git a/src/powercontext/artifacts/__init__.py b/src/powercontext/artifacts/__init__.py index a68c0c2b9..fff5989b0 100644 --- a/src/powercontext/artifacts/__init__.py +++ b/src/powercontext/artifacts/__init__.py @@ -14,11 +14,12 @@ """Immutable artifacts and their read-only catalog contract.""" -from powercontext.artifacts.models import Artifact, ArtifactDraft, ArtifactLineage, ArtifactRef +from powercontext.artifacts.models import Artifact, ArtifactAddress, ArtifactDraft, ArtifactLineage, ArtifactRef from powercontext.artifacts.protocols import ArtifactCatalog, ArtifactStore __all__ = [ "Artifact", + "ArtifactAddress", "ArtifactCatalog", "ArtifactDraft", "ArtifactLineage", diff --git a/src/powercontext/artifacts/models.py b/src/powercontext/artifacts/models.py index 3451feb94..a151107d1 100644 --- a/src/powercontext/artifacts/models.py +++ b/src/powercontext/artifacts/models.py @@ -21,7 +21,7 @@ from pydantic import BaseModel, Field, StrictInt, field_validator, model_validator from powercontext.errors import InvalidArtifactReferenceError -from powercontext.limits import MAX_ARTIFACT_FAMILY_LENGTH, MAX_ARTIFACT_ID_LENGTH +from powercontext.limits import MAX_ARTIFACT_FAMILY_LENGTH, MAX_ARTIFACT_ID_LENGTH, MAX_SCOPE_ID_LENGTH from powercontext.sources.models import SourceRef ContentT = TypeVar("ContentT", covariant=True) @@ -44,11 +44,37 @@ def validate_identity(cls, value: str, info) -> str: return value +class ArtifactAddress(BaseModel): + """A complete address for one exact Artifact revision across Scope boundaries.""" + + scope_id: str + artifact: ArtifactRef + + @field_validator("scope_id") + @classmethod + def validate_scope_id(cls, value: str) -> str: + _validate_reference_part("scope_id", value) + if len(value) > MAX_SCOPE_ID_LENGTH: + raise InvalidArtifactReferenceError( + "scope_id", + f"must not exceed {MAX_SCOPE_ID_LENGTH} characters", + ) + return value + + class ArtifactLineage(BaseModel): """The direct evidence used to produce one artifact revision.""" sources: tuple[SourceRef, ...] = () artifacts: tuple[ArtifactRef, ...] = () + publication_source: ArtifactAddress | None = None + publication_digest: str | None = None + + @model_validator(mode="after") + def require_complete_publication_provenance(self): + if (self.publication_source is None) != (self.publication_digest is None): + raise ValueError("publication source and digest must be provided together") # noqa: TRY003 + return self class ArtifactDraft(BaseModel, Generic[ContentT]): diff --git a/src/powercontext/builtin/persistence/artifacts.py b/src/powercontext/builtin/persistence/artifacts.py index 0e65140df..0e8fd1ec7 100644 --- a/src/powercontext/builtin/persistence/artifacts.py +++ b/src/powercontext/builtin/persistence/artifacts.py @@ -26,6 +26,7 @@ from powercontext.artifacts import ( Artifact, + ArtifactAddress, ArtifactDraft, ArtifactLineage, ArtifactRef, @@ -33,6 +34,7 @@ from powercontext.builtin.persistence.codec import dump_model, load_model, stored_bytes from powercontext.builtin.persistence.errors import ( IdentityMismatchError, + InvalidPublicationLineageError, InvalidRepositoryArgumentError, RepositoryNotFoundError, ) @@ -40,6 +42,7 @@ ARTIFACT_HEADS_TABLE, ARTIFACT_LINEAGE_ARTIFACTS_TABLE, ARTIFACT_LINEAGE_SOURCES_TABLE, + ARTIFACT_PUBLICATIONS_TABLE, ARTIFACTS_TABLE, ) from powercontext.errors import ( @@ -240,6 +243,42 @@ async def revisions( revisions.append(await self._decode_row(connection, row)) return tuple(revisions) + async def copy_exact( + self, + connection: AsyncConnection, + target_scope_id: str, + target_artifact_id: str, + source_address: ArtifactAddress, + source: Artifact[Any], + content_digest: str, + /, + ) -> Artifact[Any]: + """Create an independent target lifecycle from one exact source revision.""" + + _require_scope(target_scope_id) + artifact_type = self._artifact_type(source.family) + ref = ArtifactRef(family=source.family, artifact_id=target_artifact_id, revision=1) + copied = await self._insert_revision( + connection, + target_scope_id, + artifact_type, + ref, + source.content, + ArtifactLineage( + publication_source=source.lineage.publication_source or source_address, + publication_digest=source.lineage.publication_digest or content_digest, + ), + ) + await connection.execute( + insert(ARTIFACT_HEADS_TABLE).values( + scope_id=target_scope_id, + family=ref.family, + artifact_id=ref.artifact_id, + revision=ref.revision, + ) + ) + return copied + async def _insert_revision( self, connection: AsyncConnection, @@ -370,6 +409,10 @@ async def _load_lineage( .order_by(ARTIFACT_LINEAGE_ARTIFACTS_TABLE.c.ordinal) ) ).all() + publication_source, publication_digest = await self._load_publication_provenance( + connection, + ArtifactAddress(scope_id=scope_id, artifact=ref), + ) return ArtifactLineage( sources=tuple(SourceRef(source_type=str(row.source_type), source_id=str(row.source_id)) for row in sources), artifacts=tuple( @@ -380,8 +423,62 @@ async def _load_lineage( ) for row in artifacts ), + publication_source=publication_source, + publication_digest=publication_digest, ) + async def _load_publication_provenance( + self, + connection: AsyncConnection, + target: ArtifactAddress, + ) -> tuple[ArtifactAddress | None, str | None]: + """Resolve a publication chain to the Scope that owns the original revision.""" + + current = target + digest: str | None = None + visited: set[tuple[str, str, str, int]] = set() + while True: + key = ( + current.scope_id, + current.artifact.family, + current.artifact.artifact_id, + current.artifact.revision, + ) + if key in visited: + raise InvalidPublicationLineageError("cycle") + visited.add(key) + + publication = ( + ( + await connection.execute( + select(ARTIFACT_PUBLICATIONS_TABLE).where( + ARTIFACT_PUBLICATIONS_TABLE.c.target_scope_id == current.scope_id, + ARTIFACT_PUBLICATIONS_TABLE.c.target_family == current.artifact.family, + ARTIFACT_PUBLICATIONS_TABLE.c.target_artifact_id == current.artifact.artifact_id, + ARTIFACT_PUBLICATIONS_TABLE.c.target_revision == current.artifact.revision, + ) + ) + ) + .mappings() + .one_or_none() + ) + if publication is None: + return (None, None) if digest is None else (current, digest) + + current_digest = str(publication["content_digest"]) + if digest is None: + digest = current_digest + elif digest != current_digest: + raise InvalidPublicationLineageError("digest") + current = ArtifactAddress( + scope_id=str(publication["source_scope_id"]), + artifact=ArtifactRef( + family=str(publication["source_family"]), + artifact_id=str(publication["source_artifact_id"]), + revision=int(publication["source_revision"]), + ), + ) + async def _head_conflict( self, connection: AsyncConnection, diff --git a/src/powercontext/builtin/persistence/errors.py b/src/powercontext/builtin/persistence/errors.py index 8c76e2023..d729fd85a 100644 --- a/src/powercontext/builtin/persistence/errors.py +++ b/src/powercontext/builtin/persistence/errors.py @@ -88,6 +88,15 @@ def __init__(self, column: str, expected: str) -> None: super().__init__(f"stored {column} column is not {expected}") +class InvalidPublicationLineageError(RepositoryError): + """Raised when persisted publication provenance cannot form one exact chain.""" + + def __init__(self, issue: str) -> None: + self.issue = issue + detail = "inconsistent content digests" if issue == "digest" else issue + super().__init__(f"invalid publication lineage: {detail}") + + class GenerationConflictError(RepositoryError): """Raised when Trigger State compare-and-swap observes another generation.""" diff --git a/src/powercontext/builtin/persistence/tables.py b/src/powercontext/builtin/persistence/tables.py index 5085d1561..716f53aee 100644 --- a/src/powercontext/builtin/persistence/tables.py +++ b/src/powercontext/builtin/persistence/tables.py @@ -270,6 +270,43 @@ def _entry_text_type(): ), ) +ARTIFACT_PUBLICATIONS_TABLE = Table( + "pc_artifact_publications", + SHARED_METADATA, + Column("target_scope_id", identity_string(MAX_SCOPE_ID_LENGTH), primary_key=True), + Column("target_family", identity_string(MAX_ARTIFACT_FAMILY_LENGTH), primary_key=True), + Column("target_artifact_id", identity_string(MAX_ARTIFACT_ID_LENGTH), primary_key=True), + Column("target_revision", Integer, primary_key=True), + Column("source_scope_id", identity_string(MAX_SCOPE_ID_LENGTH), nullable=False), + Column("source_family", identity_string(MAX_ARTIFACT_FAMILY_LENGTH), nullable=False), + Column("source_artifact_id", identity_string(MAX_ARTIFACT_ID_LENGTH), nullable=False), + Column("source_revision", Integer, nullable=False), + Column("content_digest", identity_string(64), nullable=False), + Column("idempotency_key", identity_string(MAX_SCOPE_IDEMPOTENCY_KEY_LENGTH), nullable=False), + ForeignKeyConstraint( + ("target_scope_id", "target_family", "target_artifact_id", "target_revision"), + ( + "pc_artifacts.scope_id", + "pc_artifacts.family", + "pc_artifacts.artifact_id", + "pc_artifacts.revision", + ), + ondelete="RESTRICT", + ), + ForeignKeyConstraint( + ("source_scope_id", "source_family", "source_artifact_id", "source_revision"), + ( + "pc_artifacts.scope_id", + "pc_artifacts.family", + "pc_artifacts.artifact_id", + "pc_artifacts.revision", + ), + ondelete="RESTRICT", + ), + UniqueConstraint("target_scope_id", "idempotency_key", name="uq_pc_artifact_publications_request"), +) + + ARTIFACT_CANDIDATE_VERSIONS_TABLE = Table( "pc_artifact_candidate_versions", SHARED_METADATA, @@ -438,6 +475,7 @@ def _entry_text_type(): ARTIFACT_HEADS_TABLE, ARTIFACT_LINEAGE_SOURCES_TABLE, ARTIFACT_LINEAGE_ARTIFACTS_TABLE, + ARTIFACT_PUBLICATIONS_TABLE, ARTIFACT_CANDIDATE_VERSIONS_TABLE, ARTIFACT_CANDIDATE_HEADS_TABLE, SOURCE_CURSORS_TABLE, diff --git a/src/powercontext/builtin/publication.py b/src/powercontext/builtin/publication.py new file mode 100644 index 000000000..8f5b7329f --- /dev/null +++ b/src/powercontext/builtin/publication.py @@ -0,0 +1,221 @@ +# Copyright (c) 2026 OceanBase. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +"""Exact Artifact delivery across Scope ownership boundaries.""" + +from __future__ import annotations + +import asyncio +import hashlib +import secrets +from collections.abc import Callable, Mapping +from typing import Any + +from pydantic import BaseModel, ConfigDict, field_validator, model_validator +from sqlalchemy import insert, select +from sqlalchemy.ext.asyncio import AsyncConnection + +from powercontext.artifacts import ArtifactAddress, ArtifactRef +from powercontext.builtin.persistence.artifacts import ArtifactRepository +from powercontext.builtin.persistence.codec import dump_model +from powercontext.builtin.persistence.database import AsyncDatabase +from powercontext.builtin.persistence.tables import ARTIFACT_PUBLICATIONS_TABLE +from powercontext.builtin.scope import ScopeApplication +from powercontext.errors import PowerContextError +from powercontext.limits import MAX_SCOPE_IDEMPOTENCY_KEY_LENGTH + +PublicationIdFactory = Callable[[], str] +_CROCKFORD = "0123456789abcdefghjkmnpqrstvwxyz" + + +class ArtifactPublicationRequest(BaseModel): + """Select one exact source revision for delivery into a target Scope.""" + + model_config = ConfigDict(extra="forbid", frozen=True) + + source: ArtifactAddress + target_scope_id: str + idempotency_key: str + + @field_validator("target_scope_id", "idempotency_key") + @classmethod + def validate_text(cls, value: str, info) -> str: + if not value.strip() or value != value.strip(): + raise ValueError(f"{info.field_name} must be non-empty and trimmed") # noqa: TRY003 + if info.field_name == "idempotency_key" and len(value) > MAX_SCOPE_IDEMPOTENCY_KEY_LENGTH: + raise ValueError( # noqa: TRY003 + f"idempotency_key must not exceed {MAX_SCOPE_IDEMPOTENCY_KEY_LENGTH} characters" + ) + return value + + @model_validator(mode="after") + def require_scope_boundary(self) -> ArtifactPublicationRequest: + if self.source.scope_id == self.target_scope_id: + raise ValueError("publication requires different source and target Scopes") # noqa: TRY003 + return self + + +class ArtifactPublication(BaseModel): + """The immutable source and target addresses created by one publication.""" + + model_config = ConfigDict(extra="forbid", frozen=True) + + source: ArtifactAddress + target: ArtifactAddress + content_digest: str + + +class ArtifactPublicationConflictError(PowerContextError, RuntimeError): + """Report reuse of an idempotency key for a different publication.""" + + +class ArtifactPublicationApplication: + def __init__( + self, + database: AsyncDatabase, + artifacts: ArtifactRepository, + scopes: ScopeApplication, + *, + id_factory: PublicationIdFactory | None = None, + ) -> None: + self._database = database + self._artifacts = artifacts + self._scopes = scopes + self._id_factory = generate_publication_artifact_id if id_factory is None else id_factory + self._write_lock = asyncio.Lock() + + async def publish(self, request: ArtifactPublicationRequest, /) -> ArtifactPublication: + async with self._write_lock: + return await self._publish(request) + + async def _publish(self, request: ArtifactPublicationRequest) -> ArtifactPublication: + await self._scopes.get(request.source.scope_id) + await self._scopes.get(request.target_scope_id) + async with self._database.transaction() as connection: + existing = await self._find_request(connection, request.target_scope_id, request.idempotency_key) + if existing is not None: + if existing.source != request.source: + raise ArtifactPublicationConflictError(request.idempotency_key) + return existing + + source = await self._artifacts.get(connection, request.source.scope_id, request.source.artifact) + content_digest = hashlib.sha256(dump_model(source.content, kind="artifact", name=source.family)).hexdigest() + target = await self._artifacts.copy_exact( + connection, + request.target_scope_id, + self._id_factory(), + request.source, + source, + content_digest, + ) + publication = ArtifactPublication( + source=request.source, + target=ArtifactAddress(scope_id=request.target_scope_id, artifact=target.as_ref()), + content_digest=content_digest, + ) + await connection.execute( + insert(ARTIFACT_PUBLICATIONS_TABLE).values( + **_publication_row(publication), + idempotency_key=request.idempotency_key, + ) + ) + return publication + + async def get(self, target: ArtifactAddress, /) -> ArtifactPublication | None: + async with self._database.transaction() as connection: + row = ( + ( + await connection.execute( + select(ARTIFACT_PUBLICATIONS_TABLE).where( + ARTIFACT_PUBLICATIONS_TABLE.c.target_scope_id == target.scope_id, + ARTIFACT_PUBLICATIONS_TABLE.c.target_family == target.artifact.family, + ARTIFACT_PUBLICATIONS_TABLE.c.target_artifact_id == target.artifact.artifact_id, + ARTIFACT_PUBLICATIONS_TABLE.c.target_revision == target.artifact.revision, + ) + ) + ) + .mappings() + .one_or_none() + ) + return None if row is None else _decode_publication(row) + + async def _find_request( + self, + connection: AsyncConnection, + target_scope_id: str, + idempotency_key: str, + ) -> ArtifactPublication | None: + row = ( + ( + await connection.execute( + select(ARTIFACT_PUBLICATIONS_TABLE).where( + ARTIFACT_PUBLICATIONS_TABLE.c.target_scope_id == target_scope_id, + ARTIFACT_PUBLICATIONS_TABLE.c.idempotency_key == idempotency_key, + ) + ) + ) + .mappings() + .one_or_none() + ) + return None if row is None else _decode_publication(row) + + +def generate_publication_artifact_id() -> str: + value = int.from_bytes(secrets.token_bytes(16), "big") + encoded = "".join(_CROCKFORD[(value >> shift) & 31] for shift in range(125, -1, -5)) + return f"pub_{encoded}" + + +def _publication_row(publication: ArtifactPublication) -> dict[str, object]: + return { + "target_scope_id": publication.target.scope_id, + "target_family": publication.target.artifact.family, + "target_artifact_id": publication.target.artifact.artifact_id, + "target_revision": publication.target.artifact.revision, + "source_scope_id": publication.source.scope_id, + "source_family": publication.source.artifact.family, + "source_artifact_id": publication.source.artifact.artifact_id, + "source_revision": publication.source.artifact.revision, + "content_digest": publication.content_digest, + } + + +def _decode_publication(row: Mapping[Any, Any]) -> ArtifactPublication: + return ArtifactPublication( + source=ArtifactAddress( + scope_id=str(row["source_scope_id"]), + artifact=ArtifactRef( + family=str(row["source_family"]), + artifact_id=str(row["source_artifact_id"]), + revision=int(row["source_revision"]), + ), + ), + target=ArtifactAddress( + scope_id=str(row["target_scope_id"]), + artifact=ArtifactRef( + family=str(row["target_family"]), + artifact_id=str(row["target_artifact_id"]), + revision=int(row["target_revision"]), + ), + ), + content_digest=str(row["content_digest"]), + ) + + +__all__ = [ + "ArtifactPublication", + "ArtifactPublicationApplication", + "ArtifactPublicationConflictError", + "ArtifactPublicationRequest", +] diff --git a/tests/builtin/test_publication.py b/tests/builtin/test_publication.py new file mode 100644 index 000000000..d9baa68d6 --- /dev/null +++ b/tests/builtin/test_publication.py @@ -0,0 +1,138 @@ +# Copyright (c) 2026 OceanBase. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +from __future__ import annotations + +import asyncio + +import pytest + +from powercontext.artifacts import ArtifactAddress +from powercontext.builtin.persistence.artifacts import ArtifactRepository +from powercontext.builtin.persistence.sqlite import SQLiteConfig, SQLiteProfile +from powercontext.builtin.persistence.tables import BUILTIN_TABLES +from powercontext.builtin.publication import ( + ArtifactPublicationApplication, + ArtifactPublicationConflictError, + ArtifactPublicationRequest, +) +from powercontext.builtin.scope import ScopeApplication, ScopeDraft +from tests.builtin.persistence.contract import Report, ReportContent, ReportDraft + + +def test_publication_copies_one_exact_revision_with_original_provenance() -> None: + async def scenario() -> None: + async with SQLiteProfile.open(SQLiteConfig(), tables=BUILTIN_TABLES) as profile: + scopes = ScopeApplication(profile.database) + source_scope = await scopes.create( + ScopeDraft(title="Source", summary="Private working state", idempotency_key="source") + ) + target_scope = await scopes.create( + ScopeDraft(title="Target", summary="Accepted result", idempotency_key="target") + ) + relay_scope = await scopes.create( + ScopeDraft(title="Relay", summary="Relayed result", idempotency_key="relay") + ) + artifacts = ArtifactRepository((Report,)) + publications = ArtifactPublicationApplication(profile.database, artifacts, scopes) + async with profile.database.transaction() as connection: + first = await artifacts.create( + connection, + source_scope.scope_id, + "report", + ReportDraft(content=ReportContent(status="ready")), + ) + + request = ArtifactPublicationRequest( + source=ArtifactAddress(scope_id=source_scope.scope_id, artifact=first.as_ref()), + target_scope_id=target_scope.scope_id, + idempotency_key="accepted-report", + ) + results = await asyncio.gather(*(publications.publish(request) for _ in range(8))) + published = results[0] + assert all(result == published for result in results) + + async with profile.database.transaction() as connection: + revised = await artifacts.revise( + connection, + source_scope.scope_id, + first, + ReportDraft(content=ReportContent(status="changed")), + ) + copied = await artifacts.get(connection, published.target.scope_id, published.target.artifact) + + assert revised.revision == 2 + assert copied.content == first.content + assert copied.lineage.publication_source == request.source + assert copied.lineage.publication_digest == published.content_digest + + relayed = await publications.publish( + ArtifactPublicationRequest( + source=published.target, + target_scope_id=relay_scope.scope_id, + idempotency_key="relayed-report", + ) + ) + async with profile.database.transaction() as connection: + relay_copy = await artifacts.get(connection, relayed.target.scope_id, relayed.target.artifact) + + assert relay_copy.lineage.publication_source == request.source + assert relay_copy.lineage.publication_digest == published.content_digest + + asyncio.run(scenario()) + + +def test_publication_idempotency_key_cannot_select_another_revision() -> None: + async def scenario() -> None: + async with SQLiteProfile.open(SQLiteConfig(), tables=BUILTIN_TABLES) as profile: + scopes = ScopeApplication(profile.database) + source_scope = await scopes.create( + ScopeDraft(title="Source", summary="Private working state", idempotency_key="source") + ) + target_scope = await scopes.create( + ScopeDraft(title="Target", summary="Accepted result", idempotency_key="target") + ) + artifacts = ArtifactRepository((Report,)) + publications = ArtifactPublicationApplication(profile.database, artifacts, scopes) + async with profile.database.transaction() as connection: + first = await artifacts.create( + connection, + source_scope.scope_id, + "report", + ReportDraft(content=ReportContent(status="ready")), + ) + second = await artifacts.revise( + connection, + source_scope.scope_id, + first, + ReportDraft(content=ReportContent(status="changed")), + ) + + await publications.publish( + ArtifactPublicationRequest( + source=ArtifactAddress(scope_id=source_scope.scope_id, artifact=first.as_ref()), + target_scope_id=target_scope.scope_id, + idempotency_key="accepted-report", + ) + ) + with pytest.raises(ArtifactPublicationConflictError): + await publications.publish( + ArtifactPublicationRequest( + source=ArtifactAddress(scope_id=source_scope.scope_id, artifact=second.as_ref()), + target_scope_id=target_scope.scope_id, + idempotency_key="accepted-report", + ) + ) + + asyncio.run(scenario()) From bbd4c4a19bc281f9aacc6067d918a551d36635b6 Mon Sep 17 00:00:00 2001 From: Chojan Shang Date: Wed, 2 Sep 2026 16:12:32 +0800 Subject: [PATCH 04/17] refactor(scope): replace project reporting with selections --- .env.example | 18 +- Makefile | 1 - openapi/powercontext.yaml | 3955 ++++++++--------- scripts/generate_api.py | 44 +- scripts/generate_js_operations.py | 38 +- .../builtin/artifacts/handoff/service.py | 48 +- .../builtin/handoff_report/__init__.py | 152 +- .../builtin/handoff_report/adapters.py | 48 +- .../builtin/handoff_report/application.py | 443 +- .../builtin/handoff_report/canonical.py | 99 +- .../builtin/handoff_report/catalog.py | 223 - .../builtin/handoff_report/catalog_store.py | 751 ---- .../builtin/handoff_report/errors.py | 173 +- .../builtin/handoff_report/models.py | 483 -- .../builtin/handoff_report/protocols.py | 41 +- .../builtin/handoff_report/rendering.py | 461 +- .../builtin/handoff_report/report.py | 393 +- .../builtin/handoff_report/repository.py | 149 - .../builtin/handoff_report/selection.py | 91 - .../builtin/handoff_report/service.py | 322 -- .../builtin/handoff_report/sqlite.py | 454 -- .../builtin/handoff_report/workspace.py | 101 - .../builtin/handoff_report/workspace_store.py | 322 -- src/powercontext/builtin/runtime/__init__.py | 2 + .../builtin/runtime/application.py | 177 +- .../builtin/runtime/composition.py | 24 +- .../builtin/runtime/prepared_context.py | 110 +- src/powercontext/builtin/runtime/recall.py | 121 +- .../builtin/runtime/relational.py | 30 +- .../builtin/runtime/statistics.py | 42 +- src/powercontext/builtin/scope/application.py | 54 +- src/powercontext/builtin/scope/repository.py | 39 +- .../builtin/statistics/__init__.py | 2 + .../builtin/statistics/aggregation.py | 260 ++ src/powercontext/builtin/statistics/models.py | 23 +- src/powercontext/cli/config.py | 42 +- src/powercontext/cli/hosts.py | 6 - src/powercontext/cli/openclaw.py | 9 +- src/powercontext/cli/system.py | 17 - src/powercontext/cli/workbuddy.py | 12 +- src/powercontext/client/cli.py | 26 +- src/powercontext/client/client.py | 228 +- src/powercontext/http/__init__.py | 160 +- src/powercontext/http/_generated/models.py | 605 +-- .../http/_generated/operations.py | 654 ++- src/powercontext/http/_generated/schema.py | 1439 +++--- src/powercontext/server/app.py | 612 ++- src/powercontext/server/factory.py | 1 - src/powercontext/server/handoff_picker.py | 505 --- src/powercontext/server/mcp.py | 32 +- src/powercontext/server/settings.py | 24 - src/powercontext/server/static/dashboard.js | 54 +- .../server/static/handoff-report.js | 2254 +--------- .../server/static/scope-selection.js | 36 + src/powercontext/server/static/site.css | 178 - .../templates/pages/handoff_report.html | 492 +- src/powercontext/server/web.py | 62 +- 57 files changed, 4709 insertions(+), 12433 deletions(-) delete mode 100644 src/powercontext/builtin/handoff_report/catalog.py delete mode 100644 src/powercontext/builtin/handoff_report/catalog_store.py delete mode 100644 src/powercontext/builtin/handoff_report/models.py delete mode 100644 src/powercontext/builtin/handoff_report/repository.py delete mode 100644 src/powercontext/builtin/handoff_report/selection.py delete mode 100644 src/powercontext/builtin/handoff_report/service.py delete mode 100644 src/powercontext/builtin/handoff_report/sqlite.py delete mode 100644 src/powercontext/builtin/handoff_report/workspace.py delete mode 100644 src/powercontext/builtin/handoff_report/workspace_store.py create mode 100644 src/powercontext/builtin/statistics/aggregation.py delete mode 100644 src/powercontext/server/handoff_picker.py create mode 100644 src/powercontext/server/static/scope-selection.js diff --git a/.env.example b/.env.example index 4cff4556a..93a89c57e 100644 --- a/.env.example +++ b/.env.example @@ -18,9 +18,8 @@ POWERCONTEXT_SERVER_AUTH_ENABLED=false # POWERCONTEXT_SERVER_AUTH_TOKEN=replace-me # Dashboard ------------------------------------------------------------------- -# Every Coding Agent below uses this same Scope ID. +# The Dashboard discovers Scopes from the Server. The Server creates a default Scope on first startup. POWERCONTEXT_SERVER_DASHBOARD_ENABLED=true -POWERCONTEXT_SERVER_DASHBOARD_SCOPES='[{"scope_id":"project:quickstart","display_name":"Quick Start"}]' # Logging, metrics, and tracing ----------------------------------------------- POWERCONTEXT_SERVER_LOGGING_LEVEL=INFO @@ -110,13 +109,14 @@ POWERCONTEXT_CLIENT_TIMEOUT=10 # POWERCONTEXT_CLIENT_API_TOKEN=replace-me # Coding Agent integrations --------------------------------------------------- -# Keep these values equal to the Dashboard scope above. Load .env before starting the selected Agent. -POWERCONTEXT_CODEX_SCOPE_ID=project:quickstart -POWERCONTEXT_CLAUDE_SCOPE_ID=project:quickstart -POWERCONTEXT_DSH_SCOPE_ID=project:quickstart -POWERCONTEXT_OPENCODE_SCOPE_ID=project:quickstart -POWERCONTEXT_PI_SCOPE_ID=project:quickstart -POWERCONTEXT_LANGGRAPH_SCOPE_ID=project:quickstart +# Load .env before starting the selected Agent. Codex binds each Session through the Scope service. +# Set an integration's SCOPE_ID only to select an existing Scope explicitly. +# POWERCONTEXT_CODEX_SCOPE_ID=scp_existing +# POWERCONTEXT_CLAUDE_SCOPE_ID=scp_existing +# POWERCONTEXT_DSH_SCOPE_ID=scp_existing +# POWERCONTEXT_OPENCODE_SCOPE_ID=scp_existing +# POWERCONTEXT_PI_SCOPE_ID=scp_existing +# POWERCONTEXT_LANGGRAPH_SCOPE_ID=scp_existing # Local Server endpoints used by integrations. POWERCONTEXT_CLAUDE_SERVER_URL=http://127.0.0.1:8000 diff --git a/Makefile b/Makefile index 7ec2c3b0c..81276ef3f 100644 --- a/Makefile +++ b/Makefile @@ -103,7 +103,6 @@ js-test: ## Install, build, and test the DeepSeek Harness plugin. @pnpm --dir integrations/dsh/plugins/powercontext test @pnpm --dir integrations/dsh/plugins/powercontext build @git diff --exit-code -- \ - integrations/dsh/plugins/powercontext/openapi/powercontext.yaml \ integrations/dsh/plugins/powercontext/src/operations.generated.ts \ integrations/dsh/plugins/powercontext/lib @pnpm --dir integrations/dsh/plugins/powercontext test diff --git a/openapi/powercontext.yaml b/openapi/powercontext.yaml index a38ba8922..7cde60e8f 100644 --- a/openapi/powercontext.yaml +++ b/openapi/powercontext.yaml @@ -79,12 +79,270 @@ paths: $ref: "#/components/schemas/Capabilities" "401": $ref: "#/components/responses/Unauthorized" + /v1/scopes: + get: + tags: [scopes] + summary: List observable Scopes + operationId: list_scopes + responses: + "200": + description: Durable Scope metadata in deterministic identity order. + content: + application/json: + schema: + $ref: "#/components/schemas/ScopePage" + "401": + $ref: "#/components/responses/Unauthorized" + "503": + $ref: "#/components/responses/Unavailable" + post: + tags: [scopes] + summary: Create an independent Scope boundary + operationId: create_scope + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/CreateScopeRequest" + responses: + "201": + description: The durable Scope descriptor. + content: + application/json: + schema: + $ref: "#/components/schemas/ScopeDescriptor" + "404": + $ref: "#/components/responses/NotFound" + "409": + $ref: "#/components/responses/Conflict" + "401": + $ref: "#/components/responses/Unauthorized" + "422": + $ref: "#/components/responses/InvalidRequest" + /v1/artifact-publications: + post: + tags: [scopes] + summary: Publish one exact Artifact revision into another Scope + operationId: publish_artifact + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/PublishArtifactRequest" + responses: + "201": + description: Independent target Artifact and its exact source provenance. + content: + application/json: + schema: + $ref: "#/components/schemas/ArtifactPublication" + "404": + $ref: "#/components/responses/NotFound" + "409": + $ref: "#/components/responses/Conflict" + "401": + $ref: "#/components/responses/Unauthorized" + "422": + $ref: "#/components/responses/InvalidRequest" + /v1/scopes/{scope_id}: + get: + tags: [scopes] + summary: Get one Scope descriptor + operationId: get_scope + parameters: + - name: scope_id + in: path + required: true + schema: + type: string + minLength: 1 + maxLength: 256 + pattern: '.*\S.*' + responses: + "200": + description: The exact Scope descriptor. + content: + application/json: + schema: + $ref: "#/components/schemas/ScopeDescriptor" + "404": + $ref: "#/components/responses/NotFound" + "401": + $ref: "#/components/responses/Unauthorized" + put: + tags: [scopes] + summary: Replace mutable Scope metadata and relationships + operationId: update_scope + parameters: + - name: scope_id + in: path + required: true + schema: + type: string + minLength: 1 + maxLength: 256 + pattern: '.*\S.*' + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/UpdateScopeRequest" + responses: + "200": + description: The updated Scope descriptor. + content: + application/json: + schema: + $ref: "#/components/schemas/ScopeDescriptor" + "404": + $ref: "#/components/responses/NotFound" + "409": + $ref: "#/components/responses/Conflict" + "401": + $ref: "#/components/responses/Unauthorized" + "422": + $ref: "#/components/responses/InvalidRequest" + /v1/scopes/default: + get: + tags: [scopes] + summary: Get the default Scope binding target + operationId: get_default_scope + responses: + "200": + description: The ordinary Scope selected by the host default pointer. + content: + application/json: + schema: + $ref: "#/components/schemas/ScopeDescriptor" + "404": + $ref: "#/components/responses/NotFound" + "401": + $ref: "#/components/responses/Unauthorized" + put: + tags: [scopes] + summary: Change the default Scope binding target + operationId: set_default_scope + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/SetDefaultScopeRequest" + responses: + "200": + description: The selected ordinary Scope. + content: + application/json: + schema: + $ref: "#/components/schemas/ScopeDescriptor" + "404": + $ref: "#/components/responses/NotFound" + "401": + $ref: "#/components/responses/Unauthorized" + /v1/scopes/selection/resolve: + post: + tags: [scopes] + summary: Resolve an observation selection to a frozen Scope set + operationId: resolve_scope_selection + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/ResolveScopeSelectionRequest" + responses: + "200": + description: The selected Scope descriptors in deterministic order. + content: + application/json: + schema: + $ref: "#/components/schemas/ScopePage" + "404": + $ref: "#/components/responses/NotFound" + "401": + $ref: "#/components/responses/Unauthorized" + "422": + $ref: "#/components/responses/InvalidRequest" + /v1/scope-bindings/resolve: + post: + tags: [scope-bindings] + summary: Resolve an explicit durable or default Scope binding + operationId: resolve_scope_binding + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/ResolveScopeBindingRequest" + responses: + "200": + description: The resolved Scope descriptor. + content: + application/json: + schema: + $ref: "#/components/schemas/ScopeDescriptor" + "404": + $ref: "#/components/responses/NotFound" + "401": + $ref: "#/components/responses/Unauthorized" + "422": + $ref: "#/components/responses/InvalidRequest" + /v1/scope-bindings: + put: + tags: [scope-bindings] + summary: Persist an external identity to Scope binding + operationId: set_scope_binding + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/SetScopeBindingRequest" + responses: + "200": + description: The durable external binding. + content: + application/json: + schema: + $ref: "#/components/schemas/ScopeBinding" + "404": + $ref: "#/components/responses/NotFound" + "401": + $ref: "#/components/responses/Unauthorized" + "422": + $ref: "#/components/responses/InvalidRequest" + /v1/scope-bindings/clear: + post: + tags: [scope-bindings] + summary: Remove one durable external Scope binding + operationId: clear_scope_binding + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/ClearScopeBindingRequest" + responses: + "200": + description: Whether a durable binding was removed. + content: + application/json: + schema: + $ref: "#/components/schemas/ClearScopeBindingResponse" + "401": + $ref: "#/components/responses/Unauthorized" + "422": + $ref: "#/components/responses/InvalidRequest" /v1/sources/content: post: tags: [sources] summary: Capture durable ContentSource evidence description: Accept raw content as an idempotent Source without synchronously deriving Artifacts. operationId: capture_content_source + x-powercontext-scope-mode: current requestBody: required: true content: @@ -117,6 +375,7 @@ paths: summary: Prepare bounded context for an Agent turn description: Prepare final, ephemeral context from Runtime-owned sources without persisting or injecting it. operationId: prepare_context + x-powercontext-scope-mode: current requestBody: required: true content: @@ -147,6 +406,7 @@ paths: summary: Create a grounded Work Contract description: Persist an inspectable delegation baseline without granting execution authority. operationId: create_work_contract + x-powercontext-scope-mode: current requestBody: required: true content: @@ -181,6 +441,7 @@ paths: summary: Hand off current work in one high-level operation description: Capture an inspected boundary and prepare a temporary evidence-bearing Handoff without committing it. operationId: handoff_current_work + x-powercontext-scope-mode: current requestBody: required: true content: @@ -215,6 +476,7 @@ paths: summary: Resolve and acknowledge a Handoff description: Re-resolve one prepared or exact Handoff, check evidence, and capture the receiver's explicit live-state, capability, and authorization checks. operationId: acknowledge_handoff + x-powercontext-scope-mode: current requestBody: required: true content: @@ -249,6 +511,7 @@ paths: summary: Record a completion-aware Task Outcome description: Preserve one attempt's status and checks, optionally linked to the exact accepted Handoff Receipt that the result covers. operationId: record_task_outcome + x-powercontext-scope-mode: current requestBody: required: true content: @@ -283,6 +546,7 @@ paths: summary: Activate Handoff generation at a Source boundary description: Evaluate the standard Handoff Trigger and synchronously execute any emitted PrepareHandoff Action. operationId: activate_handoff + x-powercontext-scope-mode: current requestBody: required: true content: @@ -314,6 +578,7 @@ paths: tags: [handoff] summary: Generate an inspectable Handoff Draft operationId: prepare_handoff + x-powercontext-scope-mode: current requestBody: required: true content: @@ -345,6 +610,7 @@ paths: tags: [handoff] summary: Finalize an inspected Handoff Draft operationId: finalize_handoff + x-powercontext-scope-mode: current requestBody: required: true content: @@ -376,6 +642,7 @@ paths: tags: [handoff] summary: Commit an explicit Handoff milestone operationId: commit_handoff + x-powercontext-scope-mode: current requestBody: required: true content: @@ -409,6 +676,7 @@ paths: tags: [handoff] summary: Resolve a Handoff as untrusted historical input operationId: continue_handoff + x-powercontext-scope-mode: current requestBody: required: true content: @@ -441,6 +709,7 @@ paths: summary: Process the pending Source window into Memory description: Run one bounded Source-to-Memory activation for operational control and testing. operationId: flush_memory + x-powercontext-scope-mode: current requestBody: required: true content: @@ -471,6 +740,7 @@ paths: summary: Remember explicit Memory content description: Save one already-curated Memory entry without creating a Source or invoking extraction. operationId: remember_memory + x-powercontext-scope-mode: current requestBody: required: true content: @@ -503,6 +773,7 @@ paths: summary: Search active Memory entries description: Retrieve relevant active Memory entries within one explicit application scope. operationId: search_memory + x-powercontext-scope-mode: current requestBody: required: true content: @@ -537,6 +808,7 @@ paths: Read active entries from the current Memory head. Inactive entries are available only when explicitly requested for audit. operationId: list_memory_entries + x-powercontext-scope-mode: current requestBody: required: true content: @@ -569,6 +841,7 @@ paths: summary: Get an exact Memory entry version description: Resolve an immutable entry citation within one Memory Revision. operationId: get_memory_entry + x-powercontext-scope-mode: current requestBody: required: true content: @@ -601,6 +874,7 @@ paths: summary: Revise an exact Memory entry description: Replace active entry content against an explicit current Memory Revision. operationId: revise_memory_entry + x-powercontext-scope-mode: current requestBody: required: true content: @@ -635,6 +909,7 @@ paths: summary: Retire an exact Memory entry description: Deactivate an entry against an explicit current Memory Revision without deleting history. operationId: retire_memory_entry + x-powercontext-scope-mode: current requestBody: required: true content: @@ -669,6 +944,7 @@ paths: summary: List Memory Revision changes description: Read compact entry changes without expanding entry bodies. operationId: list_memory_changes + x-powercontext-scope-mode: current requestBody: required: true content: @@ -701,6 +977,7 @@ paths: summary: Propose Experience content description: Persist a pending Experience Candidate without creating an Artifact Revision. operationId: propose_experience + x-powercontext-scope-mode: current requestBody: required: true content: @@ -733,6 +1010,7 @@ paths: summary: Generate an Experience Candidate description: Use the configured model and caller-selected exact evidence; persist only a schema-valid pending Candidate. operationId: generate_experience + x-powercontext-scope-mode: current requestBody: required: true content: @@ -765,6 +1043,7 @@ paths: summary: Get an exact Experience Revision description: Read approved Experience content and its exact direct evidence. operationId: get_experience + x-powercontext-scope-mode: current requestBody: required: true content: @@ -797,6 +1076,7 @@ paths: summary: Propose managed Skill content description: Persist a pending managed Skill Candidate without creating an Artifact Revision. operationId: propose_skill + x-powercontext-scope-mode: current requestBody: required: true content: @@ -829,6 +1109,7 @@ paths: summary: Generate a managed Skill Candidate description: Use the configured model with an explicit provenance shape; persist only a schema-valid pending Candidate. operationId: generate_skill + x-powercontext-scope-mode: current requestBody: required: true content: @@ -861,6 +1142,7 @@ paths: summary: Get an exact managed Skill Revision description: Read approved managed Skill content and its exact direct evidence. operationId: get_skill + x-powercontext-scope-mode: current requestBody: required: true content: @@ -893,6 +1175,7 @@ paths: summary: Scan configured external Skill roots description: Replace the current host-local Registry projection without copying or rewriting package content. operationId: scan_external_skills + x-powercontext-scope-mode: current requestBody: required: true content: @@ -923,6 +1206,7 @@ paths: summary: List external Skills visible on this host description: Return live local resolutions; unavailable registrations are omitted unless explicitly requested. operationId: list_external_skills + x-powercontext-scope-mode: current requestBody: required: true content: @@ -953,6 +1237,7 @@ paths: summary: Resolve an exact external Skill fingerprint description: Resolve only the registered local package version requested by the caller; never install or fall back. operationId: resolve_external_skill + x-powercontext-scope-mode: current requestBody: required: true content: @@ -985,6 +1270,7 @@ paths: summary: Import or fork an external Skill into Review description: Capture one exact local snapshot and use the configured model to propose a new managed Skill Candidate. operationId: import_external_skill + x-powercontext-scope-mode: current requestBody: required: true content: @@ -1019,6 +1305,7 @@ paths: summary: List Artifact Candidates description: Page current Candidate heads; pending is the default Review Inbox view. operationId: list_artifact_candidates + x-powercontext-scope-mode: current requestBody: required: true content: @@ -1049,6 +1336,7 @@ paths: summary: Get an Artifact Candidate description: Read the current head and exact immutable proposal version. operationId: get_artifact_candidate + x-powercontext-scope-mode: current requestBody: required: true content: @@ -1081,6 +1369,7 @@ paths: summary: Approve an Artifact Candidate description: Commit the reviewed proposal and mark the Candidate approved in one transaction. operationId: approve_artifact_candidate + x-powercontext-scope-mode: current requestBody: required: true content: @@ -1115,6 +1404,7 @@ paths: summary: Reject an Artifact Candidate description: Move the exact pending version to its rejected terminal state without writing an Artifact. operationId: reject_artifact_candidate + x-powercontext-scope-mode: current requestBody: required: true content: @@ -1149,6 +1439,7 @@ paths: summary: Revise an Artifact Candidate description: Append a complete replacement proposal as the next immutable pending version. operationId: revise_artifact_candidate + x-powercontext-scope-mode: current requestBody: required: true content: @@ -1178,27 +1469,20 @@ paths: "500": $ref: "#/components/responses/InternalError" /v1/stats: - get: + post: tags: [stats] - summary: Get scoped product statistics + summary: Aggregate product statistics over a Scope selection operationId: get_stats - parameters: - - name: scope_id - in: query - required: true - schema: - type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - - name: period - in: query - required: false - schema: - $ref: "#/components/schemas/StatsPeriod" + x-powercontext-scope-mode: selection + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/GetStatsRequest" responses: "200": - description: Current inventory, model usage, and recall token estimates for the scope. + description: Current inventory, model usage, and recall token estimates for the frozen Scope set. headers: X-PowerContext-Request-ID: $ref: "#/components/headers/RequestId" @@ -1219,2762 +1503,2013 @@ paths: $ref: "#/components/responses/Unavailable" "500": $ref: "#/components/responses/InternalError" - /v1/handoff-reports/projects/create: - post: - tags: [handoff-reports] - summary: Create a Handoff Report Project - operationId: create_handoff_report_project - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/CreateHandoffReportProjectRequest" - responses: - "201": - description: The created Report Project. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/ProjectDescriptor" - "409": - $ref: "#/components/responses/Conflict" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "500": - $ref: "#/components/responses/InternalError" - /v1/handoff-reports/projects/list: + /v1/handoff-reports/get: post: tags: [handoff-reports] - summary: List Handoff Report Projects - operationId: list_handoff_report_projects + summary: Generate a Handoff Report + operationId: get_handoff_report + x-powercontext-scope-mode: selection requestBody: required: true content: application/json: schema: - $ref: "#/components/schemas/ListHandoffReportProjectsRequest" + $ref: "#/components/schemas/GetHandoffReportRequest" responses: "200": - description: A cursor-paginated page of Report Projects. + description: A canonical JSON report, optionally accompanied by Markdown. headers: X-PowerContext-Request-ID: $ref: "#/components/headers/RequestId" + Cache-Control: + description: Prevent caches from retaining scoped report data. + schema: + type: string + enum: [no-store] + X-PowerContext-Selection-Digest: + description: Digest of the exact report selection. + schema: + type: string + pattern: '^sha256:[0-9a-f]{64}$' + X-PowerContext-Report-Digest: + description: Digest of the selected output projection. + schema: + type: string + pattern: '^sha256:[0-9a-f]{64}$' + Content-Disposition: + description: Safe attachment filename when download is true. + schema: + type: string content: application/json: schema: - $ref: "#/components/schemas/ProjectPage" + $ref: "#/components/schemas/HandoffReportResponse" + text/markdown: + schema: + type: string + "404": + $ref: "#/components/responses/NotFound" "401": $ref: "#/components/responses/Unauthorized" "422": $ref: "#/components/responses/InvalidRequest" + "413": + $ref: "#/components/responses/ReportTooLarge" + "503": + $ref: "#/components/responses/Unavailable" "500": $ref: "#/components/responses/InternalError" - /v1/handoff-reports/scopes/list-known: - post: - tags: [handoff-reports] - summary: List scopes that contain a committed Handoff - operationId: list_handoff_report_known_scopes - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/ListHandoffReportKnownScopesRequest" - responses: - "200": - description: A cursor-paginated page of scopes that can be rendered as Handoff Reports. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/KnownHandoffScopePage" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "500": - $ref: "#/components/responses/InternalError" - /v1/handoff-reports/projects/get: - post: - tags: [handoff-reports] - summary: Get a Handoff Report Project - operationId: get_handoff_report_project - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/GetHandoffReportProjectRequest" - responses: - "200": - description: The exact current Report Project descriptor. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/ProjectDescriptor" - "404": - $ref: "#/components/responses/NotFound" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "500": - $ref: "#/components/responses/InternalError" - /v1/handoff-reports/projects/update: - post: - tags: [handoff-reports] - summary: Update a Handoff Report Project - operationId: update_handoff_report_project - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/UpdateHandoffReportProjectRequest" - responses: - "200": - description: The updated Report Project descriptor. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/ProjectDescriptor" - "404": - $ref: "#/components/responses/NotFound" - "409": - $ref: "#/components/responses/Conflict" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "500": - $ref: "#/components/responses/InternalError" - /v1/handoff-reports/workstreams/register: - post: - tags: [handoff-reports] - summary: Register a Handoff Report Workstream - operationId: register_handoff_report_workstream - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/RegisterHandoffReportWorkstreamRequest" - responses: - "201": - description: The registered Report Workstream. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/WorkstreamDescriptor" - "404": - $ref: "#/components/responses/NotFound" - "409": - $ref: "#/components/responses/Conflict" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "500": - $ref: "#/components/responses/InternalError" - /v1/handoff-reports/workstreams/list: - post: - tags: [handoff-reports] - summary: List Handoff Report Workstreams - operationId: list_handoff_report_workstreams - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/ListHandoffReportWorkstreamsRequest" - responses: - "200": - description: A cursor-paginated page of Report Workstreams. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/WorkstreamPage" - "404": - $ref: "#/components/responses/NotFound" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "500": - $ref: "#/components/responses/InternalError" - /v1/handoff-reports/workstreams/update: - post: - tags: [handoff-reports] - summary: Update a Handoff Report Workstream - operationId: update_handoff_report_workstream - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/UpdateHandoffReportWorkstreamRequest" - responses: - "200": - description: The updated Report Workstream descriptor. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/WorkstreamDescriptor" - "404": - $ref: "#/components/responses/NotFound" - "409": - $ref: "#/components/responses/Conflict" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "500": - $ref: "#/components/responses/InternalError" - /v1/handoff-reports/get: - post: - tags: [handoff-reports] - summary: Generate a Handoff Report - operationId: get_handoff_report - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/GetHandoffReportRequest" - responses: - "200": - description: A canonical JSON report, optionally accompanied by Markdown. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - Cache-Control: - description: Prevent caches from retaining scoped report data. - schema: - type: string - enum: [no-store] - X-PowerContext-Selection-Digest: - description: Digest of the exact report selection. - schema: - type: string - pattern: '^sha256:[0-9a-f]{64}$' - X-PowerContext-Report-Digest: - description: Digest of the selected output projection. - schema: - type: string - pattern: '^sha256:[0-9a-f]{64}$' - Content-Disposition: - description: Safe attachment filename when download is true. - schema: - type: string - content: - application/json: - schema: - $ref: "#/components/schemas/HandoffReportResponse" - text/markdown: - schema: - type: string - "404": - $ref: "#/components/responses/NotFound" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "413": - $ref: "#/components/responses/ReportTooLarge" - "503": - $ref: "#/components/responses/Unavailable" - "500": - $ref: "#/components/responses/InternalError" - /v1/handoff-reports/activities/record: - post: - tags: [handoff-reports] - summary: Record a Handoff Report Activity - operationId: record_handoff_report_activity - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/RecordHandoffReportActivityRequest" - responses: - "201": - description: The idempotently recorded Report Activity. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/StoredHandoffReportActivity" - "404": - $ref: "#/components/responses/NotFound" - "409": - $ref: "#/components/responses/Conflict" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "500": - $ref: "#/components/responses/InternalError" - /v1/handoff-reports/activities/list: - post: - tags: [handoff-reports] - summary: List Handoff Report Activities - operationId: list_handoff_report_activities - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/ListHandoffReportActivitiesRequest" - responses: - "200": - description: A frozen cursor page of Report Activities. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/HandoffReportActivityPage" - "404": - $ref: "#/components/responses/NotFound" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "500": - $ref: "#/components/responses/InternalError" - /v1/handoff-reports/activities/purge: - post: - tags: [handoff-reports] - summary: Purge Handoff Report Activities - operationId: purge_handoff_report_activities - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/PurgeHandoffReportActivitiesRequest" - responses: - "200": - description: The number of deleted Report-owned Activity rows. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/PurgeHandoffReportActivitiesResponse" - "404": - $ref: "#/components/responses/NotFound" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "500": - $ref: "#/components/responses/InternalError" - /v1/handoff-reports/workspace-bindings/get: - post: - tags: [handoff-reports] - summary: Get a Handoff Report Workspace Binding - operationId: get_handoff_report_workspace - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/GetHandoffReportWorkspaceRequest" - responses: - "200": - description: The confirmed Workspace binding. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/HandoffReportWorkspaceBinding" - "404": - $ref: "#/components/responses/NotFound" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "500": - $ref: "#/components/responses/InternalError" - /v1/handoff-reports/workspace-bindings/attach: - post: - tags: [handoff-reports] - summary: Attach a Handoff Report Workspace Binding - operationId: attach_handoff_report_workspace - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/AttachHandoffReportWorkspaceRequest" - responses: - "200": - description: The confirmed Workspace binding. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/HandoffReportWorkspaceBinding" - "404": - $ref: "#/components/responses/NotFound" - "409": - $ref: "#/components/responses/Conflict" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "500": - $ref: "#/components/responses/InternalError" - /v1/handoff-reports/workspace-bindings/detach: - post: - tags: [handoff-reports] - summary: Detach a Handoff Report Workspace Binding - operationId: detach_handoff_report_workspace - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/DetachHandoffReportWorkspaceRequest" - responses: - "200": - description: The detached Workspace binding record. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/HandoffReportWorkspaceBinding" - "404": - $ref: "#/components/responses/NotFound" - "409": - $ref: "#/components/responses/Conflict" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "500": - $ref: "#/components/responses/InternalError" -components: - securitySchemes: - BearerAuth: - type: http - scheme: bearer - description: Static bearer token used when local Server authentication is enabled. - headers: - BearerChallenge: - description: Authentication scheme required by the Server. - schema: - type: string - example: Bearer - RequestId: - description: Opaque identifier for correlating one request. - schema: - type: string - responses: - Unauthorized: - description: A valid bearer token is required by this Server deployment. - headers: - WWW-Authenticate: - $ref: "#/components/headers/BearerChallenge" - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorResponse" - Conflict: - description: The command conflicts with current immutable state. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorResponse" - InvalidRequest: - description: The request violates the transport or application contract. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorResponse" - ReportTooLarge: - description: The selected Handoff Report exceeds the deterministic output limit. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorResponse" - NotFound: - description: The requested immutable Memory value was not found. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorResponse" - Unavailable: - description: A required Runtime binding or dependency is unavailable. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorResponse" - InternalError: - description: The Server failed without exposing internal details. +components: + securitySchemes: + BearerAuth: + type: http + scheme: bearer + description: Static bearer token used when local Server authentication is enabled. + headers: + BearerChallenge: + description: Authentication scheme required by the Server. + schema: + type: string + example: Bearer + RequestId: + description: Opaque identifier for correlating one request. + schema: + type: string + responses: + Unauthorized: + description: A valid bearer token is required by this Server deployment. headers: + WWW-Authenticate: + $ref: "#/components/headers/BearerChallenge" X-PowerContext-Request-ID: $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorResponse" - schemas: - ActivateHandoffRequest: - type: object - additionalProperties: false - required: [scope_id, boundary_source, objective] - properties: - scope_id: - type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - boundary_source: - $ref: "#/components/schemas/SourceReference" - objective: - type: string - minLength: 1 - maxLength: 8192 - pattern: '.*\S.*' - evidence: - type: array - maxItems: 32 - items: - $ref: "#/components/schemas/HandoffCitation" - default: [] - max_bytes: - type: integer - minimum: 512 - maximum: 32768 - default: 8000 - ArtifactReference: - type: object - additionalProperties: false - required: [family, artifact_id, revision] - properties: - family: - type: string - minLength: 1 - maxLength: 128 - pattern: '^[\x21-\x7E]+$' - artifact_id: - type: string - minLength: 1 - maxLength: 128 - pattern: '^[\x21-\x7E]+$' - revision: - type: integer - minimum: 1 - ArtifactCandidate: - type: object - additionalProperties: false - required: - - candidate_id - - version - - family - - status - - proposal - - source_refs - - artifact_refs - - target - - reason - - result_artifact - - decision_reason - properties: - candidate_id: - type: string - minLength: 1 - maxLength: 128 - pattern: '^[\x21-\x7E]+$' - version: - type: integer - minimum: 1 - family: - $ref: "#/components/schemas/CandidateFamily" - status: - $ref: "#/components/schemas/CandidateStatus" - proposal: - oneOf: - - $ref: "#/components/schemas/ExperienceProposal" - - $ref: "#/components/schemas/SkillProposal" - source_refs: - type: array - maxItems: 32 - description: Exact Source evidence. Counted with artifact_refs toward a combined maximum of 32 references. - items: - $ref: "#/components/schemas/SourceReference" - artifact_refs: - type: array - maxItems: 32 - description: Exact Artifact evidence. Counted with source_refs toward a combined maximum of 32 references. - items: - $ref: "#/components/schemas/ArtifactReference" - target: - $ref: "#/components/schemas/ArtifactReference" - nullable: true - reason: - type: string - minLength: 1 - maxLength: 2000 - nullable: true - result_artifact: - $ref: "#/components/schemas/ArtifactReference" - nullable: true - decision_reason: - type: string - minLength: 1 - maxLength: 2000 - nullable: true - ArtifactCandidatePage: - type: object - additionalProperties: false - required: [candidates, next_cursor] - properties: - candidates: - type: array - items: - $ref: "#/components/schemas/ArtifactCandidate" - next_cursor: - type: string - nullable: true - ApproveArtifactCandidateRequest: - type: object - additionalProperties: false - required: [scope_id, candidate_id, expected_version] - properties: - scope_id: - type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - candidate_id: - type: string - minLength: 1 - maxLength: 128 - pattern: '^[\x21-\x7E]+$' - expected_version: - type: integer - minimum: 1 - Capabilities: - type: object - additionalProperties: false - required: - [source_types, artifact_families, memory_extraction, handoff_generation, search_modes, context_versions] - properties: - source_types: - type: array - items: - type: string - artifact_families: - type: array - items: - type: string - memory_extraction: - type: boolean - description: Whether pending Sources can be extracted into Memory. - experience_generation: - type: boolean - default: false - description: Whether the configured model can generate reviewed Experience Candidates. - managed_skill_generation: - type: boolean - default: false - description: Whether the configured model can generate reviewed managed Skill Candidates. - external_skill_registry: - type: boolean - default: false - description: Whether host-local external Skill discovery and exact resolution are configured. - handoff_generation: - type: boolean - description: Whether exact evidence can be generated into an inspectable Handoff Draft. - search_modes: - type: array - items: - $ref: "#/components/schemas/MemorySearchMode" - context_versions: - type: array - items: - $ref: "#/components/schemas/PreparedContextSchema" - FamilyCount: - type: object - additionalProperties: false - required: [family, total] - properties: - family: - type: string - minLength: 1 - maxLength: 128 - pattern: '^[\x21-\x7E]+$' - total: - type: integer - minimum: 0 - CandidateFamilyCount: - type: object - additionalProperties: false - required: [family, total, pending, approved, rejected] - properties: - family: - $ref: "#/components/schemas/CandidateFamily" - total: - type: integer - minimum: 0 - pending: - type: integer - minimum: 0 - approved: - type: integer - minimum: 0 - rejected: - type: integer - minimum: 0 - MemoryKindCount: + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorResponse" + Conflict: + description: The command conflicts with current immutable state. + headers: + X-PowerContext-Request-ID: + $ref: "#/components/headers/RequestId" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorResponse" + InvalidRequest: + description: The request violates the transport or application contract. + headers: + X-PowerContext-Request-ID: + $ref: "#/components/headers/RequestId" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorResponse" + ReportTooLarge: + description: The selected Handoff Report exceeds the deterministic output limit. + headers: + X-PowerContext-Request-ID: + $ref: "#/components/headers/RequestId" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorResponse" + NotFound: + description: The requested immutable Memory value was not found. + headers: + X-PowerContext-Request-ID: + $ref: "#/components/headers/RequestId" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorResponse" + Unavailable: + description: A required Runtime binding or dependency is unavailable. + headers: + X-PowerContext-Request-ID: + $ref: "#/components/headers/RequestId" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorResponse" + InternalError: + description: The Server failed without exposing internal details. + headers: + X-PowerContext-Request-ID: + $ref: "#/components/headers/RequestId" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorResponse" + schemas: + ActivateHandoffRequest: type: object additionalProperties: false - required: [kind, total, active, inactive] + required: [scope_id, boundary_source, objective] properties: - kind: + scope_id: type: string minLength: 1 - maxLength: 128 - total: - type: integer - minimum: 0 - active: - type: integer - minimum: 0 - inactive: - type: integer - minimum: 0 - SourceInventoryStatistics: - type: object - additionalProperties: false - required: [total, memory_processed, memory_pending] - properties: - total: - type: integer - minimum: 0 - memory_processed: - type: integer - minimum: 0 - memory_pending: - type: integer - minimum: 0 - ArtifactInventoryStatistics: - type: object - additionalProperties: false - required: [total, by_family] - properties: - total: - type: integer - minimum: 0 - by_family: - type: array - items: - $ref: "#/components/schemas/FamilyCount" - CandidateInventoryStatistics: - type: object - additionalProperties: false - required: [total, pending, approved, rejected, by_family] - properties: - total: - type: integer - minimum: 0 - pending: - type: integer - minimum: 0 - approved: - type: integer - minimum: 0 - rejected: - type: integer - minimum: 0 - by_family: - type: array - items: - $ref: "#/components/schemas/CandidateFamilyCount" - MemoryEntryInventoryStatistics: - type: object - additionalProperties: false - required: [total, active, inactive, by_kind] - properties: - total: - type: integer - minimum: 0 - active: - type: integer - minimum: 0 - inactive: - type: integer - minimum: 0 - by_kind: - type: array - items: - $ref: "#/components/schemas/MemoryKindCount" - MemoryInventoryStatistics: - type: object - additionalProperties: false - required: [entries] - properties: - entries: - $ref: "#/components/schemas/MemoryEntryInventoryStatistics" - InventoryStatistics: - type: object - additionalProperties: false - required: [sources, artifacts, candidates, memory] - properties: - sources: - $ref: "#/components/schemas/SourceInventoryStatistics" - artifacts: - $ref: "#/components/schemas/ArtifactInventoryStatistics" - candidates: - $ref: "#/components/schemas/CandidateInventoryStatistics" - memory: - $ref: "#/components/schemas/MemoryInventoryStatistics" - ModelUsageValue: - type: object - additionalProperties: false - required: [requests, input_tokens, output_tokens] - properties: - requests: - type: integer - minimum: 0 - input_tokens: - type: integer - minimum: 0 - nullable: true - output_tokens: - type: integer - minimum: 0 - nullable: true - ModelUsageStatistics: - type: object - additionalProperties: false - required: [generation, embedding] - properties: - generation: - $ref: "#/components/schemas/ModelUsageValue" - embedding: - $ref: "#/components/schemas/ModelUsageValue" - ModelUsagePurposeBreakdown: - type: object - additionalProperties: false - required: [purpose, generation, embedding] - properties: - purpose: + maxLength: 256 + pattern: '.*\S.*' + boundary_source: + $ref: "#/components/schemas/SourceReference" + objective: type: string minLength: 1 - maxLength: 64 - generation: - $ref: "#/components/schemas/ModelUsageValue" - embedding: - $ref: "#/components/schemas/ModelUsageValue" - ModelUsageDay: - type: object - additionalProperties: false - required: [date, generation, embedding, by_purpose] - properties: - date: - type: string - format: date - generation: - $ref: "#/components/schemas/ModelUsageValue" - embedding: - $ref: "#/components/schemas/ModelUsageValue" - by_purpose: - type: array - maxItems: 16 - items: - $ref: "#/components/schemas/ModelUsagePurposeBreakdown" - ResolvedUsagePeriod: - type: object - additionalProperties: false - required: [preset, start_date, end_date, timezone] - properties: - preset: - $ref: "#/components/schemas/StatsPeriod" - start_date: - type: string - format: date - end_date: - type: string - format: date - timezone: - type: string - enum: [UTC] - UsageStatistics: - type: object - additionalProperties: false - required: [period, totals, by_purpose, daily] - properties: - period: - $ref: "#/components/schemas/ResolvedUsagePeriod" - totals: - $ref: "#/components/schemas/ModelUsageStatistics" - by_purpose: - type: array - maxItems: 16 - items: - $ref: "#/components/schemas/ModelUsagePurposeBreakdown" - daily: + maxLength: 8192 + pattern: '.*\S.*' + evidence: type: array - maxItems: 30 + maxItems: 32 items: - $ref: "#/components/schemas/ModelUsageDay" - TokenEstimatorProfile: + $ref: "#/components/schemas/HandoffCitation" + default: [] + max_bytes: + type: integer + minimum: 512 + maximum: 32768 + default: 8000 + ArtifactReference: type: object additionalProperties: false - required: [estimator_id, version] + required: [family, artifact_id, revision] properties: - estimator_id: + family: type: string minLength: 1 maxLength: 128 - version: + pattern: '^[\x21-\x7E]+$' + artifact_id: type: string minLength: 1 - maxLength: 64 - RecallTokenValue: + maxLength: 128 + pattern: '^[\x21-\x7E]+$' + revision: + type: integer + minimum: 1 + ArtifactAddress: type: object additionalProperties: false - required: [preparations, ready_preparations, comparable_preparations, baseline_tokens, recalled_tokens, token_reduction] + required: [scope_id, artifact] properties: - preparations: - type: integer - minimum: 0 - ready_preparations: - type: integer - minimum: 0 - comparable_preparations: - type: integer - minimum: 0 - baseline_tokens: - type: integer - minimum: 0 - recalled_tokens: - type: integer - minimum: 0 - token_reduction: - type: integer - RecallTokenDay: + scope_id: + type: string + minLength: 1 + maxLength: 256 + pattern: '.*\S.*' + artifact: + $ref: "#/components/schemas/ArtifactReference" + PublishArtifactRequest: type: object additionalProperties: false - required: [date, preparations, ready_preparations, comparable_preparations, baseline_tokens, recalled_tokens, token_reduction] + required: [source, target_scope_id, idempotency_key] properties: - date: + source: + $ref: "#/components/schemas/ArtifactAddress" + target_scope_id: type: string - format: date - preparations: - type: integer - minimum: 0 - ready_preparations: - type: integer - minimum: 0 - comparable_preparations: - type: integer - minimum: 0 - baseline_tokens: - type: integer - minimum: 0 - recalled_tokens: - type: integer - minimum: 0 - token_reduction: - type: integer - RecallTokenStatistics: + minLength: 1 + maxLength: 256 + pattern: '.*\S.*' + idempotency_key: + type: string + minLength: 1 + maxLength: 256 + pattern: '.*\S.*' + ArtifactPublication: type: object additionalProperties: false - required: [period, estimator, totals, daily] + required: [source, target, content_digest] properties: - period: - $ref: "#/components/schemas/ResolvedUsagePeriod" - estimator: - $ref: "#/components/schemas/TokenEstimatorProfile" - nullable: true - totals: - $ref: "#/components/schemas/RecallTokenValue" - daily: - type: array - maxItems: 30 - items: - $ref: "#/components/schemas/RecallTokenDay" - ScopedStats: + source: + $ref: "#/components/schemas/ArtifactAddress" + target: + $ref: "#/components/schemas/ArtifactAddress" + content_digest: + type: string + pattern: '^[0-9a-f]{64}$' + ScopeExternalReference: type: object additionalProperties: false - required: [scope_id, as_of, inventory, usage, recall] + required: [kind, value] properties: - scope_id: + kind: type: string - as_of: + minLength: 1 + maxLength: 128 + pattern: '.*\S.*' + value: type: string - format: date-time - inventory: - $ref: "#/components/schemas/InventoryStatistics" - usage: - $ref: "#/components/schemas/UsageStatistics" - recall: - $ref: "#/components/schemas/RecallTokenStatistics" - GetStatsRequest: + minLength: 1 + maxLength: 2000 + pattern: '.*\S.*' + ScopeDescriptor: type: object additionalProperties: false - required: [scope_id] + required: [scope_id, title, summary, context_references, external_references, version] properties: scope_id: type: string minLength: 1 maxLength: 256 pattern: '.*\S.*' - period: - $ref: "#/components/schemas/StatsPeriod" - default: 30d - WorkClaimBasis: - type: string - enum: [declared, verified] - WorkClaim: - type: object - additionalProperties: false - required: [text, basis, evidence] - properties: - text: + title: type: string minLength: 1 - maxLength: 8192 + maxLength: 256 pattern: '.*\S.*' - basis: - $ref: "#/components/schemas/WorkClaimBasis" - evidence: - type: array - maxItems: 31 - items: - $ref: "#/components/schemas/HandoffCitation" - WorkContract: - type: object - additionalProperties: false - required: [schema, trust, objective, facts, in_scope, exclusions, completion_criteria, authorization_notes, open_questions] - properties: - schema: - type: string - enum: [powercontext.work-contract.v1] - trust: + summary: type: string - enum: [untrusted_input] - objective: + minLength: 1 + maxLength: 2000 + pattern: '.*\S.*' + parent_scope_id: type: string minLength: 1 - maxLength: 8192 + maxLength: 256 pattern: '.*\S.*' - facts: - type: array - maxItems: 64 - items: - $ref: "#/components/schemas/WorkClaim" - in_scope: + nullable: true + context_references: type: array - minItems: 1 - maxItems: 64 + uniqueItems: true items: type: string minLength: 1 - maxLength: 8192 + maxLength: 256 pattern: '.*\S.*' - exclusions: + external_references: type: array - maxItems: 64 + uniqueItems: true items: - type: string - minLength: 1 - maxLength: 8192 - pattern: '.*\S.*' - completion_criteria: + $ref: "#/components/schemas/ScopeExternalReference" + version: + type: integer + minimum: 1 + ScopePage: + type: object + additionalProperties: false + required: [items] + properties: + items: type: array - minItems: 1 - maxItems: 64 items: - type: string - minLength: 1 - maxLength: 8192 - pattern: '.*\S.*' - authorization_notes: + $ref: "#/components/schemas/ScopeDescriptor" + CreateScopeRequest: + type: object + additionalProperties: false + required: [title, summary, idempotency_key] + properties: + title: + type: string + minLength: 1 + maxLength: 256 + pattern: '.*\S.*' + summary: + type: string + minLength: 1 + maxLength: 2000 + pattern: '.*\S.*' + parent_scope_id: + type: string + minLength: 1 + maxLength: 256 + pattern: '.*\S.*' + nullable: true + context_references: type: array - maxItems: 64 + uniqueItems: true items: type: string minLength: 1 - maxLength: 8192 + maxLength: 256 pattern: '.*\S.*' - open_questions: + default: [] + external_references: type: array - maxItems: 64 + uniqueItems: true items: - type: string - minLength: 1 - maxLength: 8192 - pattern: '.*\S.*' - CreateWorkContractRequest: + $ref: "#/components/schemas/ScopeExternalReference" + default: [] + idempotency_key: + type: string + minLength: 1 + maxLength: 256 + pattern: '.*\S.*' + UpdateScopeRequest: type: object additionalProperties: false - required: [scope_id, source_id, contract] + required: [expected_version, title, summary] properties: - scope_id: + expected_version: + type: integer + minimum: 1 + title: type: string minLength: 1 maxLength: 256 pattern: '.*\S.*' - source_id: + summary: type: string minLength: 1 - maxLength: 256 + maxLength: 2000 pattern: '.*\S.*' - contract: - $ref: "#/components/schemas/WorkContract" - CurrentWorkHandoff: - type: object - additionalProperties: false - required: [schema, trust, objective, state, disposition, next_action, omissions] - properties: - schema: - type: string - enum: [powercontext.current-work-handoff.v1] - trust: - type: string - enum: [untrusted_input] - objective: + parent_scope_id: type: string minLength: 1 - maxLength: 8192 - pattern: '.*\S.*' - state: - type: array - minItems: 1 - maxItems: 64 - items: - $ref: "#/components/schemas/WorkClaim" - disposition: - $ref: "#/components/schemas/HandoffDisposition" - next_action: - $ref: "#/components/schemas/WorkClaim" + maxLength: 256 + pattern: '.*\S.*' nullable: true - omissions: + context_references: type: array - maxItems: 64 + uniqueItems: true items: type: string minLength: 1 - maxLength: 8192 + maxLength: 256 pattern: '.*\S.*' - HandoffCurrentWorkRequest: + default: [] + external_references: + type: array + uniqueItems: true + items: + $ref: "#/components/schemas/ScopeExternalReference" + default: [] + SetDefaultScopeRequest: type: object additionalProperties: false - required: [scope_id, source_id, handoff] + required: [scope_id] properties: scope_id: type: string minLength: 1 maxLength: 256 pattern: '.*\S.*' - source_id: + AllScopeSelection: + type: object + additionalProperties: false + required: [mode] + properties: + mode: type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - handoff: - $ref: "#/components/schemas/CurrentWorkHandoff" - WorkSourceKind: - type: string - enum: [work-contract, handoff-boundary, handoff-receipt, task-outcome] - WorkSourceReceipt: + enum: [all] + ExactScopeSelection: type: object additionalProperties: false - required: [kind, source, position, content_digest] + required: [mode, scope_ids] properties: - kind: - $ref: "#/components/schemas/WorkSourceKind" - source: - $ref: "#/components/schemas/SourceReference" - position: - type: integer - minimum: 1 - content_digest: + mode: type: string - minLength: 71 - maxLength: 71 - pattern: '^sha256:[0-9a-f]{64}$' - PreparedWorkHandoff: + enum: [exact] + scope_ids: + type: array + minItems: 1 + uniqueItems: true + items: + type: string + minLength: 1 + maxLength: 256 + pattern: '.*\S.*' + SubtreeScopeSelection: type: object additionalProperties: false - required: [boundary, handoff] + required: [mode, root_scope_id] properties: - boundary: - $ref: "#/components/schemas/WorkSourceReceipt" - handoff: - $ref: "#/components/schemas/PreparedHandoff" - HandoffReceiptStatus: - type: string - enum: [accepted, needs_clarification, declined] - HandoffAcknowledgementSelection: - type: string - enum: [prepared, exact] - LiveStateCheckStatus: - type: string - enum: [confirmed, mismatch, not_checked] - ReceiverReadinessCheckStatus: - type: string - enum: [confirmed, insufficient, not_checked] - ReceiverChecks: + mode: + type: string + enum: [subtree] + root_scope_id: + type: string + minLength: 1 + maxLength: 256 + pattern: '.*\S.*' + ScopeSelection: + oneOf: + - $ref: "#/components/schemas/AllScopeSelection" + - $ref: "#/components/schemas/ExactScopeSelection" + - $ref: "#/components/schemas/SubtreeScopeSelection" + discriminator: + propertyName: mode + ResolveScopeSelectionRequest: type: object additionalProperties: false - description: Untrusted receiver self-attestation kept separate from citation availability. All three values must be confirmed when status is accepted. - required: [live_state, capability, authorization] + required: [selection] properties: - live_state: - $ref: "#/components/schemas/LiveStateCheckStatus" - capability: - $ref: "#/components/schemas/ReceiverReadinessCheckStatus" - authorization: - $ref: "#/components/schemas/ReceiverReadinessCheckStatus" - AcknowledgeHandoffRequest: + selection: + $ref: "#/components/schemas/ScopeSelection" + ScopeBindingKey: type: object additionalProperties: false - required: [scope_id, source_id, receiver, status, selection] + required: [integration, kind, external_id] properties: - scope_id: + integration: type: string minLength: 1 - maxLength: 256 + maxLength: 128 pattern: '.*\S.*' - source_id: + kind: type: string minLength: 1 - maxLength: 256 + maxLength: 64 pattern: '.*\S.*' - receiver: + external_id: type: string minLength: 1 maxLength: 256 pattern: '.*\S.*' - status: - $ref: "#/components/schemas/HandoffReceiptStatus" - selection: - $ref: "#/components/schemas/HandoffAcknowledgementSelection" - receiver_checks: - $ref: "#/components/schemas/ReceiverChecks" - nullable: true - prepared: - $ref: "#/components/schemas/PreparedHandoff" - nullable: true - revision: - $ref: "#/components/schemas/ArtifactReference" - nullable: true - message: + ScopeBinding: + type: object + additionalProperties: false + required: [key, scope_id] + properties: + key: + $ref: "#/components/schemas/ScopeBindingKey" + scope_id: type: string minLength: 1 - maxLength: 8192 + maxLength: 256 pattern: '.*\S.*' - nullable: true - HandoffAcknowledgement: + SetScopeBindingRequest: + $ref: "#/components/schemas/ScopeBinding" + ClearScopeBindingRequest: type: object additionalProperties: false - required: [resolution, receipt] + required: [key] properties: - resolution: - $ref: "#/components/schemas/HandoffResolution" - receipt: - $ref: "#/components/schemas/WorkSourceReceipt" - TaskOutcomeStatus: - type: string - enum: [succeeded, partial, blocked, failed, cancelled, unknown] - TaskCheckStatus: - type: string - enum: [passed, failed, skipped, timed_out, unavailable, cancelled, unknown] - TaskCheck: + key: + $ref: "#/components/schemas/ScopeBindingKey" + ClearScopeBindingResponse: type: object additionalProperties: false - required: [name, status, basis, evidence] + required: [cleared] properties: - name: + cleared: + type: boolean + ResolveScopeBindingRequest: + type: object + additionalProperties: false + properties: + explicit_scope_id: type: string minLength: 1 - maxLength: 8192 + maxLength: 256 pattern: '.*\S.*' - status: - $ref: "#/components/schemas/TaskCheckStatus" - details: + nullable: true + binding_keys: + type: array + items: + $ref: "#/components/schemas/ScopeBindingKey" + default: [] + ArtifactCandidate: + type: object + additionalProperties: false + required: + - candidate_id + - version + - family + - status + - proposal + - source_refs + - artifact_refs + - target + - reason + - result_artifact + - decision_reason + properties: + candidate_id: type: string minLength: 1 - maxLength: 8192 - pattern: '.*\S.*' - nullable: true - basis: - $ref: "#/components/schemas/WorkClaimBasis" - evidence: + maxLength: 128 + pattern: '^[\x21-\x7E]+$' + version: + type: integer + minimum: 1 + family: + $ref: "#/components/schemas/CandidateFamily" + status: + $ref: "#/components/schemas/CandidateStatus" + proposal: + oneOf: + - $ref: "#/components/schemas/ExperienceProposal" + - $ref: "#/components/schemas/SkillProposal" + source_refs: type: array maxItems: 32 + description: Exact Source evidence. Counted with artifact_refs toward a combined maximum of 32 references. items: - $ref: "#/components/schemas/HandoffCitation" - TaskOutcome: + $ref: "#/components/schemas/SourceReference" + artifact_refs: + type: array + maxItems: 32 + description: Exact Artifact evidence. Counted with source_refs toward a combined maximum of 32 references. + items: + $ref: "#/components/schemas/ArtifactReference" + target: + $ref: "#/components/schemas/ArtifactReference" + nullable: true + reason: + type: string + minLength: 1 + maxLength: 2000 + nullable: true + result_artifact: + $ref: "#/components/schemas/ArtifactReference" + nullable: true + decision_reason: + type: string + minLength: 1 + maxLength: 2000 + nullable: true + ArtifactCandidatePage: type: object additionalProperties: false - required: [schema, trust, objective, status, summary, observations, checks, produced_artifacts, remaining_work] + required: [candidates, next_cursor] properties: - schema: - type: string - enum: [powercontext.task-outcome.v1] - trust: + candidates: + type: array + items: + $ref: "#/components/schemas/ArtifactCandidate" + next_cursor: type: string - enum: [untrusted_observation] - objective: + nullable: true + ApproveArtifactCandidateRequest: + type: object + additionalProperties: false + required: [scope_id, candidate_id, expected_version] + properties: + scope_id: type: string minLength: 1 - maxLength: 8192 + maxLength: 256 pattern: '.*\S.*' - status: - $ref: "#/components/schemas/TaskOutcomeStatus" - summary: + candidate_id: type: string minLength: 1 - maxLength: 8192 - pattern: '.*\S.*' - handoff_receipt_ref: - $ref: "#/components/schemas/SourceReference" - nullable: true - observations: - type: array - minItems: 1 - maxItems: 64 + maxLength: 128 + pattern: '^[\x21-\x7E]+$' + expected_version: + type: integer + minimum: 1 + Capabilities: + type: object + additionalProperties: false + required: + [source_types, artifact_families, memory_extraction, handoff_generation, search_modes, context_versions] + properties: + source_types: + type: array items: - $ref: "#/components/schemas/WorkClaim" - checks: + type: string + artifact_families: type: array - maxItems: 64 items: - $ref: "#/components/schemas/TaskCheck" - produced_artifacts: + type: string + memory_extraction: + type: boolean + description: Whether pending Sources can be extracted into Memory. + experience_generation: + type: boolean + default: false + description: Whether the configured model can generate reviewed Experience Candidates. + managed_skill_generation: + type: boolean + default: false + description: Whether the configured model can generate reviewed managed Skill Candidates. + external_skill_registry: + type: boolean + default: false + description: Whether host-local external Skill discovery and exact resolution are configured. + handoff_generation: + type: boolean + description: Whether exact evidence can be generated into an inspectable Handoff Draft. + search_modes: type: array - maxItems: 32 items: - $ref: "#/components/schemas/ArtifactReference" - remaining_work: + $ref: "#/components/schemas/MemorySearchMode" + context_versions: type: array - maxItems: 64 items: - type: string - minLength: 1 - maxLength: 8192 - pattern: '.*\S.*' - RecordTaskOutcomeRequest: + $ref: "#/components/schemas/PreparedContextSchema" + FamilyCount: type: object additionalProperties: false - required: [scope_id, source_id, outcome] + required: [family, total] properties: - scope_id: - type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - source_id: + family: type: string minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - outcome: - $ref: "#/components/schemas/TaskOutcome" - CaptureContentSourceRequest: + maxLength: 128 + pattern: '^[\x21-\x7E]+$' + total: + type: integer + minimum: 0 + CandidateFamilyCount: type: object additionalProperties: false - required: [scope_id, source_id, content] + required: [family, total, pending, approved, rejected] properties: - scope_id: - type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - source_id: - type: string - minLength: 1 - maxLength: 256 - content: + family: + $ref: "#/components/schemas/CandidateFamily" + total: + type: integer + minimum: 0 + pending: + type: integer + minimum: 0 + approved: + type: integer + minimum: 0 + rejected: + type: integer + minimum: 0 + MemoryKindCount: + type: object + additionalProperties: false + required: [kind, total, active, inactive] + properties: + kind: type: string minLength: 1 - maxLength: 200000 - metadata: - type: object - additionalProperties: true - nullable: true - CaptureContentSourceResponse: + maxLength: 128 + total: + type: integer + minimum: 0 + active: + type: integer + minimum: 0 + inactive: + type: integer + minimum: 0 + SourceInventoryStatistics: type: object additionalProperties: false - required: [status, source, position] + required: [total, memory_processed, memory_pending] properties: - status: - $ref: "#/components/schemas/CaptureStatus" - source: - $ref: "#/components/schemas/SourceReference" - position: + total: type: integer - minimum: 1 - CommitHandoffRequest: + minimum: 0 + memory_processed: + type: integer + minimum: 0 + memory_pending: + type: integer + minimum: 0 + ArtifactInventoryStatistics: type: object additionalProperties: false - required: [scope_id, handoff] + required: [total, by_family] properties: - scope_id: - type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - handoff: - $ref: "#/components/schemas/PreparedHandoff" - CommittedHandoff: + total: + type: integer + minimum: 0 + by_family: + type: array + items: + $ref: "#/components/schemas/FamilyCount" + CandidateInventoryStatistics: type: object additionalProperties: false - required: [reference, content, source_refs, artifact_refs] + required: [total, pending, approved, rejected, by_family] properties: - reference: - $ref: "#/components/schemas/ArtifactReference" - content: - $ref: "#/components/schemas/HandoffContent" - source_refs: + total: + type: integer + minimum: 0 + pending: + type: integer + minimum: 0 + approved: + type: integer + minimum: 0 + rejected: + type: integer + minimum: 0 + by_family: type: array items: - $ref: "#/components/schemas/SourceReference" - artifact_refs: + $ref: "#/components/schemas/CandidateFamilyCount" + MemoryEntryInventoryStatistics: + type: object + additionalProperties: false + required: [total, active, inactive, by_kind] + properties: + total: + type: integer + minimum: 0 + active: + type: integer + minimum: 0 + inactive: + type: integer + minimum: 0 + by_kind: type: array items: - $ref: "#/components/schemas/ArtifactReference" - ContinueHandoffRequest: + $ref: "#/components/schemas/MemoryKindCount" + MemoryInventoryStatistics: type: object additionalProperties: false - required: [scope_id, selection] + required: [entries] properties: - scope_id: - type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - selection: - $ref: "#/components/schemas/HandoffSelection" - prepared: - $ref: "#/components/schemas/PreparedHandoff" + entries: + $ref: "#/components/schemas/MemoryEntryInventoryStatistics" + InventoryStatistics: + type: object + additionalProperties: false + required: [sources, artifacts, candidates, memory] + properties: + sources: + $ref: "#/components/schemas/SourceInventoryStatistics" + artifacts: + $ref: "#/components/schemas/ArtifactInventoryStatistics" + candidates: + $ref: "#/components/schemas/CandidateInventoryStatistics" + memory: + $ref: "#/components/schemas/MemoryInventoryStatistics" + ModelUsageValue: + type: object + additionalProperties: false + required: [requests, input_tokens, output_tokens] + properties: + requests: + type: integer + minimum: 0 + input_tokens: + type: integer + minimum: 0 nullable: true - revision: - $ref: "#/components/schemas/ArtifactReference" + output_tokens: + type: integer + minimum: 0 nullable: true - FinalizeHandoffRequest: + ModelUsageStatistics: type: object additionalProperties: false - required: [scope_id, draft] + required: [generation, embedding] properties: - scope_id: + generation: + $ref: "#/components/schemas/ModelUsageValue" + embedding: + $ref: "#/components/schemas/ModelUsageValue" + ModelUsagePurposeBreakdown: + type: object + additionalProperties: false + required: [purpose, generation, embedding] + properties: + purpose: type: string minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - draft: - $ref: "#/components/schemas/HandoffDraft" - HandoffArtifactCitation: + maxLength: 64 + generation: + $ref: "#/components/schemas/ModelUsageValue" + embedding: + $ref: "#/components/schemas/ModelUsageValue" + ModelUsageDay: type: object additionalProperties: false - required: [kind, artifact_ref] + required: [date, generation, embedding, by_purpose] properties: - kind: + date: type: string - enum: [artifact] - artifact_ref: - $ref: "#/components/schemas/ArtifactReference" - HandoffActivation: + format: date + generation: + $ref: "#/components/schemas/ModelUsageValue" + embedding: + $ref: "#/components/schemas/ModelUsageValue" + by_purpose: + type: array + maxItems: 16 + items: + $ref: "#/components/schemas/ModelUsagePurposeBreakdown" + ResolvedUsagePeriod: type: object additionalProperties: false - required: [status, boundary_source, previous_position, current_position, draft] + required: [preset, start_date, end_date, timezone] properties: - status: - $ref: "#/components/schemas/HandoffActivationStatus" - boundary_source: - $ref: "#/components/schemas/SourceReference" - previous_position: - type: integer - minimum: 0 - current_position: - type: integer - minimum: 0 - draft: - $ref: "#/components/schemas/HandoffDraft" - nullable: true - HandoffCitation: - oneOf: - - $ref: "#/components/schemas/HandoffSourceCitation" - - $ref: "#/components/schemas/HandoffArtifactCitation" - - $ref: "#/components/schemas/HandoffMemoryCitation" - discriminator: - propertyName: kind - mapping: - source: "#/components/schemas/HandoffSourceCitation" - artifact: "#/components/schemas/HandoffArtifactCitation" - memory: "#/components/schemas/HandoffMemoryCitation" - HandoffContent: + preset: + $ref: "#/components/schemas/StatsPeriod" + start_date: + type: string + format: date + end_date: + type: string + format: date + timezone: + type: string + enum: [UTC] + UsageStatistics: type: object additionalProperties: false - required: [schema, objective, state, disposition, next_action, omissions] + required: [period, totals, by_purpose, daily] properties: - schema: - $ref: "#/components/schemas/HandoffSchema" - objective: - type: string - minLength: 1 - maxLength: 8192 - pattern: '.*\S.*' - state: + period: + $ref: "#/components/schemas/ResolvedUsagePeriod" + totals: + $ref: "#/components/schemas/ModelUsageStatistics" + by_purpose: type: array - minItems: 1 - maxItems: 64 + maxItems: 16 items: - $ref: "#/components/schemas/HandoffStatement" - disposition: - $ref: "#/components/schemas/HandoffDisposition" - next_action: - $ref: "#/components/schemas/HandoffStatement" - nullable: true - omissions: + $ref: "#/components/schemas/ModelUsagePurposeBreakdown" + daily: type: array - maxItems: 64 + maxItems: 30 items: - $ref: "#/components/schemas/HandoffOmission" - HandoffDraft: + $ref: "#/components/schemas/ModelUsageDay" + TokenEstimatorProfile: type: object additionalProperties: false - required: [objective, state, disposition, next_action, omissions] + required: [estimator_id, version] properties: - objective: + estimator_id: type: string minLength: 1 - maxLength: 8192 - pattern: '.*\S.*' - state: - type: array - minItems: 1 - maxItems: 64 - items: - $ref: "#/components/schemas/HandoffStatement" - disposition: - $ref: "#/components/schemas/HandoffDisposition" - next_action: - $ref: "#/components/schemas/HandoffStatement" - nullable: true - omissions: - type: array - maxItems: 64 - items: - $ref: "#/components/schemas/HandoffOmission" - HandoffEvidenceCheck: + maxLength: 128 + version: + type: string + minLength: 1 + maxLength: 64 + RecallTokenValue: type: object additionalProperties: false - required: [claim, state_index, status, unavailable_evidence] + required: [preparations, ready_preparations, comparable_preparations, baseline_tokens, recalled_tokens, token_reduction] properties: - claim: - $ref: "#/components/schemas/HandoffClaim" - state_index: + preparations: type: integer minimum: 0 - nullable: true - status: - $ref: "#/components/schemas/HandoffEvidenceStatus" - unavailable_evidence: - type: array - maxItems: 32 - items: - $ref: "#/components/schemas/HandoffCitation" - HandoffMemoryCitation: + ready_preparations: + type: integer + minimum: 0 + comparable_preparations: + type: integer + minimum: 0 + baseline_tokens: + type: integer + minimum: 0 + recalled_tokens: + type: integer + minimum: 0 + token_reduction: + type: integer + RecallTokenDay: type: object additionalProperties: false - required: [kind, memory_citation] + required: [date, preparations, ready_preparations, comparable_preparations, baseline_tokens, recalled_tokens, token_reduction] properties: - kind: + date: type: string - enum: [memory] - memory_citation: - $ref: "#/components/schemas/MemoryCitation" - HandoffOmission: + format: date + preparations: + type: integer + minimum: 0 + ready_preparations: + type: integer + minimum: 0 + comparable_preparations: + type: integer + minimum: 0 + baseline_tokens: + type: integer + minimum: 0 + recalled_tokens: + type: integer + minimum: 0 + token_reduction: + type: integer + RecallTokenStatistics: type: object additionalProperties: false - required: [text, citation] + required: [period, estimator, totals, daily] properties: - text: - type: string - minLength: 1 - maxLength: 8192 - pattern: '.*\S.*' - citation: - $ref: "#/components/schemas/HandoffCitation" + period: + $ref: "#/components/schemas/ResolvedUsagePeriod" + estimator: + $ref: "#/components/schemas/TokenEstimatorProfile" nullable: true - HandoffResolution: + totals: + $ref: "#/components/schemas/RecallTokenValue" + daily: + type: array + maxItems: 30 + items: + $ref: "#/components/schemas/RecallTokenDay" + ScopeStats: type: object additionalProperties: false - required: - [trust, status, scope_id, content, selection, selected_revision, current_revision, evidence_checks] + required: [scope_id, inventory, usage, recall] properties: - trust: - type: string - enum: [untrusted_history] - status: - $ref: "#/components/schemas/HandoffResolutionStatus" scope_id: type: string - content: - $ref: "#/components/schemas/HandoffContent" - nullable: true + inventory: + $ref: "#/components/schemas/InventoryStatistics" + usage: + $ref: "#/components/schemas/UsageStatistics" + recall: + $ref: "#/components/schemas/RecallTokenStatistics" + ScopedStats: + type: object + additionalProperties: false + required: [selection, scope_ids, as_of, inventory, usage, recall, by_scope] + properties: selection: - $ref: "#/components/schemas/HandoffSelection" - nullable: true - selected_revision: - $ref: "#/components/schemas/ArtifactReference" - nullable: true - current_revision: - $ref: "#/components/schemas/ArtifactReference" - nullable: true - evidence_checks: + $ref: "#/components/schemas/ScopeSelection" + scope_ids: type: array - maxItems: 65 + uniqueItems: true items: - $ref: "#/components/schemas/HandoffEvidenceCheck" - HandoffSourceCitation: + type: string + as_of: + type: string + format: date-time + inventory: + $ref: "#/components/schemas/InventoryStatistics" + usage: + $ref: "#/components/schemas/UsageStatistics" + recall: + $ref: "#/components/schemas/RecallTokenStatistics" + by_scope: + type: array + items: + $ref: "#/components/schemas/ScopeStats" + GetStatsRequest: type: object additionalProperties: false - required: [kind, source_ref] + required: [selection] properties: - kind: - type: string - enum: [source] - source_ref: - $ref: "#/components/schemas/SourceReference" - HandoffStatement: + selection: + $ref: "#/components/schemas/ScopeSelection" + period: + $ref: "#/components/schemas/StatsPeriod" + default: 30d + WorkClaimBasis: + type: string + enum: [declared, verified] + WorkClaim: type: object additionalProperties: false - required: [text, citations] + required: [text, basis, evidence] properties: text: type: string minLength: 1 maxLength: 8192 pattern: '.*\S.*' - citations: + basis: + $ref: "#/components/schemas/WorkClaimBasis" + evidence: type: array - minItems: 1 - maxItems: 32 + maxItems: 31 items: $ref: "#/components/schemas/HandoffCitation" - PrepareHandoffRequest: + WorkContract: type: object additionalProperties: false - required: [scope_id, objective, evidence] + required: [schema, trust, objective, facts, in_scope, exclusions, completion_criteria, authorization_notes, open_questions] properties: - scope_id: + schema: type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' + enum: [powercontext.work-contract.v1] + trust: + type: string + enum: [untrusted_input] objective: type: string minLength: 1 maxLength: 8192 pattern: '.*\S.*' - evidence: + facts: + type: array + maxItems: 64 + items: + $ref: "#/components/schemas/WorkClaim" + in_scope: type: array minItems: 1 - maxItems: 32 + maxItems: 64 items: - $ref: "#/components/schemas/HandoffCitation" - max_bytes: - type: integer - minimum: 512 - maximum: 32768 - default: 8000 - PreparedHandoff: + type: string + minLength: 1 + maxLength: 8192 + pattern: '.*\S.*' + exclusions: + type: array + maxItems: 64 + items: + type: string + minLength: 1 + maxLength: 8192 + pattern: '.*\S.*' + completion_criteria: + type: array + minItems: 1 + maxItems: 64 + items: + type: string + minLength: 1 + maxLength: 8192 + pattern: '.*\S.*' + authorization_notes: + type: array + maxItems: 64 + items: + type: string + minLength: 1 + maxLength: 8192 + pattern: '.*\S.*' + open_questions: + type: array + maxItems: 64 + items: + type: string + minLength: 1 + maxLength: 8192 + pattern: '.*\S.*' + CreateWorkContractRequest: type: object additionalProperties: false - required: [schema, scope_id, base, content] + required: [scope_id, source_id, contract] properties: - schema: - $ref: "#/components/schemas/PreparedHandoffSchema" scope_id: type: string - base: - $ref: "#/components/schemas/ArtifactReference" - nullable: true - content: - $ref: "#/components/schemas/HandoffContent" - PreparedContext: + minLength: 1 + maxLength: 256 + pattern: '.*\S.*' + source_id: + type: string + minLength: 1 + maxLength: 256 + pattern: '.*\S.*' + contract: + $ref: "#/components/schemas/WorkContract" + CurrentWorkHandoff: type: object additionalProperties: false - required: [schema, status, content, content_bytes] + required: [schema, trust, objective, state, disposition, next_action, omissions] properties: schema: - $ref: "#/components/schemas/PreparedContextSchema" - status: - $ref: "#/components/schemas/PreparedContextStatus" - content: type: string + enum: [powercontext.current-work-handoff.v1] + trust: + type: string + enum: [untrusted_input] + objective: + type: string + minLength: 1 + maxLength: 8192 + pattern: '.*\S.*' + state: + type: array + minItems: 1 + maxItems: 64 + items: + $ref: "#/components/schemas/WorkClaim" + disposition: + $ref: "#/components/schemas/HandoffDisposition" + next_action: + $ref: "#/components/schemas/WorkClaim" nullable: true - content_bytes: - type: integer - minimum: 0 - EntryChange: + omissions: + type: array + maxItems: 64 + items: + type: string + minLength: 1 + maxLength: 8192 + pattern: '.*\S.*' + HandoffCurrentWorkRequest: type: object additionalProperties: false - required: [op, entry_id, from_entry_version_id, to_entry_version_id, reason] + required: [scope_id, source_id, handoff] properties: - op: - $ref: "#/components/schemas/EntryChangeOperation" - entry_id: - type: string - minLength: 1 - maxLength: 128 - pattern: '^[\x21-\x7E]+$' - from_entry_version_id: + scope_id: type: string minLength: 1 - maxLength: 128 - pattern: '^[\x21-\x7E]+$' - nullable: true - to_entry_version_id: + maxLength: 256 + pattern: '.*\S.*' + source_id: type: string minLength: 1 - maxLength: 128 - pattern: '^[\x21-\x7E]+$' - nullable: true - reason: + maxLength: 256 + pattern: '.*\S.*' + handoff: + $ref: "#/components/schemas/CurrentWorkHandoff" + WorkSourceKind: + type: string + enum: [work-contract, handoff-boundary, handoff-receipt, task-outcome] + WorkSourceReceipt: + type: object + additionalProperties: false + required: [kind, source, position, content_digest] + properties: + kind: + $ref: "#/components/schemas/WorkSourceKind" + source: + $ref: "#/components/schemas/SourceReference" + position: + type: integer + minimum: 1 + content_digest: type: string - nullable: true - ExperienceArtifact: + minLength: 71 + maxLength: 71 + pattern: '^sha256:[0-9a-f]{64}$' + PreparedWorkHandoff: type: object additionalProperties: false - required: [artifact, content, source_refs, artifact_refs] + required: [boundary, handoff] properties: - artifact: - $ref: "#/components/schemas/ArtifactReference" - content: - $ref: "#/components/schemas/ExperienceProposal" - source_refs: - type: array - items: - $ref: "#/components/schemas/SourceReference" - artifact_refs: - type: array - items: - $ref: "#/components/schemas/ArtifactReference" - ExperienceProposal: + boundary: + $ref: "#/components/schemas/WorkSourceReceipt" + handoff: + $ref: "#/components/schemas/PreparedHandoff" + HandoffReceiptStatus: + type: string + enum: [accepted, needs_clarification, declined] + HandoffAcknowledgementSelection: + type: string + enum: [prepared, exact] + LiveStateCheckStatus: + type: string + enum: [confirmed, mismatch, not_checked] + ReceiverReadinessCheckStatus: + type: string + enum: [confirmed, insufficient, not_checked] + ReceiverChecks: type: object additionalProperties: false - required: [situation, action, outcome, lesson] + description: Untrusted receiver self-attestation kept separate from citation availability. All three values must be confirmed when status is accepted. + required: [live_state, capability, authorization] properties: - situation: + live_state: + $ref: "#/components/schemas/LiveStateCheckStatus" + capability: + $ref: "#/components/schemas/ReceiverReadinessCheckStatus" + authorization: + $ref: "#/components/schemas/ReceiverReadinessCheckStatus" + AcknowledgeHandoffRequest: + type: object + additionalProperties: false + required: [scope_id, source_id, receiver, status, selection] + properties: + scope_id: type: string minLength: 1 - maxLength: 8000 + maxLength: 256 pattern: '.*\S.*' - action: + source_id: type: string minLength: 1 - maxLength: 8000 + maxLength: 256 pattern: '.*\S.*' - outcome: + receiver: type: string minLength: 1 - maxLength: 8000 + maxLength: 256 pattern: '.*\S.*' - lesson: + status: + $ref: "#/components/schemas/HandoffReceiptStatus" + selection: + $ref: "#/components/schemas/HandoffAcknowledgementSelection" + receiver_checks: + $ref: "#/components/schemas/ReceiverChecks" + nullable: true + prepared: + $ref: "#/components/schemas/PreparedHandoff" + nullable: true + revision: + $ref: "#/components/schemas/ArtifactReference" + nullable: true + message: type: string minLength: 1 - maxLength: 8000 + maxLength: 8192 pattern: '.*\S.*' - SkillArtifact: + nullable: true + HandoffAcknowledgement: type: object additionalProperties: false - required: [artifact, content, source_refs, artifact_refs] + required: [resolution, receipt] properties: - artifact: - $ref: "#/components/schemas/ArtifactReference" - content: - $ref: "#/components/schemas/SkillProposal" - source_refs: - type: array - items: - $ref: "#/components/schemas/SourceReference" - artifact_refs: - type: array - items: - $ref: "#/components/schemas/ArtifactReference" - SkillProposal: + resolution: + $ref: "#/components/schemas/HandoffResolution" + receipt: + $ref: "#/components/schemas/WorkSourceReceipt" + TaskOutcomeStatus: + type: string + enum: [succeeded, partial, blocked, failed, cancelled, unknown] + TaskCheckStatus: + type: string + enum: [passed, failed, skipped, timed_out, unavailable, cancelled, unknown] + TaskCheck: type: object additionalProperties: false - required: [name, description, instructions, validation] + required: [name, status, basis, evidence] properties: name: type: string minLength: 1 - maxLength: 128 - pattern: '^\S(?:.*\S)?$' - description: - type: string - minLength: 1 - maxLength: 2000 - pattern: '^\S(?:.*\S)?$' - instructions: + maxLength: 8192 + pattern: '.*\S.*' + status: + $ref: "#/components/schemas/TaskCheckStatus" + details: type: string minLength: 1 - maxLength: 32000 + maxLength: 8192 pattern: '.*\S.*' - validation: + nullable: true + basis: + $ref: "#/components/schemas/WorkClaimBasis" + evidence: type: array - minItems: 1 maxItems: 32 items: - $ref: "#/components/schemas/SkillValidationItem" - SkillValidationItem: - type: string - minLength: 1 - maxLength: 2000 - pattern: '^\S(?:.*\S)?$' - ExternalSkillRegistration: + $ref: "#/components/schemas/HandoffCitation" + TaskOutcome: type: object additionalProperties: false - required: - - external_skill_id - - provider - - agent_kind - - host_id - - installation_scope - - locator - - fingerprint - - name - - description + required: [schema, trust, objective, status, summary, observations, checks, produced_artifacts, remaining_work] properties: - external_skill_id: - type: string - minLength: 1 - maxLength: 128 - pattern: '^[\x21-\x7E]+$' - provider: - type: string - enum: [codex, claude_code] - agent_kind: - type: string - enum: [codex, claude_code] - host_id: - type: string - minLength: 1 - maxLength: 128 - pattern: '^\S(?:.*\S)?$' - installation_scope: - $ref: "#/components/schemas/ExternalSkillInstallationScope" - locator: - type: string - minLength: 1 - maxLength: 2000 - pattern: '^\S(?:.*\S)?$' - description: Host-local locator; not a cross-Agent or cross-host contract. - fingerprint: + schema: type: string - pattern: '^[0-9a-f]{64}$' - name: + enum: [powercontext.task-outcome.v1] + trust: type: string - minLength: 1 - maxLength: 128 - pattern: '^\S(?:.*\S)?$' - description: + enum: [untrusted_observation] + objective: type: string minLength: 1 - maxLength: 2000 - pattern: '^\S(?:.*\S)?$' - ExternalSkillResolution: - type: object - additionalProperties: false - required: [registration, status, entrypoint] - properties: - registration: - $ref: "#/components/schemas/ExternalSkillRegistration" + maxLength: 8192 + pattern: '.*\S.*' status: - $ref: "#/components/schemas/ExternalSkillResolutionStatus" - entrypoint: + $ref: "#/components/schemas/TaskOutcomeStatus" + summary: type: string + minLength: 1 + maxLength: 8192 + pattern: '.*\S.*' + handoff_receipt_ref: + $ref: "#/components/schemas/SourceReference" nullable: true - description: Host-local SKILL.md path; present only when the exact fingerprint is available. - ScanExternalSkillsResponse: - type: object - additionalProperties: false - required: [registrations, skipped] - properties: - registrations: + observations: type: array + minItems: 1 + maxItems: 64 items: - $ref: "#/components/schemas/ExternalSkillRegistration" - skipped: - type: integer - minimum: 0 - ListExternalSkillsResponse: - type: object - additionalProperties: false - required: [skills] - properties: - skills: + $ref: "#/components/schemas/WorkClaim" + checks: type: array + maxItems: 64 items: - $ref: "#/components/schemas/ExternalSkillResolution" - ErrorDetail: - type: object - additionalProperties: false - required: [code, message, details] - properties: - code: - type: string - message: - type: string - details: - type: object - additionalProperties: true - nullable: true - ErrorResponse: - type: object - additionalProperties: false - required: [error] - properties: - error: - $ref: "#/components/schemas/ErrorDetail" - FlushMemoryRequest: + $ref: "#/components/schemas/TaskCheck" + produced_artifacts: + type: array + maxItems: 32 + items: + $ref: "#/components/schemas/ArtifactReference" + remaining_work: + type: array + maxItems: 64 + items: + type: string + minLength: 1 + maxLength: 8192 + pattern: '.*\S.*' + RecordTaskOutcomeRequest: type: object additionalProperties: false - required: [scope_id] + required: [scope_id, source_id, outcome] properties: scope_id: type: string minLength: 1 maxLength: 256 pattern: '.*\S.*' - FlushMemoryResponse: - type: object - additionalProperties: false - required: [status, previous_cursor, current_cursor, high_watermark, processed_source_count] - properties: - status: - $ref: "#/components/schemas/FlushStatus" - previous_cursor: - type: integer - minimum: 0 - current_cursor: - type: integer - minimum: 0 - high_watermark: - type: integer - minimum: 0 - processed_source_count: - type: integer - minimum: 0 - memory: - $ref: "#/components/schemas/ArtifactReference" - nullable: true - GetMemoryEntryRequest: - type: object - additionalProperties: false - required: [scope_id, citation] - properties: - scope_id: + source_id: type: string minLength: 1 maxLength: 256 pattern: '.*\S.*' - citation: - $ref: "#/components/schemas/MemoryCitation" - GetArtifactCandidateRequest: + outcome: + $ref: "#/components/schemas/TaskOutcome" + CaptureContentSourceRequest: type: object additionalProperties: false - required: [scope_id, candidate_id] + required: [scope_id, source_id, content] properties: scope_id: type: string minLength: 1 maxLength: 256 pattern: '.*\S.*' - candidate_id: + source_id: type: string minLength: 1 - maxLength: 128 - pattern: '^[\x21-\x7E]+$' - GetExperienceRequest: + maxLength: 256 + content: + type: string + minLength: 1 + maxLength: 200000 + metadata: + type: object + additionalProperties: true + nullable: true + CaptureContentSourceResponse: + type: object + additionalProperties: false + required: [status, source, position] + properties: + status: + $ref: "#/components/schemas/CaptureStatus" + source: + $ref: "#/components/schemas/SourceReference" + position: + type: integer + minimum: 1 + CommitHandoffRequest: type: object additionalProperties: false - required: [scope_id, artifact] + required: [scope_id, handoff] properties: scope_id: type: string minLength: 1 maxLength: 256 pattern: '.*\S.*' - artifact: + handoff: + $ref: "#/components/schemas/PreparedHandoff" + CommittedHandoff: + type: object + additionalProperties: false + required: [reference, content, source_refs, artifact_refs] + properties: + reference: $ref: "#/components/schemas/ArtifactReference" - GetSkillRequest: + content: + $ref: "#/components/schemas/HandoffContent" + source_refs: + type: array + items: + $ref: "#/components/schemas/SourceReference" + artifact_refs: + type: array + items: + $ref: "#/components/schemas/ArtifactReference" + ContinueHandoffRequest: type: object additionalProperties: false - required: [scope_id, artifact] + required: [scope_id, selection] properties: scope_id: type: string minLength: 1 maxLength: 256 pattern: '.*\S.*' - artifact: + selection: + $ref: "#/components/schemas/HandoffSelection" + prepared: + $ref: "#/components/schemas/PreparedHandoff" + nullable: true + revision: $ref: "#/components/schemas/ArtifactReference" - CreateHandoffReportProjectRequest: + nullable: true + FinalizeHandoffRequest: type: object additionalProperties: false - required: [project_key, title] + required: [scope_id, draft] properties: - project_key: - type: string - minLength: 1 - maxLength: 64 - title: - type: string - minLength: 1 - maxLength: 256 - description: - type: string - maxLength: 2000 - nullable: true - default_locale: - $ref: "#/components/schemas/ReportLocale" - default: zh-CN - timezone: + scope_id: type: string minLength: 1 maxLength: 256 - default: UTC - ListHandoffReportProjectsRequest: - type: object - additionalProperties: false - properties: - cursor: - type: string - nullable: true - limit: - type: integer - minimum: 1 - maximum: 100 - default: 50 - include_archived: - type: boolean - default: false - GetHandoffReportProjectRequest: + pattern: '.*\S.*' + draft: + $ref: "#/components/schemas/HandoffDraft" + HandoffArtifactCitation: type: object additionalProperties: false - required: [project_id] + required: [kind, artifact_ref] properties: - project_id: + kind: type: string - minLength: 1 - maxLength: 256 - UpdateHandoffReportProjectRequest: + enum: [artifact] + artifact_ref: + $ref: "#/components/schemas/ArtifactReference" + HandoffActivation: type: object additionalProperties: false - required: [project, expected_version] + required: [status, boundary_source, previous_position, current_position, draft] properties: - project: - $ref: "#/components/schemas/ProjectDescriptor" - expected_version: + status: + $ref: "#/components/schemas/HandoffActivationStatus" + boundary_source: + $ref: "#/components/schemas/SourceReference" + previous_position: type: integer - minimum: 1 - RegisterHandoffReportWorkstreamRequest: + minimum: 0 + current_position: + type: integer + minimum: 0 + draft: + $ref: "#/components/schemas/HandoffDraft" + nullable: true + HandoffCitation: + oneOf: + - $ref: "#/components/schemas/HandoffSourceCitation" + - $ref: "#/components/schemas/HandoffArtifactCitation" + - $ref: "#/components/schemas/HandoffMemoryCitation" + discriminator: + propertyName: kind + mapping: + source: "#/components/schemas/HandoffSourceCitation" + artifact: "#/components/schemas/HandoffArtifactCitation" + memory: "#/components/schemas/HandoffMemoryCitation" + HandoffContent: type: object additionalProperties: false - required: [project_id, scope_id, title, kind] + required: [schema, objective, state, disposition, next_action, omissions] properties: - project_id: - type: string - minLength: 1 - maxLength: 256 - scope_id: - type: string - minLength: 1 - maxLength: 256 - key: - type: string - minLength: 1 - maxLength: 64 - nullable: true - title: + schema: + $ref: "#/components/schemas/HandoffSchema" + objective: type: string minLength: 1 - maxLength: 256 - kind: - $ref: "#/components/schemas/WorkstreamKind" - catalog_state: - $ref: "#/components/schemas/ReportCatalogState" - default: included - external_refs: + maxLength: 8192 + pattern: '.*\S.*' + state: type: array - maxItems: 32 + minItems: 1 + maxItems: 64 items: - $ref: "#/components/schemas/HandoffReportExternalReference" - default: [] - labels: + $ref: "#/components/schemas/HandoffStatement" + disposition: + $ref: "#/components/schemas/HandoffDisposition" + next_action: + $ref: "#/components/schemas/HandoffStatement" + nullable: true + omissions: type: array - maxItems: 32 + maxItems: 64 items: - type: string - minLength: 1 - maxLength: 128 - default: [] - ListHandoffReportWorkstreamsRequest: + $ref: "#/components/schemas/HandoffOmission" + HandoffDraft: type: object additionalProperties: false - required: [project_id] + required: [objective, state, disposition, next_action, omissions] properties: - project_id: + objective: type: string minLength: 1 - maxLength: 256 - cursor: - type: string + maxLength: 8192 + pattern: '.*\S.*' + state: + type: array + minItems: 1 + maxItems: 64 + items: + $ref: "#/components/schemas/HandoffStatement" + disposition: + $ref: "#/components/schemas/HandoffDisposition" + next_action: + $ref: "#/components/schemas/HandoffStatement" nullable: true - limit: - type: integer - minimum: 1 - maximum: 100 - default: 50 - include_archived: - type: boolean - default: false - UpdateHandoffReportWorkstreamRequest: + omissions: + type: array + maxItems: 64 + items: + $ref: "#/components/schemas/HandoffOmission" + HandoffEvidenceCheck: type: object additionalProperties: false - required: [workstream, expected_version] + required: [claim, state_index, status, unavailable_evidence] properties: - workstream: - $ref: "#/components/schemas/WorkstreamDescriptor" - expected_version: + claim: + $ref: "#/components/schemas/HandoffClaim" + state_index: type: integer - minimum: 1 - GetHandoffReportRequest: + minimum: 0 + nullable: true + status: + $ref: "#/components/schemas/HandoffEvidenceStatus" + unavailable_evidence: + type: array + maxItems: 32 + items: + $ref: "#/components/schemas/HandoffCitation" + HandoffMemoryCitation: type: object additionalProperties: false - required: [scope_id] + required: [kind, memory_citation] properties: - scope_id: + kind: type: string - minLength: 1 - maxLength: 256 - project_id: + enum: [memory] + memory_citation: + $ref: "#/components/schemas/MemoryCitation" + HandoffOmission: + type: object + additionalProperties: false + required: [text, citation] + properties: + text: type: string minLength: 1 - maxLength: 256 + maxLength: 8192 + pattern: '.*\S.*' + citation: + $ref: "#/components/schemas/HandoffCitation" + nullable: true + HandoffResolution: + type: object + additionalProperties: false + required: + [trust, status, scope_id, content, selection, selected_revision, current_revision, evidence_checks] + properties: + trust: + type: string + enum: [untrusted_history] + status: + $ref: "#/components/schemas/HandoffResolutionStatus" + scope_id: + type: string + content: + $ref: "#/components/schemas/HandoffContent" nullable: true - deprecated: true - description: Retained for wire compatibility and ignored when generating a scope report. - locale: - $ref: "#/components/schemas/ReportLocale" + selection: + $ref: "#/components/schemas/HandoffSelection" nullable: true - include_evidence_checks: - type: boolean - default: true - format: - $ref: "#/components/schemas/ReportFormat" - default: markdown - include_archived: - type: boolean - default: false - download: - type: boolean - default: false - period: - $ref: "#/components/schemas/HandoffReportPeriodRequest" + selected_revision: + $ref: "#/components/schemas/ArtifactReference" + nullable: true + current_revision: + $ref: "#/components/schemas/ArtifactReference" nullable: true - ListHandoffReportKnownScopesRequest: + evidence_checks: + type: array + maxItems: 65 + items: + $ref: "#/components/schemas/HandoffEvidenceCheck" + HandoffSourceCitation: + type: object + additionalProperties: false + required: [kind, source_ref] + properties: + kind: + type: string + enum: [source] + source_ref: + $ref: "#/components/schemas/SourceReference" + HandoffStatement: type: object additionalProperties: false + required: [text, citations] properties: - cursor: + text: type: string - nullable: true - limit: - type: integer - minimum: 1 - maximum: 100 - default: 50 - KnownHandoffScope: + minLength: 1 + maxLength: 8192 + pattern: '.*\S.*' + citations: + type: array + minItems: 1 + maxItems: 32 + items: + $ref: "#/components/schemas/HandoffCitation" + PrepareHandoffRequest: type: object additionalProperties: false - required: [scope_id] + required: [scope_id, objective, evidence] properties: scope_id: type: string minLength: 1 maxLength: 256 - KnownHandoffScopePage: - type: object - additionalProperties: false - required: [items] - properties: - items: + pattern: '.*\S.*' + objective: + type: string + minLength: 1 + maxLength: 8192 + pattern: '.*\S.*' + evidence: type: array + minItems: 1 + maxItems: 32 items: - $ref: "#/components/schemas/KnownHandoffScope" - next_cursor: - type: string - nullable: true - HandoffReportPeriodRequest: + $ref: "#/components/schemas/HandoffCitation" + max_bytes: + type: integer + minimum: 512 + maximum: 32768 + default: 8000 + PreparedHandoff: type: object additionalProperties: false - required: [start, end] + required: [schema, scope_id, base, content] properties: - start: - type: string - format: date-time - end: - type: string - format: date-time - timezone: + schema: + $ref: "#/components/schemas/PreparedHandoffSchema" + scope_id: type: string - minLength: 1 - maxLength: 256 + base: + $ref: "#/components/schemas/ArtifactReference" nullable: true - compare_to_previous_period: - type: boolean - default: false - HandoffReportResponse: + content: + $ref: "#/components/schemas/HandoffContent" + PreparedContext: type: object additionalProperties: false - required: [format, report, markdown, selection_digest, report_digest] + required: [schema, status, content, content_bytes] properties: - format: - $ref: "#/components/schemas/ReportFormat" - report: - type: object - additionalProperties: true - nullable: true - markdown: + schema: + $ref: "#/components/schemas/PreparedContextSchema" + status: + $ref: "#/components/schemas/PreparedContextStatus" + content: type: string nullable: true - selection_digest: - type: string - pattern: '^sha256:[0-9a-f]{64}$' - report_digest: - type: string - pattern: '^sha256:[0-9a-f]{64}$' - ReportActivitySource: - type: string - enum: [handoff_observation, git_commit, git_worktree, coding_session, other] - ReportTimeBasis: - type: string - enum: [source_reported, host_observed, first_seen, current_only, unknown] - HandoffReportActivityAgent: + content_bytes: + type: integer + minimum: 0 + EntryChange: type: object additionalProperties: false + required: [op, entry_id, from_entry_version_id, to_entry_version_id, reason] properties: - provider: + op: + $ref: "#/components/schemas/EntryChangeOperation" + entry_id: type: string minLength: 1 - maxLength: 64 - nullable: true - label: + maxLength: 128 + pattern: '^[\x21-\x7E]+$' + from_entry_version_id: type: string minLength: 1 maxLength: 128 + pattern: '^[\x21-\x7E]+$' nullable: true - HandoffReportActivityVcsContext: - type: object - additionalProperties: false - properties: - branch: + to_entry_version_id: type: string minLength: 1 - maxLength: 256 + maxLength: 128 + pattern: '^[\x21-\x7E]+$' nullable: true - head_revision: + reason: type: string - minLength: 1 - maxLength: 256 nullable: true - RecordHandoffReportActivityRequest: + ExperienceArtifact: + type: object + additionalProperties: false + required: [artifact, content, source_refs, artifact_refs] + properties: + artifact: + $ref: "#/components/schemas/ArtifactReference" + content: + $ref: "#/components/schemas/ExperienceProposal" + source_refs: + type: array + items: + $ref: "#/components/schemas/SourceReference" + artifact_refs: + type: array + items: + $ref: "#/components/schemas/ArtifactReference" + ExperienceProposal: type: object additionalProperties: false - required: [project_id, source, source_event_id, time_basis] + required: [situation, action, outcome, lesson] properties: - project_id: + situation: type: string minLength: 1 - maxLength: 256 - scope_id: + maxLength: 8000 + pattern: '.*\S.*' + action: type: string minLength: 1 - maxLength: 256 - nullable: true - source: - $ref: "#/components/schemas/ReportActivitySource" - source_event_id: + maxLength: 8000 + pattern: '.*\S.*' + outcome: type: string minLength: 1 - maxLength: 256 - source_ref: - $ref: "#/components/schemas/HandoffReportExternalReference" - nullable: true - occurred_at: + maxLength: 8000 + pattern: '.*\S.*' + lesson: type: string - format: date-time - nullable: true - time_basis: - $ref: "#/components/schemas/ReportTimeBasis" - title: + minLength: 1 + maxLength: 8000 + pattern: '.*\S.*' + SkillArtifact: + type: object + additionalProperties: false + required: [artifact, content, source_refs, artifact_refs] + properties: + artifact: + $ref: "#/components/schemas/ArtifactReference" + content: + $ref: "#/components/schemas/SkillProposal" + source_refs: + type: array + items: + $ref: "#/components/schemas/SourceReference" + artifact_refs: + type: array + items: + $ref: "#/components/schemas/ArtifactReference" + SkillProposal: + type: object + additionalProperties: false + required: [name, description, instructions, validation] + properties: + name: type: string minLength: 1 - maxLength: 256 - nullable: true - summary: + maxLength: 128 + pattern: '^\S(?:.*\S)?$' + description: type: string minLength: 1 maxLength: 2000 - nullable: true - agent: - $ref: "#/components/schemas/HandoffReportActivityAgent" - nullable: true - session_id: + pattern: '^\S(?:.*\S)?$' + instructions: type: string minLength: 1 - maxLength: 256 - nullable: true - vcs_context: - $ref: "#/components/schemas/HandoffReportActivityVcsContext" - nullable: true - evidence_refs: + maxLength: 32000 + pattern: '.*\S.*' + validation: type: array + minItems: 1 maxItems: 32 items: - $ref: "#/components/schemas/HandoffReportExternalReference" - default: [] - HandoffReportActivity: + $ref: "#/components/schemas/SkillValidationItem" + SkillValidationItem: + type: string + minLength: 1 + maxLength: 2000 + pattern: '^\S(?:.*\S)?$' + ExternalSkillRegistration: type: object additionalProperties: false - required: [schema, event_id, project_id, scope_id, source, source_event_id, source_ref, occurred_at, observed_at, time_basis, title, summary, agent, session_id, vcs_context, evidence_refs, trust] + required: + - external_skill_id + - provider + - agent_kind + - host_id + - installation_scope + - locator + - fingerprint + - name + - description properties: - schema: - type: string - enum: [powercontext.handoff-report-activity.v1] - event_id: - type: string - minLength: 1 - maxLength: 256 - project_id: - type: string - minLength: 1 - maxLength: 256 - scope_id: - type: string - minLength: 1 - maxLength: 256 - nullable: true - source: - $ref: "#/components/schemas/ReportActivitySource" - source_event_id: + external_skill_id: type: string minLength: 1 - maxLength: 256 - source_ref: - $ref: "#/components/schemas/HandoffReportExternalReference" - nullable: true - occurred_at: + maxLength: 128 + pattern: '^[\x21-\x7E]+$' + provider: type: string - format: date-time - nullable: true - observed_at: + enum: [codex, claude_code] + agent_kind: type: string - format: date-time - time_basis: - $ref: "#/components/schemas/ReportTimeBasis" - title: + enum: [codex, claude_code] + host_id: type: string minLength: 1 - maxLength: 256 - nullable: true - summary: + maxLength: 128 + pattern: '^\S(?:.*\S)?$' + installation_scope: + $ref: "#/components/schemas/ExternalSkillInstallationScope" + locator: type: string minLength: 1 maxLength: 2000 - nullable: true - agent: - $ref: "#/components/schemas/HandoffReportActivityAgent" - nullable: true - session_id: + pattern: '^\S(?:.*\S)?$' + description: Host-local locator; not a cross-Agent or cross-host contract. + fingerprint: + type: string + pattern: '^[0-9a-f]{64}$' + name: type: string minLength: 1 - maxLength: 256 - nullable: true - vcs_context: - $ref: "#/components/schemas/HandoffReportActivityVcsContext" - nullable: true - evidence_refs: - type: array - maxItems: 32 - items: - $ref: "#/components/schemas/HandoffReportExternalReference" - trust: + maxLength: 128 + pattern: '^\S(?:.*\S)?$' + description: type: string - enum: [untrusted_observation] - StoredHandoffReportActivity: + minLength: 1 + maxLength: 2000 + pattern: '^\S(?:.*\S)?$' + ExternalSkillResolution: type: object additionalProperties: false - required: [cursor, event] + required: [registration, status, entrypoint] properties: - cursor: - type: integer - minimum: 1 - event: - $ref: "#/components/schemas/HandoffReportActivity" - ListHandoffReportActivitiesRequest: + registration: + $ref: "#/components/schemas/ExternalSkillRegistration" + status: + $ref: "#/components/schemas/ExternalSkillResolutionStatus" + entrypoint: + type: string + nullable: true + description: Host-local SKILL.md path; present only when the exact fingerprint is available. + ScanExternalSkillsResponse: type: object additionalProperties: false - required: [project_id] + required: [registrations, skipped] properties: - project_id: - type: string - minLength: 1 - maxLength: 256 - period_start: - type: string - format: date-time - nullable: true - period_end: - type: string - format: date-time - nullable: true - sources: + registrations: type: array - maxItems: 5 items: - $ref: "#/components/schemas/ReportActivitySource" - nullable: true - after_cursor: - type: integer - minimum: 0 - default: 0 - through_cursor: + $ref: "#/components/schemas/ExternalSkillRegistration" + skipped: type: integer minimum: 0 - nullable: true - limit: - type: integer - minimum: 1 - maximum: 100 - default: 50 - HandoffReportActivityPage: + ListExternalSkillsResponse: type: object additionalProperties: false - required: [items, next_cursor, high_watermark] + required: [skills] properties: - items: + skills: type: array - maxItems: 100 items: - $ref: "#/components/schemas/HandoffReportActivity" - next_cursor: - type: integer - minimum: 1 - nullable: true - high_watermark: - type: integer - minimum: 0 - PurgeHandoffReportActivitiesRequest: + $ref: "#/components/schemas/ExternalSkillResolution" + ErrorDetail: type: object additionalProperties: false - required: [project_id, observed_before] + required: [code, message, details] properties: - project_id: + code: type: string - minLength: 1 - maxLength: 256 - observed_before: + message: type: string - format: date-time - PurgeHandoffReportActivitiesResponse: + details: + type: object + additionalProperties: true + nullable: true + ErrorResponse: type: object additionalProperties: false - required: [deleted_count] + required: [error] properties: - deleted_count: - type: integer - minimum: 0 - HandoffReportRepositoryRef: + error: + $ref: "#/components/schemas/ErrorDetail" + FlushMemoryRequest: type: object additionalProperties: false - required: [provider, repository_id, normalized_remote, subpath] + required: [scope_id] properties: - provider: - type: string - enum: [github, gitlab, local, other] - repository_id: + scope_id: type: string minLength: 1 maxLength: 256 - nullable: true - normalized_remote: - type: string - minLength: 1 - maxLength: 2048 - nullable: true - subpath: - type: string - minLength: 1 - maxLength: 1024 - nullable: true - HandoffReportWorkspaceBinding: + pattern: '.*\S.*' + FlushMemoryResponse: type: object additionalProperties: false - required: [schema, workspace_instance_id, project_id, repository_ref, state, confirmed_at, version] + required: [status, previous_cursor, current_cursor, high_watermark, processed_source_count] properties: - schema: - type: string - enum: [powercontext.workspace-binding.v1] - workspace_instance_id: - type: string - minLength: 1 - maxLength: 256 - project_id: - type: string - minLength: 1 - maxLength: 256 - repository_ref: - $ref: "#/components/schemas/HandoffReportRepositoryRef" - state: - type: string - enum: [confirmed, detached] - confirmed_at: - type: string - format: date-time - version: + status: + $ref: "#/components/schemas/FlushStatus" + previous_cursor: type: integer - minimum: 1 - GetHandoffReportWorkspaceRequest: + minimum: 0 + current_cursor: + type: integer + minimum: 0 + high_watermark: + type: integer + minimum: 0 + processed_source_count: + type: integer + minimum: 0 + memory: + $ref: "#/components/schemas/ArtifactReference" + nullable: true + GetMemoryEntryRequest: type: object additionalProperties: false - required: [workspace_instance_id] + required: [scope_id, citation] properties: - workspace_instance_id: + scope_id: type: string minLength: 1 maxLength: 256 - AttachHandoffReportWorkspaceRequest: + pattern: '.*\S.*' + citation: + $ref: "#/components/schemas/MemoryCitation" + GetArtifactCandidateRequest: type: object additionalProperties: false - required: [workspace_instance_id, project_id, repository_ref, expected_version] + required: [scope_id, candidate_id] properties: - workspace_instance_id: + scope_id: type: string minLength: 1 maxLength: 256 - project_id: + pattern: '.*\S.*' + candidate_id: type: string minLength: 1 - maxLength: 256 - repository_ref: - $ref: "#/components/schemas/HandoffReportRepositoryRef" - expected_version: - type: integer - minimum: 1 - nullable: true - DetachHandoffReportWorkspaceRequest: + maxLength: 128 + pattern: '^[\x21-\x7E]+$' + GetExperienceRequest: type: object additionalProperties: false - required: [workspace_instance_id, expected_version] + required: [scope_id, artifact] properties: - workspace_instance_id: + scope_id: type: string minLength: 1 maxLength: 256 - expected_version: - type: integer - minimum: 1 - ProjectDescriptor: + pattern: '.*\S.*' + artifact: + $ref: "#/components/schemas/ArtifactReference" + GetSkillRequest: type: object additionalProperties: false - required: [schema, project_id, project_key, title, description, default_locale, timezone, catalog_state, version] + required: [scope_id, artifact] properties: - schema: - type: string - enum: [powercontext.project.v1] - project_id: - type: string - minLength: 1 - maxLength: 256 - project_key: - type: string - minLength: 1 - maxLength: 64 - title: - type: string - minLength: 1 - maxLength: 256 - description: - type: string - maxLength: 2000 - nullable: true - default_locale: - $ref: "#/components/schemas/ReportLocale" - timezone: + scope_id: type: string minLength: 1 maxLength: 256 - catalog_state: - $ref: "#/components/schemas/ReportCatalogState" - version: - type: integer - minimum: 1 - ProjectPage: + pattern: '.*\S.*' + artifact: + $ref: "#/components/schemas/ArtifactReference" + GetHandoffReportRequest: type: object additionalProperties: false - required: [items, next_cursor] + required: [selection] properties: - items: - type: array - maxItems: 100 - items: - $ref: "#/components/schemas/ProjectDescriptor" - next_cursor: - type: string - nullable: true - WorkstreamDescriptor: + selection: + $ref: "#/components/schemas/ScopeSelection" + format: + $ref: "#/components/schemas/ReportFormat" + default: json + download: + type: boolean + default: false + HandoffReportResponse: type: object additionalProperties: false - required: [schema, scope_id, project_id, key, title, kind, catalog_state, external_refs, labels, version] + required: [format, report, markdown, selection_digest, report_digest] properties: - schema: - type: string - enum: [powercontext.workstream.v1] - scope_id: - type: string - minLength: 1 - maxLength: 256 - project_id: - type: string - minLength: 1 - maxLength: 256 - key: - type: string - maxLength: 64 + format: + $ref: "#/components/schemas/ReportFormat" + report: + type: object + additionalProperties: true nullable: true - title: - type: string - minLength: 1 - maxLength: 256 - kind: - $ref: "#/components/schemas/WorkstreamKind" - catalog_state: - $ref: "#/components/schemas/ReportCatalogState" - external_refs: - type: array - maxItems: 32 - items: - $ref: "#/components/schemas/HandoffReportExternalReference" - labels: - type: array - maxItems: 32 - items: - type: string - minLength: 1 - maxLength: 128 - version: - type: integer - minimum: 1 - WorkstreamPage: - type: object - additionalProperties: false - required: [items, next_cursor] - properties: - items: - type: array - maxItems: 100 - items: - $ref: "#/components/schemas/WorkstreamDescriptor" - next_cursor: + markdown: type: string nullable: true - HandoffReportExternalReference: - type: object - additionalProperties: false - required: [kind, provider, external_id, url] - properties: - kind: - type: string - enum: [issue, task, pull_request, branch, feature, release, program, other] - provider: - type: string - minLength: 1 - maxLength: 64 - external_id: + selection_digest: type: string - minLength: 1 - maxLength: 256 - url: + pattern: '^sha256:[0-9a-f]{64}$' + report_digest: type: string - maxLength: 2048 - nullable: true - ReportLocale: - type: string - enum: [zh-CN, en] + pattern: '^sha256:[0-9a-f]{64}$' ReportFormat: type: string enum: [json, markdown] - ReportCatalogState: - type: string - enum: [included, archived] - WorkstreamKind: - type: string - enum: [feature, bug, refactor, operations, research, other] HealthResponse: type: object additionalProperties: false diff --git a/scripts/generate_api.py b/scripts/generate_api.py index 364eb1617..3bc865113 100644 --- a/scripts/generate_api.py +++ b/scripts/generate_api.py @@ -25,7 +25,17 @@ from datamodel_code_generator import GenerateConfig, InputFileType, generate from datamodel_code_generator.enums import StrictTypes from datamodel_code_generator.format import CodeFormatter, Formatter, PythonVersion -from fastapi.openapi.models import MediaType, OpenAPI, PathItem, Reference, RequestBody, Response, Schema +from fastapi.openapi.models import ( + MediaType, + OpenAPI, + Parameter, + ParameterInType, + PathItem, + Reference, + RequestBody, + Response, + Schema, +) from fastapi.openapi.models import Operation as OpenAPIOperation from pydantic import JsonValue, TypeAdapter, ValidationError @@ -145,7 +155,8 @@ def _generate_operations( if operation.operationId is None or operation.summary is None: raise ContractGenerationError("operation metadata", path) # noqa: TRY003 operation_id = operation.operationId - request_model = _request_model(operation, schemas) + parameters = _operation_parameters(path_item, operation) + request_model = _request_model(operation, parameters, schemas) if request_model is not None: imports.add(request_model[:2]) @@ -160,10 +171,14 @@ def _generate_operations( operation_id=operation_id, request_model=None if request_model is None else request_model[1], request_location=None if request_model is None else request_model[2], + path_parameters=tuple( + parameter.name for parameter in parameters if parameter.in_ is ParameterInType.path + ), response_model=response_model[1], success_status=success_status, summary=operation.summary, tags=tuple(operation.tags or ()), + scope_mode=_scope_mode(operation), responses={ int(code) if code.isdecimal() else code: _response_metadata(response) for code, response in operation.responses.items() @@ -198,10 +213,12 @@ class Operation(BaseModel, Generic[RequestT, ResponseT]): operation_id: str request_type: type[RequestT] | None request_location: Literal["body", "query"] | None + path_parameters: tuple[str, ...] response_type: type[ResponseT] success_status: int summary: str tags: tuple[str, ...] + scope_mode: Literal["none", "current", "selection"] responses: dict[int | str, dict[str, JsonValue]] @@ -293,6 +310,7 @@ def _with_model_validator_import(source: str) -> str: def _request_model( operation: OpenAPIOperation, + parameters: tuple[Parameter, ...], schemas: dict[str, Schema | Reference], ) -> tuple[str, str, Literal["body", "query"]] | None: request_body = operation.requestBody @@ -302,7 +320,7 @@ def _request_model( module, name = _model_for_json_content(request_body.content, schemas, "request body") return module, name, "body" - if not operation.parameters: + if not any(parameter.in_ is ParameterInType.query for parameter in parameters): return None operation_id = operation.operationId if operation_id is None: @@ -313,6 +331,15 @@ def _request_model( return "powercontext.http._generated.models", query_model, "query" +def _operation_parameters(path_item: PathItem, operation: OpenAPIOperation) -> tuple[Parameter, ...]: + parameters: list[Parameter] = [] + for parameter in (*(path_item.parameters or ()), *(operation.parameters or ())): + if not isinstance(parameter, Parameter): + raise ContractGenerationError("parameter reference", parameter) # noqa: TRY003 + parameters.append(parameter) + return tuple(parameters) + + def _success_response( responses: dict[str, Response | object], path: str, @@ -361,10 +388,12 @@ def _render_operation( operation_id: str, request_model: str | None, request_location: Literal["body", "query"] | None, + path_parameters: tuple[str, ...], response_model: str, success_status: int, summary: str, tags: tuple[str, ...], + scope_mode: Literal["none", "current", "selection"], responses: dict[int | str, dict[str, JsonValue]], ) -> str: request_type = "None" if request_model is None else request_model @@ -374,13 +403,22 @@ def _render_operation( operation_id={operation_id!r}, request_type={request_type}, request_location={request_location!r}, + path_parameters={path_parameters!r}, response_type={response_model}, success_status={success_status}, summary={summary!r}, tags={tags!r}, + scope_mode={scope_mode!r}, responses={pformat(responses, width=100, sort_dicts=False)}, )""" +def _scope_mode(operation: OpenAPIOperation) -> Literal["none", "current", "selection"]: + value = (operation.model_extra or {}).get("x-powercontext-scope-mode", "none") + if value not in {"none", "current", "selection"}: + raise ContractGenerationError("x-powercontext-scope-mode", value) + return value + + if __name__ == "__main__": main() diff --git a/scripts/generate_js_operations.py b/scripts/generate_js_operations.py index 64eec9041..73b599b1d 100644 --- a/scripts/generate_js_operations.py +++ b/scripts/generate_js_operations.py @@ -89,7 +89,8 @@ def parse_operations(doc: dict[str, Any]) -> list[dict[str, Any]]: "method": method.upper(), "path": path, "location": _request_location(body_schema, parameters), - "scope": _operation_has_scope(doc, body_schema, parameters), + "scopeMode": _scope_mode(operation), + "pathParameters": _path_parameters(parameters), }) return rows @@ -112,10 +113,10 @@ def main() -> None: def _render_row(row: dict[str, Any]) -> str: location = "null" if row["location"] is None else f'"{row["location"]}"' - scope = "true" if row["scope"] else "false" + path_parameters = ", ".join(f"'{name}'" for name in row["pathParameters"]) return ( f" {row['operationId']}: {{ method: '{row['method']}', path: '{row['path']}', " - f"location: {location}, scope: {scope} }}," + f"location: {location}, scopeMode: '{row['scopeMode']}', pathParameters: [{path_parameters}] }}," ) @@ -142,20 +143,6 @@ def _deref(doc: dict[str, Any], node: Any, seen: set[str] | None = None) -> Any: return node -def _schema_has_scope(doc: dict[str, Any], schema: Any, seen: set[str] | None = None) -> bool: - resolved = _deref(doc, schema, seen or set()) - if not isinstance(resolved, dict): - return False - properties = resolved.get("properties") - if isinstance(properties, dict) and "scope_id" in properties: - return True - for key in ("allOf", "oneOf", "anyOf"): - parts = resolved.get(key) - if isinstance(parts, list) and any(_schema_has_scope(doc, part, set(seen or set())) for part in parts): - return True - return False - - def _json_body_schema(doc: dict[str, Any], operation: dict[str, Any]) -> Any: body = _deref(doc, operation.get("requestBody")) if not isinstance(body, dict): @@ -187,10 +174,19 @@ def _request_location(body_schema: Any, parameters: list[dict[str, Any]]) -> str return None -def _operation_has_scope(doc: dict[str, Any], body_schema: Any, parameters: list[dict[str, Any]]) -> bool: - if body_schema and _schema_has_scope(doc, body_schema): - return True - return any(parameter.get("in") == "query" and parameter.get("name") == "scope_id" for parameter in parameters) +def _scope_mode(operation: dict[str, Any]) -> str: + value = operation.get("x-powercontext-scope-mode", "none") + if value not in {"none", "current", "selection"}: + raise SystemExit("invalid x-powercontext-scope-mode") # noqa: TRY003 + return value + + +def _path_parameters(parameters: list[dict[str, Any]]) -> list[str]: + return [ + name + for parameter in parameters + if parameter.get("in") == "path" and isinstance(name := parameter.get("name"), str) + ] if __name__ == "__main__": diff --git a/src/powercontext/builtin/artifacts/handoff/service.py b/src/powercontext/builtin/artifacts/handoff/service.py index 8c46dbbd1..4456c20bd 100644 --- a/src/powercontext/builtin/artifacts/handoff/service.py +++ b/src/powercontext/builtin/artifacts/handoff/service.py @@ -16,7 +16,7 @@ from __future__ import annotations -from collections.abc import Iterable +from collections.abc import Callable, Iterable from powercontext.artifacts import ArtifactRef from powercontext.builtin.artifacts.handoff.errors import ( @@ -63,12 +63,14 @@ def __init__( artifact_id: str, backend: HandoffBackend, evidence_resolver: HandoffEvidenceResolver, + evidence_resolver_for_scope: Callable[[str], HandoffEvidenceResolver] | None = None, generation_pipeline: HandoffGenerationPipeline | None = None, ) -> None: self.scope_id = scope_id self.artifact_id = artifact_id self._backend = backend self._evidence_resolver = evidence_resolver + self._evidence_resolver_for_scope = evidence_resolver_for_scope self._generation_pipeline = generation_pipeline ArtifactRef(family=Handoff.family, artifact_id=artifact_id, revision=1) @@ -125,9 +127,9 @@ async def latest(self) -> Handoff | None: return await self._backend.latest(self.artifact_id) async def revision(self, reference: ArtifactRef, /) -> Handoff: - """Return one exact committed milestone.""" + """Return one exact local or published Handoff revision.""" - self._require_reference(reference) + self._require_handoff_reference(reference) return await self._backend.get(reference) async def revisions(self) -> tuple[Handoff, ...]: @@ -148,26 +150,31 @@ async def continue_from( ) -> HandoffResolution: """Resolve Handoff content without treating historical claims as current truth.""" - current = await self._backend.latest(self.artifact_id) + evidence_resolver = self._evidence_resolver if isinstance(handoff, PreparedHandoff): + current = await self._backend.latest(self.artifact_id) self._require_prepared(handoff) content = handoff.content selection: HandoffResolutionSelection = "prepared" selected_revision = None else: selected = await self.revision(handoff) + current = await self._backend.latest(selected.artifact_id) content = selected.content selection = "exact" selected_revision = selected.as_ref() + provenance = selected.lineage.publication_source + evidence_resolver = self._resolver_for_scope(self.scope_id if provenance is None else provenance.scope_id) return await self._resolve( content, selection=selection, selected_revision=selected_revision, current=current, + evidence_resolver=evidence_resolver, ) async def continue_latest(self) -> HandoffResolution: - """Resolve the latest milestone after the caller selects the current workstream.""" + """Resolve the latest milestone after the caller selects the current Scope.""" current = await self._backend.latest(self.artifact_id) if current is None: @@ -181,6 +188,7 @@ async def continue_latest(self) -> HandoffResolution: selection="latest", selected_revision=current.as_ref(), current=current, + evidence_resolver=self._evidence_resolver, ) async def _resolve( @@ -190,6 +198,7 @@ async def _resolve( selection: HandoffResolutionSelection, selected_revision: ArtifactRef | None, current: Handoff | None, + evidence_resolver: HandoffEvidenceResolver, ) -> HandoffResolution: return HandoffResolution( status="resolved", @@ -198,9 +207,16 @@ async def _resolve( selection=selection, selected_revision=selected_revision, current_revision=None if current is None else current.as_ref(), - evidence_checks=await self._evidence_checks(content), + evidence_checks=await self._evidence_checks(content, evidence_resolver=evidence_resolver), ) + def _resolver_for_scope(self, scope_id: str) -> HandoffEvidenceResolver: + if scope_id == self.scope_id: + return self._evidence_resolver + if self._evidence_resolver_for_scope is None: + return self._evidence_resolver + return self._evidence_resolver_for_scope(scope_id) + @staticmethod def render( handoff: HandoffDraft | PreparedHandoff | Handoff, @@ -219,9 +235,13 @@ def _require_prepared(self, prepared: PreparedHandoff) -> None: if prepared.scope_id != self.scope_id: raise HandoffScopeMismatchError(self.scope_id, prepared.scope_id) if prepared.base is not None: - self._require_reference(prepared.base) + self._require_lifecycle_reference(prepared.base) + + def _require_handoff_reference(self, reference: ArtifactRef) -> None: + if reference.family != Handoff.family: + raise InvalidHandoffReferenceError(reference) - def _require_reference(self, reference: ArtifactRef) -> None: + def _require_lifecycle_reference(self, reference: ArtifactRef) -> None: if reference.family != Handoff.family or reference.artifact_id != self.artifact_id: raise InvalidHandoffReferenceError(reference) @@ -248,12 +268,18 @@ def _validate_generated_draft(action: PrepareHandoff, draft: object) -> None: if content_bytes > action.max_bytes: raise InvalidHandoffGenerationError("budget") - async def _evidence_checks(self, content: HandoffContent) -> tuple[HandoffEvidenceCheck, ...]: + async def _evidence_checks( + self, + content: HandoffContent, + *, + evidence_resolver: HandoffEvidenceResolver, + ) -> tuple[HandoffEvidenceCheck, ...]: checks = [ await self._check_evidence( statement.citations, claim="state", state_index=index, + evidence_resolver=evidence_resolver, ) for index, statement in enumerate(content.state) ] @@ -262,6 +288,7 @@ async def _evidence_checks(self, content: HandoffContent) -> tuple[HandoffEviden await self._check_evidence( content.next_action.citations, claim="next_action", + evidence_resolver=evidence_resolver, ) ) return tuple(checks) @@ -272,11 +299,12 @@ async def _check_evidence( *, claim: HandoffClaim, state_index: int | None = None, + evidence_resolver: HandoffEvidenceResolver, ) -> HandoffEvidenceCheck: unavailable: list[HandoffCitation] = [] for citation in citations: try: - await self._evidence_resolver.validate(citation) + await evidence_resolver.validate(citation) except HandoffEvidenceUnavailableError: if citation not in unavailable: unavailable.append(citation) diff --git a/src/powercontext/builtin/handoff_report/__init__.py b/src/powercontext/builtin/handoff_report/__init__.py index 16af8671b..873247d2b 100644 --- a/src/powercontext/builtin/handoff_report/__init__.py +++ b/src/powercontext/builtin/handoff_report/__init__.py @@ -12,14 +12,10 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Optional, read-only Handoff Report domain values.""" +"""Scope-based Handoff Report projection.""" -from powercontext.builtin.handoff_report.adapters import RuntimeHandoffReadAdapter, RuntimeWorkContinuityReadAdapter -from powercontext.builtin.handoff_report.application import ( - HandoffReportApplication, - ReportActivityPage, - ReportPeriodInput, -) +from powercontext.builtin.handoff_report.adapters import RuntimeHandoffReadAdapter +from powercontext.builtin.handoff_report.application import HandoffReportApplication from powercontext.builtin.handoff_report.canonical import ( ReportCanonicalizationError, canonical_json_bytes, @@ -28,164 +24,34 @@ selection_digest, selection_envelope, ) -from powercontext.builtin.handoff_report.catalog import HandoffReportCatalog, ProjectIdFactory -from powercontext.builtin.handoff_report.catalog_store import ( - DEFAULT_CATALOG_PAGE_SIZE, - HANDOFF_REPORT_CATALOG_TABLES, - MAX_CATALOG_PAGE_SIZE, - CatalogPage, - ReportCatalogRepository, -) from powercontext.builtin.handoff_report.errors import ( - HandoffReportBusyError, - HandoffReportCatalogArgumentError, HandoffReportError, - HandoffReportEvidenceCheckUnavailableError, HandoffReportInconsistentError, HandoffReportTooLargeError, - InvalidStoredCatalogError, - ProjectConflictError, - ProjectNotFoundError, - ScopeAlreadyGroupedError, - WorkspaceBindingConflictError, - WorkspaceBindingNotFoundError, - WorkstreamConflictError, - WorkstreamNotFoundError, -) -from powercontext.builtin.handoff_report.models import ( - ActivityAgent, - ActivityVcsContext, - CatalogState, - ExternalReference, - ExternalReferenceKind, - GeneratedSummaryTrust, - HandoffReportTrust, - ProjectDescriptor, - ReportActivityEvent, - ReportActivitySource, - ReportActivityTrust, - ReportLocale, - ReportSelectionConsistency, - ReportSelectionEntry, - ReportSelectionStatus, - ReportTimeBasis, - RepositoryProvider, - RepositoryRef, - WorkspaceBinding, - WorkspaceBindingState, - WorkstreamDescriptor, - WorkstreamKind, - activity_sort_key, - normalize_repository_ref, - normalized_sort_text, - selection_sort_key, - workstream_sort_key, ) from powercontext.builtin.handoff_report.rendering import render_markdown from powercontext.builtin.handoff_report.report import ( HandoffReport, - HandoffRevisionSummary, - ReportActivityCoverageStatus, - ReportActivityStatus, - ReportCoverage, - ReportEvidenceChecks, - ReportFormat, - ReportHandoffActivityRelation, - ReportKind, - ReportPeriodComparison, - ReportReportingStatus, - ReportSummary, - ReportWorkStatus, - WorkstreamReport, -) -from powercontext.builtin.handoff_report.selection import select_optimistic_stable_handoffs -from powercontext.builtin.handoff_report.service import HandoffReportService -from powercontext.builtin.handoff_report.workspace import WorkspaceBindingService -from powercontext.builtin.handoff_report.workspace_store import ( - HANDOFF_REPORT_WORKSPACE_BINDINGS_TABLE, - HANDOFF_REPORT_WORKSPACE_TABLES, - WorkspaceBindingRepository, + HandoffReportStatus, + HandoffReportSummary, + ScopeHandoffReport, ) __all__ = [ - "DEFAULT_CATALOG_PAGE_SIZE", - "HANDOFF_REPORT_CATALOG_TABLES", - "HANDOFF_REPORT_WORKSPACE_BINDINGS_TABLE", - "HANDOFF_REPORT_WORKSPACE_TABLES", - "MAX_CATALOG_PAGE_SIZE", - "ActivityAgent", - "ActivityVcsContext", - "CatalogPage", - "CatalogState", - "ExternalReference", - "ExternalReferenceKind", - "GeneratedSummaryTrust", "HandoffReport", "HandoffReportApplication", - "HandoffReportBusyError", - "HandoffReportCatalog", - "HandoffReportCatalogArgumentError", "HandoffReportError", - "HandoffReportEvidenceCheckUnavailableError", "HandoffReportInconsistentError", - "HandoffReportService", + "HandoffReportStatus", + "HandoffReportSummary", "HandoffReportTooLargeError", - "HandoffReportTrust", - "HandoffRevisionSummary", - "InvalidStoredCatalogError", - "ProjectConflictError", - "ProjectDescriptor", - "ProjectIdFactory", - "ProjectNotFoundError", - "ReportActivityCoverageStatus", - "ReportActivityEvent", - "ReportActivityPage", - "ReportActivitySource", - "ReportActivityStatus", - "ReportActivityTrust", "ReportCanonicalizationError", - "ReportCatalogRepository", - "ReportCoverage", - "ReportEvidenceChecks", - "ReportFormat", - "ReportHandoffActivityRelation", - "ReportKind", - "ReportLocale", - "ReportPeriodComparison", - "ReportPeriodInput", - "ReportReportingStatus", - "ReportSelectionConsistency", - "ReportSelectionEntry", - "ReportSelectionStatus", - "ReportSummary", - "ReportTimeBasis", - "ReportWorkStatus", - "RepositoryProvider", - "RepositoryRef", "RuntimeHandoffReadAdapter", - "RuntimeWorkContinuityReadAdapter", - "ScopeAlreadyGroupedError", - "WorkspaceBinding", - "WorkspaceBindingConflictError", - "WorkspaceBindingNotFoundError", - "WorkspaceBindingRepository", - "WorkspaceBindingService", - "WorkspaceBindingState", - "WorkstreamConflictError", - "WorkstreamDescriptor", - "WorkstreamKind", - "WorkstreamNotFoundError", - "WorkstreamReport", - "activity_sort_key", + "ScopeHandoffReport", "canonical_json_bytes", "finalize_digests", - "normalize_repository_ref", - "normalized_sort_text", "render_markdown", "report_digest", - "select_optimistic_stable_handoffs", "selection_digest", "selection_envelope", - "selection_sort_key", - "workstream_sort_key", ] diff --git a/src/powercontext/builtin/handoff_report/adapters.py b/src/powercontext/builtin/handoff_report/adapters.py index d43175cd8..6f617edeb 100644 --- a/src/powercontext/builtin/handoff_report/adapters.py +++ b/src/powercontext/builtin/handoff_report/adapters.py @@ -12,19 +12,14 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Adapters from existing Runtime behavior into Handoff Report read ports.""" +"""Runtime adapter for read-only Handoff report projection.""" from __future__ import annotations from typing import Protocol from powercontext.artifacts import ArtifactRef -from powercontext.builtin.artifacts.handoff import ( - Handoff, - HandoffEvidenceCheck, -) -from powercontext.builtin.handoff_report.errors import HandoffReportEvidenceCheckUnavailableError -from powercontext.builtin.work import WorkContinuity +from powercontext.builtin.artifacts.handoff import Handoff class _ScopedHandoffReader(Protocol): @@ -32,24 +27,12 @@ async def latest(self) -> Handoff | None: ... async def revision(self, reference: ArtifactRef, /) -> Handoff: ... - async def revisions(self) -> tuple[Handoff, ...]: ... - class _HandoffApplicationReader(Protocol): def for_scope(self, scope_id: str, /) -> _ScopedHandoffReader: ... -class _ScopedWorkReader(Protocol): - async def continuity(self, selected_handoff: ArtifactRef | None = None) -> WorkContinuity: ... - - -class _WorkApplicationReader(Protocol): - def for_scope(self, scope_id: str, /) -> _ScopedWorkReader: ... - - class RuntimeHandoffReadAdapter: - """Use the existing public Runtime Handoff application as a read-only source.""" - def __init__(self, application: _HandoffApplicationReader, /) -> None: self._application = application @@ -59,30 +42,5 @@ async def latest(self, scope_id: str, /) -> Handoff | None: async def get(self, scope_id: str, reference: ArtifactRef, /) -> Handoff: return await self._application.for_scope(scope_id).revision(reference) - async def revisions(self, scope_id: str, /) -> tuple[Handoff, ...]: - return await self._application.for_scope(scope_id).revisions() - - async def check_evidence( - self, - scope_id: str, - reference: ArtifactRef, - /, - ) -> tuple[HandoffEvidenceCheck, ...]: - del scope_id, reference - # The current Runtime exposes evidence checks through Continue only. - # Report must not enter that control flow, so it degrades explicitly - # until an independent read-only capability exists. - raise HandoffReportEvidenceCheckUnavailableError - - -class RuntimeWorkContinuityReadAdapter: - """Project Work continuity through the Runtime's high-level read application.""" - - def __init__(self, application: _WorkApplicationReader, /) -> None: - self._application = application - - async def get(self, scope_id: str, reference: ArtifactRef | None, /) -> WorkContinuity: - return await self._application.for_scope(scope_id).continuity(reference) - -__all__ = ["RuntimeHandoffReadAdapter", "RuntimeWorkContinuityReadAdapter"] +__all__ = ["RuntimeHandoffReadAdapter"] diff --git a/src/powercontext/builtin/handoff_report/application.py b/src/powercontext/builtin/handoff_report/application.py index 0135c4afb..2f5ad4039 100644 --- a/src/powercontext/builtin/handoff_report/application.py +++ b/src/powercontext/builtin/handoff_report/application.py @@ -12,412 +12,71 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Runtime-facing application service for Handoff Report operations.""" +"""Read-only Handoff reports over a resolved Scope selection.""" from __future__ import annotations -import json -from bisect import bisect_right -from collections.abc import Awaitable, Callable -from dataclasses import dataclass -from datetime import UTC, datetime, timedelta -from typing import cast -from zoneinfo import ZoneInfo, ZoneInfoNotFoundError +from datetime import UTC, datetime -from pydantic import JsonValue - -from powercontext.builtin.handoff_report.catalog import HandoffReportCatalog -from powercontext.builtin.handoff_report.catalog_store import ( - DEFAULT_CATALOG_PAGE_SIZE, - CatalogPage, -) -from powercontext.builtin.handoff_report.errors import HandoffReportCatalogArgumentError -from powercontext.builtin.handoff_report.models import ( - CatalogState, - ExternalReference, - ProjectDescriptor, - ReportActivityEvent, - ReportLocale, - RepositoryRef, - WorkspaceBinding, - WorkstreamDescriptor, - WorkstreamKind, -) -from powercontext.builtin.handoff_report.protocols import HandoffReadAdapter, WorkContinuityReadAdapter -from powercontext.builtin.handoff_report.report import HandoffReport, ReportFormat -from powercontext.builtin.handoff_report.repository import ActivityEventRepository, StoredActivityEvent -from powercontext.builtin.handoff_report.service import HandoffReportService -from powercontext.builtin.handoff_report.sqlite import SQLiteActivityEventRepository -from powercontext.builtin.handoff_report.workspace import WorkspaceBindingService -from powercontext.builtin.persistence.database import AsyncDatabase -from powercontext.builtin.sources import validate_scope_id - - -@dataclass(frozen=True, slots=True) -class ReportActivityPage: - """One cursor page plus the frozen current Project high watermark.""" - - items: tuple[ReportActivityEvent, ...] - next_cursor: int | None - high_watermark: int - - -@dataclass(frozen=True, slots=True) -class ReportPeriodInput: - """Explicit half-open period requested by a Report consumer.""" - - start: datetime - end: datetime - timezone: str | None = None - compare_to_previous_period: bool = False - - -@dataclass(frozen=True, slots=True) -class KnownScopePage: - """One cursor page of scopes that contain a committed Handoff.""" - - items: tuple[str, ...] - next_cursor: str | None +from powercontext.artifacts import ArtifactAddress +from powercontext.builtin.handoff_report.canonical import finalize_digests +from powercontext.builtin.handoff_report.errors import HandoffReportInconsistentError +from powercontext.builtin.handoff_report.protocols import HandoffReadAdapter, ScopeSelectionResolver +from powercontext.builtin.handoff_report.report import HandoffReport, HandoffReportSummary, ScopeHandoffReport +from powercontext.builtin.scope.models import ScopeSelection class HandoffReportApplication: - """Coordinate Report-owned persistence with the existing Handoff read port.""" - - def __init__( - self, - database: AsyncDatabase, - handoffs: HandoffReadAdapter, - /, - *, - activities: ActivityEventRepository | None = None, - workspace_bindings: WorkspaceBindingService | None = None, - continuity: WorkContinuityReadAdapter | None = None, - scope_ids: Callable[[], Awaitable[tuple[str, ...]]] | None = None, - ) -> None: - self._database = database - self._catalog = HandoffReportCatalog() - self._activities = SQLiteActivityEventRepository() if activities is None else activities - self._workspace_bindings = WorkspaceBindingService() if workspace_bindings is None else workspace_bindings - self._reports = HandoffReportService(handoffs, continuity=continuity) - self._scope_ids = scope_ids - - async def list_known_scopes( - self, - *, - cursor: str | None = None, - limit: int = DEFAULT_CATALOG_PAGE_SIZE, - ) -> KnownScopePage: - """List exact scope identities backed by a committed Handoff.""" - - if limit < 1 or limit > 100: - raise HandoffReportCatalogArgumentError("limit", "must be between 1 and 100") - if cursor is not None and (not cursor.strip() or cursor != cursor.strip()): - raise HandoffReportCatalogArgumentError("cursor", "must be non-empty trimmed text") - scopes = () if self._scope_ids is None else tuple(sorted(set(await self._scope_ids()))) - start = 0 if cursor is None else bisect_right(scopes, cursor) - items = scopes[start : start + limit] - next_cursor = items[-1] if start + len(items) < len(scopes) else None - return KnownScopePage(items=items, next_cursor=next_cursor) - - async def create_project( - self, - *, - project_key: str, - title: str, - description: str | None = None, - default_locale: ReportLocale = "zh-CN", - timezone: str = "UTC", - effective_at: datetime | None = None, - ) -> ProjectDescriptor: - async with self._database.transaction() as connection: - return await self._catalog.create_project( - connection, - project_key=project_key, - title=title, - description=description, - default_locale=default_locale, - timezone=timezone, - effective_at=effective_at, - ) - - async def get_project(self, project_id: str, /) -> ProjectDescriptor: - async with self._database.transaction() as connection: - return await self._catalog.get_project(connection, project_id) - - async def update_project( - self, - descriptor: ProjectDescriptor, - expected_version: int, - /, - *, - effective_at: datetime | None = None, - ) -> ProjectDescriptor: - async with self._database.transaction() as connection: - return await self._catalog.update_project( - connection, - descriptor, - expected_version, - effective_at=effective_at, - ) - - async def list_projects( - self, - *, - cursor: str | None = None, - limit: int = DEFAULT_CATALOG_PAGE_SIZE, - include_archived: bool = False, - ) -> CatalogPage[ProjectDescriptor]: - async with self._database.transaction() as connection: - return await self._catalog.list_projects( - connection, - cursor=cursor, - limit=limit, - include_archived=include_archived, - ) - - async def register_workstream( - self, - *, - project_id: str, - scope_id: str, - title: str, - kind: WorkstreamKind, - key: str | None = None, - catalog_state: CatalogState = "included", - external_refs: tuple[ExternalReference, ...] = (), - labels: tuple[str, ...] = (), - effective_at: datetime | None = None, - ) -> WorkstreamDescriptor: - async with self._database.transaction() as connection: - return await self._catalog.register_workstream( - connection, - project_id=project_id, - scope_id=scope_id, - title=title, - kind=kind, - key=key, - catalog_state=catalog_state, - external_refs=external_refs, - labels=labels, - effective_at=effective_at, - ) - - async def list_workstreams( - self, - project_id: str, - /, - *, - cursor: str | None = None, - limit: int = DEFAULT_CATALOG_PAGE_SIZE, - include_archived: bool = False, - ) -> CatalogPage[WorkstreamDescriptor]: - async with self._database.transaction() as connection: - return await self._catalog.list_workstreams( - connection, - project_id, - cursor=cursor, - limit=limit, - include_archived=include_archived, - ) - - async def update_workstream( - self, - descriptor: WorkstreamDescriptor, - expected_version: int, - /, - *, - effective_at: datetime | None = None, - ) -> WorkstreamDescriptor: - async with self._database.transaction() as connection: - return await self._catalog.update_workstream( - connection, - descriptor, - expected_version, - effective_at=effective_at, - ) - - async def record_activity(self, event: ReportActivityEvent, /) -> StoredActivityEvent: - """Record an explicit observation without entering the Handoff write path.""" - - async with self._database.transaction() as connection: - await self._catalog.get_project(connection, event.project_id) - return await self._activities.record(connection, event) - - async def list_activities( - self, - project_id: str, - /, - *, - period_start: datetime | None = None, - period_end: datetime | None = None, - sources: tuple[str, ...] | None = None, - after_cursor: int = 0, - through_cursor: int | None = None, - limit: int = DEFAULT_CATALOG_PAGE_SIZE, - ) -> ReportActivityPage: - """Read a stable cursor page from the Report-owned Activity Store.""" - - async with self._database.transaction() as connection: - await self._catalog.get_project(connection, project_id) - high_watermark = await self._activities.high_watermark(connection, project_id) - frozen_cursor = high_watermark if through_cursor is None else through_cursor - stored = await self._activities.list( - connection, - project_id, - period_start=period_start, - period_end=period_end, - sources=sources, - after_cursor=after_cursor, - through_cursor=frozen_cursor, - limit=limit + 1, - ) - has_more = len(stored) > limit - selected = stored[:limit] - return ReportActivityPage( - items=tuple(_activity_event(item) for item in selected), - next_cursor=selected[-1].cursor if has_more and selected else None, - high_watermark=high_watermark, - ) - - async def purge_activities(self, project_id: str, observed_before: datetime, /) -> int: - """Purge only Report-owned Activity rows for one Project.""" - - async with self._database.transaction() as connection: - await self._catalog.get_project(connection, project_id) - return await self._activities.purge(connection, project_id, observed_before) + """Build exact Handoff state without introducing another organization model.""" - async def get_workspace_binding(self, workspace_instance_id: str, /) -> WorkspaceBinding: - async with self._database.transaction() as connection: - return await self._workspace_bindings.get(connection, workspace_instance_id) - - async def attach_workspace_binding( - self, - *, - workspace_instance_id: str, - project_id: str, - repository_ref: RepositoryRef, - expected_version: int | None, - ) -> WorkspaceBinding: - async with self._database.transaction() as connection: - return await self._workspace_bindings.attach( - connection, - workspace_instance_id=workspace_instance_id, - project_id=project_id, - repository_ref=repository_ref, - expected_version=expected_version, - ) - - async def detach_workspace_binding( - self, - workspace_instance_id: str, - expected_version: int, - /, - ) -> WorkspaceBinding: - async with self._database.transaction() as connection: - return await self._workspace_bindings.detach(connection, workspace_instance_id, expected_version) + def __init__(self, scopes: ScopeSelectionResolver, handoffs: HandoffReadAdapter, /) -> None: + self._scopes = scopes + self._handoffs = handoffs async def get_report( self, - scope_id: str, + selection: ScopeSelection, /, *, - locale: ReportLocale | None = None, - include_evidence_checks: bool = True, - report_format: ReportFormat = "markdown", - include_archived: bool = False, - normalized_filters: dict[str, JsonValue] | None = None, - period: ReportPeriodInput | None = None, + generated_at: datetime | None = None, ) -> HandoffReport: - del include_archived - project = _scope_report_project(scope_id) - workstreams = (_scope_report_workstream(scope_id),) - period_values = _normalize_period(project, period) - normalized_period = _normalized_period(period, period_values) - return await self._reports.generate( - project, - workstreams, - locale=locale, - include_evidence_checks=include_evidence_checks, - activities=(), - activity_cursor=0, - activity_coverage="not_configured", - report_format=report_format, - report_kind="handoff" if period is None else "periodic", - normalized_filters={} if normalized_filters is None else normalized_filters, - normalized_period=normalized_period, - period_comparison=None, - ) - - -def _scope_report_project(scope_id: str) -> ProjectDescriptor: - scope = validate_scope_id(scope_id) - return ProjectDescriptor( - project_id="unused", - project_key="unused", - title=scope, - default_locale="zh-CN", - timezone="UTC", - version=1, - ) - - -def _scope_report_workstream(scope_id: str) -> WorkstreamDescriptor: - scope = validate_scope_id(scope_id) - return WorkstreamDescriptor( - scope_id=scope, - project_id="unused", - title=scope, - kind="other", - version=1, - ) - - -def _normalized_period( - period: ReportPeriodInput | None, - values: tuple[datetime, datetime, str] | None, -) -> dict[str, JsonValue] | None: - if values is None: - return None - requested = cast(ReportPeriodInput, period) - start, end, timezone = values - return { - "start": _utc_text(start), - "end": _utc_text(end), - "timezone": timezone, - "compare_to_previous_period": requested.compare_to_previous_period, - } - - -def _activity_event(value: StoredActivityEvent) -> ReportActivityEvent: - return ReportActivityEvent.model_validate_json(json.dumps(value.payload)) - - -def _normalize_period( - project: ProjectDescriptor, - period: ReportPeriodInput | None, -) -> tuple[datetime, datetime, str] | None: - if period is None: - return None - if period.start.tzinfo is None or period.start.utcoffset() is None: - raise HandoffReportCatalogArgumentError("period.start", "must include a UTC offset") - if period.end.tzinfo is None or period.end.utcoffset() is None: - raise HandoffReportCatalogArgumentError("period.end", "must include a UTC offset") - start = period.start.astimezone(UTC) - end = period.end.astimezone(UTC) - if start >= end: - raise HandoffReportCatalogArgumentError("period", "start must precede end") - if end - start > timedelta(days=366): - raise HandoffReportCatalogArgumentError("period", "must not exceed 366 days") - timezone = project.timezone if period.timezone is None else period.timezone - try: - ZoneInfo(timezone) - except ZoneInfoNotFoundError as error: - raise HandoffReportCatalogArgumentError("period.timezone", "must be a recognized IANA timezone") from error - return start, end, timezone - + """Resolve one common selection and freeze each Scope at an exact Handoff revision.""" + + scopes = await self._scopes.resolve_selection(selection) + projected: list[ScopeHandoffReport] = [] + for scope in scopes: + latest = await self._handoffs.latest(scope.scope_id) + if latest is None: + projected.append(ScopeHandoffReport(scope=scope, status="no_handoff")) + continue + + reference = latest.as_ref() + frozen = await self._handoffs.get(scope.scope_id, reference) + if frozen.as_ref() != reference: + raise HandoffReportInconsistentError(scope.scope_id) + projected.append( + ScopeHandoffReport( + scope=scope, + status=frozen.content.disposition, + handoff=ArtifactAddress(scope_id=scope.scope_id, artifact=reference), + content=frozen.content, + ) + ) -def _utc_text(value: datetime) -> str: - return value.astimezone(UTC).isoformat(timespec="microseconds").replace("+00:00", "Z") + entries = tuple(projected) + report = HandoffReport( + selection=selection, + scope_ids=tuple(scope.scope_id for scope in scopes), + generated_at=datetime.now(UTC) if generated_at is None else generated_at, + summary=HandoffReportSummary( + continuable_count=sum(entry.status == "continuable" for entry in entries), + blocked_count=sum(entry.status == "blocked" for entry in entries), + complete_count=sum(entry.status == "complete" for entry in entries), + no_handoff_count=sum(entry.status == "no_handoff" for entry in entries), + ), + scopes=entries, + ) + return finalize_digests(report) -__all__ = ["HandoffReportApplication", "KnownScopePage", "ReportActivityPage", "ReportPeriodInput"] +__all__ = ["HandoffReportApplication"] diff --git a/src/powercontext/builtin/handoff_report/canonical.py b/src/powercontext/builtin/handoff_report/canonical.py index 65e8a084d..eea1b0b1b 100644 --- a/src/powercontext/builtin/handoff_report/canonical.py +++ b/src/powercontext/builtin/handoff_report/canonical.py @@ -12,93 +12,54 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Canonical JSON and digest helpers for Handoff Reports.""" +"""Canonical digests for Handoff Report snapshots.""" + +# ruff: noqa: TRY003 from __future__ import annotations from collections.abc import Mapping, Sequence from datetime import UTC, datetime from hashlib import sha256 -from typing import TYPE_CHECKING, Any, cast +from typing import Any, cast from unicodedata import normalize import rfc8785 from pydantic import BaseModel, JsonValue -if TYPE_CHECKING: - from powercontext.builtin.handoff_report.report import HandoffReport +from powercontext.builtin.handoff_report.report import HandoffReport class ReportCanonicalizationError(ValueError): - """Raised when a report digest input cannot be represented canonically.""" - - def __init__(self, code: str, detail: object | None = None) -> None: - messages = { - "unknown-event": f"activity selection references unknown event {detail!r}", - "timestamp": "digest timestamps must be timezone-aware", - "float": "digest inputs must not contain floating-point values", - "key-type": "digest object keys must be strings", - "key-collision": "digest object keys collide after NFC normalization", - "unsupported-type": f"digest input contains unsupported value type {detail}", - } - super().__init__(messages[code]) + pass def canonical_json_bytes(value: object, /) -> bytes: - """Return RFC 8785 JSON bytes after applying the report NFC rules.""" - return rfc8785.dumps(cast(Any, _normalize_json(value))) def selection_envelope(report: HandoffReport, /) -> dict[str, object]: - """Build the locale-independent exact selection envelope for one report.""" - - events = {event.event_id: event for item in report.workstreams for event in item.activities} - events.update({event.event_id: event for event in report.unassigned_activity}) - activity_selection = [] - for event_id in report.activity_selection: - event = events.get(event_id) - if event is None: - raise ReportCanonicalizationError("unknown-event", event_id) - activity_selection.append({ - "event_id": event.event_id, - "source": event.source, - "source_event_id": event.source_event_id, - "occurred_at": event.occurred_at, - "observed_at": event.observed_at, - "time_basis": event.time_basis, - }) + """Describe the exact resolved observation independently of rendering time.""" + return { - "schema": "powercontext.handoff-report-selection.v1", - "project_id": report.project.project_id, - "project_revision": report.project_revision, - "normalized_filters": report.normalized_filters, - "normalized_period": report.normalized_period, - "selection_consistency": report.selection_consistency, - "activity_cursor": report.activity_cursor, - "baseline_selection": report.baseline_selection, - "end_selection": report.end_selection, - "activity_selection": activity_selection, + "schema": "powercontext.handoff-report-selection.v2", + "selection": report.selection, + "scope_ids": report.scope_ids, + "handoffs": tuple(entry.handoff for entry in report.scopes), } def selection_digest(report: HandoffReport, /) -> str: - """Hash the exact selection independently of locale and renderer.""" - return _digest(selection_envelope(report)) def report_digest(report: HandoffReport, /) -> str: - """Hash the complete report payload, excluding its own digest field.""" - payload = report.model_dump(mode="python", by_alias=True, exclude_none=False) payload.pop("report_digest", None) return _digest(payload) def finalize_digests(report: HandoffReport, /) -> HandoffReport: - """Return a report with selection and output-specific digests populated.""" - selected = report.model_copy(update={"selection_digest": selection_digest(report)}) return selected.model_copy(update={"report_digest": report_digest(selected)}) @@ -107,40 +68,32 @@ def _digest(value: object) -> str: return f"sha256:{sha256(canonical_json_bytes(value)).hexdigest()}" -def _normalize_json(value: object) -> JsonValue: +def _normalize_json(value: object) -> JsonValue: # noqa: C901 if isinstance(value, BaseModel): return _normalize_json(value.model_dump(mode="python", by_alias=True, exclude_none=False)) if isinstance(value, datetime): if value.tzinfo is None or value.utcoffset() is None: - raise ReportCanonicalizationError("timestamp") + raise ReportCanonicalizationError("digest timestamps must be timezone-aware") return value.astimezone(UTC).isoformat(timespec="microseconds").replace("+00:00", "Z") if isinstance(value, str): return normalize("NFC", value) if value is None or isinstance(value, (bool, int)): return value if isinstance(value, float): - raise ReportCanonicalizationError("float") + raise ReportCanonicalizationError("digest inputs must not contain floating-point values") if isinstance(value, Mapping): - return _normalize_mapping(cast(Mapping[object, object], value)) + normalized: dict[str, JsonValue] = {} + for key, item in cast(Mapping[object, object], value).items(): + if not isinstance(key, str): + raise ReportCanonicalizationError("digest object keys must be strings") + normalized_key = normalize("NFC", key) + if normalized_key in normalized: + raise ReportCanonicalizationError("digest object keys collide after normalization") + normalized[normalized_key] = _normalize_json(item) + return normalized if isinstance(value, Sequence) and not isinstance(value, (bytes, bytearray, memoryview)): - return _normalize_sequence(value) - raise ReportCanonicalizationError("unsupported-type", type(value).__name__) - - -def _normalize_mapping(value: Mapping[object, object]) -> dict[str, JsonValue]: - normalized: dict[str, JsonValue] = {} - for key, item in value.items(): - if not isinstance(key, str): - raise ReportCanonicalizationError("key-type") - normalized_key = normalize("NFC", key) - if normalized_key in normalized: - raise ReportCanonicalizationError("key-collision") - normalized[normalized_key] = _normalize_json(item) - return normalized - - -def _normalize_sequence(value: Sequence[object]) -> list[JsonValue]: - return [_normalize_json(item) for item in value] + return [_normalize_json(item) for item in value] + raise ReportCanonicalizationError(f"unsupported digest value: {type(value).__name__}") __all__ = [ diff --git a/src/powercontext/builtin/handoff_report/catalog.py b/src/powercontext/builtin/handoff_report/catalog.py deleted file mode 100644 index 09bce97f9..000000000 --- a/src/powercontext/builtin/handoff_report/catalog.py +++ /dev/null @@ -1,223 +0,0 @@ -# Copyright (c) 2026 OceanBase. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -"""Application service for the Report-owned Project catalog.""" - -from __future__ import annotations - -from collections.abc import Callable -from datetime import datetime -from uuid import uuid4 - -from sqlalchemy.ext.asyncio import AsyncConnection - -from powercontext.builtin.handoff_report.catalog_store import ( - DEFAULT_CATALOG_PAGE_SIZE, - CatalogPage, - ReportCatalogRepository, -) -from powercontext.builtin.handoff_report.models import ( - CatalogState, - ExternalReference, - ProjectDescriptor, - ReportLocale, - WorkstreamDescriptor, - WorkstreamKind, -) - -ProjectIdFactory = Callable[[], str] - - -class HandoffReportCatalog: - """Coordinate server-generated Project identity with catalog persistence. - - The service only mutates Report-owned catalog tables. It never creates a - Core scope, writes Handoff data, or infers membership from repository - signals. - """ - - def __init__( - self, - repository: ReportCatalogRepository | None = None, - *, - project_id_factory: ProjectIdFactory | None = None, - ) -> None: - self._repository = ReportCatalogRepository() if repository is None else repository - self._project_id_factory = _new_project_id if project_id_factory is None else project_id_factory - - async def create_project( - self, - connection: AsyncConnection, - *, - project_key: str, - title: str, - description: str | None = None, - default_locale: ReportLocale = "zh-CN", - timezone: str = "UTC", - effective_at: datetime | None = None, - ) -> ProjectDescriptor: - descriptor = ProjectDescriptor( - project_id=self._project_id_factory(), - project_key=project_key, - title=title, - description=description, - default_locale=default_locale, - timezone=timezone, - version=1, - ) - return await self._repository.create_project(connection, descriptor, effective_at=effective_at) - - async def get_project(self, connection: AsyncConnection, project_id: str, /) -> ProjectDescriptor: - return await self._repository.get_project(connection, project_id) - - async def list_projects( - self, - connection: AsyncConnection, - /, - *, - cursor: str | None = None, - limit: int = DEFAULT_CATALOG_PAGE_SIZE, - include_archived: bool = False, - ) -> CatalogPage[ProjectDescriptor]: - return await self._repository.list_projects( - connection, - cursor=cursor, - limit=limit, - include_archived=include_archived, - ) - - async def update_project( - self, - connection: AsyncConnection, - descriptor: ProjectDescriptor, - expected_version: int, - *, - effective_at: datetime | None = None, - ) -> ProjectDescriptor: - return await self._repository.update_project( - connection, - descriptor, - expected_version, - effective_at=effective_at, - ) - - async def project_revision( - self, - connection: AsyncConnection, - project_id: str, - version: int, - /, - ) -> ProjectDescriptor: - return await self._repository.project_revision(connection, project_id, version) - - async def project_at( - self, - connection: AsyncConnection, - project_id: str, - effective_at: datetime, - /, - ) -> ProjectDescriptor | None: - return await self._repository.project_at(connection, project_id, effective_at) - - async def register_workstream( - self, - connection: AsyncConnection, - *, - project_id: str, - scope_id: str, - title: str, - kind: WorkstreamKind, - key: str | None = None, - catalog_state: CatalogState = "included", - external_refs: tuple[ExternalReference, ...] = (), - labels: tuple[str, ...] = (), - effective_at: datetime | None = None, - ) -> WorkstreamDescriptor: - descriptor = WorkstreamDescriptor( - scope_id=scope_id, - project_id=project_id, - key=key, - title=title, - kind=kind, - catalog_state=catalog_state, - external_refs=external_refs, - labels=labels, - version=1, - ) - return await self._repository.create_workstream(connection, descriptor, effective_at=effective_at) - - async def get_workstream(self, connection: AsyncConnection, scope_id: str, /) -> WorkstreamDescriptor: - return await self._repository.get_workstream(connection, scope_id) - - async def list_workstreams( - self, - connection: AsyncConnection, - project_id: str, - /, - *, - cursor: str | None = None, - limit: int = DEFAULT_CATALOG_PAGE_SIZE, - include_archived: bool = False, - ) -> CatalogPage[WorkstreamDescriptor]: - return await self._repository.list_workstreams( - connection, - project_id, - cursor=cursor, - limit=limit, - include_archived=include_archived, - ) - - async def update_workstream( - self, - connection: AsyncConnection, - descriptor: WorkstreamDescriptor, - expected_version: int, - *, - effective_at: datetime | None = None, - ) -> WorkstreamDescriptor: - return await self._repository.update_workstream( - connection, - descriptor, - expected_version, - effective_at=effective_at, - ) - - async def workstream_revision( - self, - connection: AsyncConnection, - scope_id: str, - version: int, - /, - ) -> WorkstreamDescriptor: - return await self._repository.workstream_revision(connection, scope_id, version) - - async def workstream_at( - self, - connection: AsyncConnection, - scope_id: str, - effective_at: datetime, - /, - ) -> WorkstreamDescriptor | None: - return await self._repository.workstream_at(connection, scope_id, effective_at) - - async def project_for_scope(self, connection: AsyncConnection, scope_id: str, /) -> ProjectDescriptor: - workstream = await self._repository.get_workstream(connection, scope_id) - return await self._repository.get_project(connection, workstream.project_id) - - -def _new_project_id() -> str: - return f"prj_{uuid4().hex}" - - -__all__ = ["HandoffReportCatalog", "ProjectIdFactory"] diff --git a/src/powercontext/builtin/handoff_report/catalog_store.py b/src/powercontext/builtin/handoff_report/catalog_store.py deleted file mode 100644 index dda79e185..000000000 --- a/src/powercontext/builtin/handoff_report/catalog_store.py +++ /dev/null @@ -1,751 +0,0 @@ -# Copyright (c) 2026 OceanBase. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -"""Report-owned Project and Workstream catalog persistence. - -The tables in this module deliberately keep ``scope_id`` opaque. They are -application-layer metadata and do not create foreign keys into Core Handoff, -Artifact, Source, Memory, or Context tables. -""" - -from __future__ import annotations - -import json -from collections.abc import Mapping -from datetime import UTC, datetime -from typing import Any, Generic, TypeVar - -from pydantic import ValidationError -from sqlalchemy import ( - CheckConstraint, - Column, - Index, - Integer, - MetaData, - Table, - Text, - UniqueConstraint, - insert, - select, - update, -) -from sqlalchemy.exc import IntegrityError -from sqlalchemy.ext.asyncio import AsyncConnection -from typing_extensions import override - -from powercontext.builtin.handoff_report.errors import ( - HandoffReportCatalogArgumentError, - InvalidStoredCatalogError, - ProjectConflictError, - ProjectNotFoundError, - ScopeAlreadyGroupedError, - WorkstreamConflictError, - WorkstreamNotFoundError, -) -from powercontext.builtin.handoff_report.models import ( - MAX_PROJECT_KEY_LENGTH, - MAX_REPORT_ID_LENGTH, - MAX_WORKSTREAM_KEY_LENGTH, - ProjectDescriptor, - WorkstreamDescriptor, -) -from powercontext.builtin.persistence.tables import identity_string -from powercontext.limits import MAX_SCOPE_ID_LENGTH - -HANDOFF_REPORT_CATALOG_METADATA = MetaData() - -HANDOFF_REPORT_PROJECTS_TABLE = Table( - "pc_handoff_report_projects", - HANDOFF_REPORT_CATALOG_METADATA, - Column("project_id", identity_string(MAX_REPORT_ID_LENGTH), primary_key=True), - Column("project_key", identity_string(MAX_PROJECT_KEY_LENGTH), nullable=False, unique=True), - Column("version", Integer, nullable=False), - Column("catalog_state", identity_string(16), nullable=False), - Column("payload", Text, nullable=False), - CheckConstraint("version > 0", name="ck_pc_handoff_report_projects_version_positive"), -) - -HANDOFF_REPORT_PROJECT_REVISIONS_TABLE = Table( - "pc_handoff_report_project_revisions", - HANDOFF_REPORT_CATALOG_METADATA, - Column("project_id", identity_string(MAX_REPORT_ID_LENGTH), primary_key=True), - Column("version", Integer, primary_key=True), - Column("effective_at", identity_string(32), nullable=False), - Column("payload", Text, nullable=False), - CheckConstraint("version > 0", name="ck_pc_handoff_report_project_revisions_version_positive"), -) -Index( - "ix_pc_handoff_report_project_revisions_effective_at", - HANDOFF_REPORT_PROJECT_REVISIONS_TABLE.c.project_id, - HANDOFF_REPORT_PROJECT_REVISIONS_TABLE.c.effective_at, - HANDOFF_REPORT_PROJECT_REVISIONS_TABLE.c.version, -) - -HANDOFF_REPORT_WORKSTREAMS_TABLE = Table( - "pc_handoff_report_workstreams", - HANDOFF_REPORT_CATALOG_METADATA, - Column("scope_id", identity_string(MAX_SCOPE_ID_LENGTH), primary_key=True), - Column("project_id", identity_string(MAX_REPORT_ID_LENGTH), nullable=False), - Column("workstream_key", identity_string(MAX_WORKSTREAM_KEY_LENGTH)), - Column("version", Integer, nullable=False), - Column("catalog_state", identity_string(16), nullable=False), - Column("payload", Text, nullable=False), - UniqueConstraint( - "project_id", - "workstream_key", - name="uq_pc_handoff_report_workstreams_project_key", - ), - CheckConstraint("version > 0", name="ck_pc_handoff_report_workstreams_version_positive"), -) -Index( - "ix_pc_handoff_report_workstreams_project_scope", - HANDOFF_REPORT_WORKSTREAMS_TABLE.c.project_id, - HANDOFF_REPORT_WORKSTREAMS_TABLE.c.scope_id, -) - -HANDOFF_REPORT_WORKSTREAM_REVISIONS_TABLE = Table( - "pc_handoff_report_workstream_revisions", - HANDOFF_REPORT_CATALOG_METADATA, - Column("scope_id", identity_string(MAX_SCOPE_ID_LENGTH), primary_key=True), - Column("version", Integer, primary_key=True), - Column("project_id", identity_string(MAX_REPORT_ID_LENGTH), nullable=False), - Column("effective_at", identity_string(32), nullable=False), - Column("payload", Text, nullable=False), - CheckConstraint("version > 0", name="ck_pc_handoff_report_workstream_revisions_version_positive"), -) -Index( - "ix_pc_handoff_report_workstream_revisions_effective_at", - HANDOFF_REPORT_WORKSTREAM_REVISIONS_TABLE.c.scope_id, - HANDOFF_REPORT_WORKSTREAM_REVISIONS_TABLE.c.effective_at, - HANDOFF_REPORT_WORKSTREAM_REVISIONS_TABLE.c.version, -) - -HANDOFF_REPORT_CATALOG_TABLES = ( - HANDOFF_REPORT_PROJECTS_TABLE, - HANDOFF_REPORT_PROJECT_REVISIONS_TABLE, - HANDOFF_REPORT_WORKSTREAMS_TABLE, - HANDOFF_REPORT_WORKSTREAM_REVISIONS_TABLE, -) - -DEFAULT_CATALOG_PAGE_SIZE = 50 -MAX_CATALOG_PAGE_SIZE = 100 -CatalogItemT = TypeVar("CatalogItemT") - - -class CatalogPage(Generic[CatalogItemT]): - """A stable identity-cursor page returned by the Report catalog.""" - - __slots__ = ("items", "next_cursor") - - def __init__(self, items: tuple[CatalogItemT, ...], next_cursor: str | None) -> None: - self.items = items - self.next_cursor = next_cursor - - @override - def __repr__(self) -> str: - return f"CatalogPage(items={self.items!r}, next_cursor={self.next_cursor!r})" - - @override - def __eq__(self, other: object) -> bool: - return isinstance(other, CatalogPage) and self.items == other.items and self.next_cursor == other.next_cursor - - -class ReportCatalogRepository: - """Persist mutable catalog heads and immutable descriptor revisions.""" - - async def create_project( - self, - connection: AsyncConnection, - descriptor: ProjectDescriptor, - /, - *, - effective_at: datetime | None = None, - ) -> ProjectDescriptor: - _validate_project_descriptor(descriptor) - if descriptor.version != 1: - raise HandoffReportCatalogArgumentError("version", "a new Project must start at version 1") - if await self._find_project(connection, descriptor.project_id) is not None: - raise ProjectConflictError(descriptor.project_id, None, descriptor.version) - key_owner = await self._find_project_by_key(connection, descriptor.project_key) - if key_owner is not None: - raise ProjectConflictError( - descriptor.project_id, - None, - int(key_owner["version"]), - detail=f"Project key {descriptor.project_key!r} is already in use", - ) - - effective_text = _effective_at_text(effective_at) - try: - await connection.execute( - insert(HANDOFF_REPORT_PROJECTS_TABLE).values( - project_id=descriptor.project_id, - project_key=descriptor.project_key, - version=descriptor.version, - catalog_state=descriptor.catalog_state, - payload=_dump_descriptor(descriptor), - ) - ) - await connection.execute( - insert(HANDOFF_REPORT_PROJECT_REVISIONS_TABLE).values( - project_id=descriptor.project_id, - version=descriptor.version, - effective_at=effective_text, - payload=_dump_descriptor(descriptor), - ) - ) - except IntegrityError as error: - raise ProjectConflictError( - descriptor.project_id, - None, - None, - detail=f"Project key {descriptor.project_key!r} conflicts with the current catalog", - ) from error - return descriptor - - async def get_project(self, connection: AsyncConnection, project_id: str, /) -> ProjectDescriptor: - project_id = _identifier("project_id", project_id, MAX_REPORT_ID_LENGTH) - row = await self._find_project(connection, project_id) - if row is None: - raise ProjectNotFoundError(project_id) - return _decode_project(row) - - async def list_projects( - self, - connection: AsyncConnection, - /, - *, - cursor: str | None = None, - limit: int = DEFAULT_CATALOG_PAGE_SIZE, - include_archived: bool = False, - ) -> CatalogPage[ProjectDescriptor]: - cursor = None if cursor is None else _identifier("cursor", cursor, MAX_REPORT_ID_LENGTH) - _page_limit(limit) - statement = ( - select(HANDOFF_REPORT_PROJECTS_TABLE).order_by(HANDOFF_REPORT_PROJECTS_TABLE.c.project_id).limit(limit + 1) - ) - if cursor is not None: - statement = statement.where(HANDOFF_REPORT_PROJECTS_TABLE.c.project_id > cursor) - if not include_archived: - statement = statement.where(HANDOFF_REPORT_PROJECTS_TABLE.c.catalog_state == "included") - rows = list((await connection.execute(statement)).mappings()) - has_more = len(rows) > limit - selected = rows[:limit] - items = tuple(_decode_project(row) for row in selected) - return CatalogPage(items, items[-1].project_id if has_more and items else None) - - async def update_project( - self, - connection: AsyncConnection, - descriptor: ProjectDescriptor, - expected_version: int, - /, - *, - effective_at: datetime | None = None, - ) -> ProjectDescriptor: - _validate_project_descriptor(descriptor) - _version("expected_version", expected_version) - if descriptor.version != expected_version + 1: - raise HandoffReportCatalogArgumentError( - "version", - "updated Project version must equal expected_version + 1", - ) - current = await self._find_project(connection, descriptor.project_id) - if current is None: - raise ProjectNotFoundError(descriptor.project_id) - current_version = int(current["version"]) - if current_version != expected_version: - raise ProjectConflictError(descriptor.project_id, expected_version, current_version) - key_owner = await self._find_project_by_key(connection, descriptor.project_key) - if key_owner is not None and str(key_owner["project_id"]) != descriptor.project_id: - raise ProjectConflictError( - descriptor.project_id, - expected_version, - current_version, - detail=f"Project key {descriptor.project_key!r} is already in use", - ) - - effective_text = _effective_at_text(effective_at) - try: - result = await connection.execute( - update(HANDOFF_REPORT_PROJECTS_TABLE) - .where( - HANDOFF_REPORT_PROJECTS_TABLE.c.project_id == descriptor.project_id, - HANDOFF_REPORT_PROJECTS_TABLE.c.version == expected_version, - ) - .values( - project_key=descriptor.project_key, - version=descriptor.version, - catalog_state=descriptor.catalog_state, - payload=_dump_descriptor(descriptor), - ) - ) - if result.rowcount != 1: - current = await self._find_project(connection, descriptor.project_id) - if current is None: - raise ProjectNotFoundError(descriptor.project_id) - raise ProjectConflictError( - descriptor.project_id, - expected_version, - int(current["version"]), - ) - await connection.execute( - insert(HANDOFF_REPORT_PROJECT_REVISIONS_TABLE).values( - project_id=descriptor.project_id, - version=descriptor.version, - effective_at=effective_text, - payload=_dump_descriptor(descriptor), - ) - ) - except IntegrityError as error: - raise ProjectConflictError( - descriptor.project_id, - expected_version, - current_version, - detail=f"Project key {descriptor.project_key!r} conflicts with the current catalog", - ) from error - return descriptor - - async def project_revision( - self, - connection: AsyncConnection, - project_id: str, - version: int, - /, - ) -> ProjectDescriptor: - project_id = _identifier("project_id", project_id, MAX_REPORT_ID_LENGTH) - _version("version", version) - row = ( - ( - await connection.execute( - select(HANDOFF_REPORT_PROJECT_REVISIONS_TABLE).where( - HANDOFF_REPORT_PROJECT_REVISIONS_TABLE.c.project_id == project_id, - HANDOFF_REPORT_PROJECT_REVISIONS_TABLE.c.version == version, - ) - ) - ) - .mappings() - .one_or_none() - ) - if row is None: - raise ProjectNotFoundError(project_id) - return _decode_project(row) - - async def project_at( - self, - connection: AsyncConnection, - project_id: str, - effective_at: datetime, - /, - ) -> ProjectDescriptor | None: - project_id = _identifier("project_id", project_id, MAX_REPORT_ID_LENGTH) - boundary = _effective_at_text(effective_at) - row = ( - ( - await connection.execute( - select(HANDOFF_REPORT_PROJECT_REVISIONS_TABLE) - .where( - HANDOFF_REPORT_PROJECT_REVISIONS_TABLE.c.project_id == project_id, - HANDOFF_REPORT_PROJECT_REVISIONS_TABLE.c.effective_at <= boundary, - ) - .order_by( - HANDOFF_REPORT_PROJECT_REVISIONS_TABLE.c.effective_at.desc(), - HANDOFF_REPORT_PROJECT_REVISIONS_TABLE.c.version.desc(), - ) - .limit(1) - ) - ) - .mappings() - .one_or_none() - ) - return None if row is None else _decode_project(row) - - async def create_workstream( - self, - connection: AsyncConnection, - descriptor: WorkstreamDescriptor, - /, - *, - effective_at: datetime | None = None, - ) -> WorkstreamDescriptor: - _validate_workstream_descriptor(descriptor) - if descriptor.version != 1: - raise HandoffReportCatalogArgumentError("version", "a new Workstream must start at version 1") - await self.get_project(connection, descriptor.project_id) - existing = await self._find_workstream(connection, descriptor.scope_id) - if existing is not None: - existing_project = str(existing["project_id"]) - if existing_project != descriptor.project_id: - raise ScopeAlreadyGroupedError(descriptor.scope_id, existing_project) - raise WorkstreamConflictError( - descriptor.scope_id, - None, - int(existing["version"]), - detail=f"scope {descriptor.scope_id!r} is already registered", - ) - key_owner = await self._find_workstream_by_key(connection, descriptor.project_id, descriptor.key) - if key_owner is not None: - raise WorkstreamConflictError( - descriptor.scope_id, - None, - int(key_owner["version"]), - detail=f"Workstream key {descriptor.key!r} is already in use", - ) - - effective_text = _effective_at_text(effective_at) - try: - await connection.execute( - insert(HANDOFF_REPORT_WORKSTREAMS_TABLE).values( - scope_id=descriptor.scope_id, - project_id=descriptor.project_id, - workstream_key=descriptor.key, - version=descriptor.version, - catalog_state=descriptor.catalog_state, - payload=_dump_descriptor(descriptor), - ) - ) - await connection.execute( - insert(HANDOFF_REPORT_WORKSTREAM_REVISIONS_TABLE).values( - scope_id=descriptor.scope_id, - version=descriptor.version, - project_id=descriptor.project_id, - effective_at=effective_text, - payload=_dump_descriptor(descriptor), - ) - ) - except IntegrityError as error: - raise WorkstreamConflictError( - descriptor.scope_id, - None, - None, - detail=f"Workstream key {descriptor.key!r} conflicts with the current catalog", - ) from error - return descriptor - - async def get_workstream(self, connection: AsyncConnection, scope_id: str, /) -> WorkstreamDescriptor: - scope_id = _identifier("scope_id", scope_id, MAX_SCOPE_ID_LENGTH) - row = await self._find_workstream(connection, scope_id) - if row is None: - raise WorkstreamNotFoundError(scope_id) - return _decode_workstream(row) - - async def list_workstreams( - self, - connection: AsyncConnection, - project_id: str, - /, - *, - cursor: str | None = None, - limit: int = DEFAULT_CATALOG_PAGE_SIZE, - include_archived: bool = False, - ) -> CatalogPage[WorkstreamDescriptor]: - project_id = _identifier("project_id", project_id, MAX_REPORT_ID_LENGTH) - cursor = None if cursor is None else _identifier("cursor", cursor, MAX_SCOPE_ID_LENGTH) - _page_limit(limit) - statement = ( - select(HANDOFF_REPORT_WORKSTREAMS_TABLE) - .where(HANDOFF_REPORT_WORKSTREAMS_TABLE.c.project_id == project_id) - .order_by(HANDOFF_REPORT_WORKSTREAMS_TABLE.c.scope_id) - .limit(limit + 1) - ) - if cursor is not None: - statement = statement.where(HANDOFF_REPORT_WORKSTREAMS_TABLE.c.scope_id > cursor) - if not include_archived: - statement = statement.where(HANDOFF_REPORT_WORKSTREAMS_TABLE.c.catalog_state == "included") - rows = list((await connection.execute(statement)).mappings()) - has_more = len(rows) > limit - selected = rows[:limit] - items = tuple(_decode_workstream(row) for row in selected) - return CatalogPage(items, items[-1].scope_id if has_more and items else None) - - async def update_workstream( - self, - connection: AsyncConnection, - descriptor: WorkstreamDescriptor, - expected_version: int, - /, - *, - effective_at: datetime | None = None, - ) -> WorkstreamDescriptor: - _validate_workstream_descriptor(descriptor) - _version("expected_version", expected_version) - if descriptor.version != expected_version + 1: - raise HandoffReportCatalogArgumentError( - "version", - "updated Workstream version must equal expected_version + 1", - ) - current = await self._find_workstream(connection, descriptor.scope_id) - if current is None: - raise WorkstreamNotFoundError(descriptor.scope_id) - current_project = str(current["project_id"]) - current_version = int(current["version"]) - if current_project != descriptor.project_id: - raise HandoffReportCatalogArgumentError( - "project_id", - "Workstream membership cannot move between Projects", - ) - if current_version != expected_version: - raise WorkstreamConflictError(descriptor.scope_id, expected_version, current_version) - key_owner = await self._find_workstream_by_key(connection, descriptor.project_id, descriptor.key) - if key_owner is not None and str(key_owner["scope_id"]) != descriptor.scope_id: - raise WorkstreamConflictError( - descriptor.scope_id, - expected_version, - current_version, - detail=f"Workstream key {descriptor.key!r} is already in use", - ) - - effective_text = _effective_at_text(effective_at) - try: - result = await connection.execute( - update(HANDOFF_REPORT_WORKSTREAMS_TABLE) - .where( - HANDOFF_REPORT_WORKSTREAMS_TABLE.c.scope_id == descriptor.scope_id, - HANDOFF_REPORT_WORKSTREAMS_TABLE.c.version == expected_version, - ) - .values( - workstream_key=descriptor.key, - version=descriptor.version, - catalog_state=descriptor.catalog_state, - payload=_dump_descriptor(descriptor), - ) - ) - if result.rowcount != 1: - current = await self._find_workstream(connection, descriptor.scope_id) - if current is None: - raise WorkstreamNotFoundError(descriptor.scope_id) - raise WorkstreamConflictError( - descriptor.scope_id, - expected_version, - int(current["version"]), - ) - await connection.execute( - insert(HANDOFF_REPORT_WORKSTREAM_REVISIONS_TABLE).values( - scope_id=descriptor.scope_id, - version=descriptor.version, - project_id=descriptor.project_id, - effective_at=effective_text, - payload=_dump_descriptor(descriptor), - ) - ) - except IntegrityError as error: - raise WorkstreamConflictError( - descriptor.scope_id, - expected_version, - current_version, - detail=f"Workstream key {descriptor.key!r} conflicts with the current catalog", - ) from error - return descriptor - - async def workstream_revision( - self, - connection: AsyncConnection, - scope_id: str, - version: int, - /, - ) -> WorkstreamDescriptor: - scope_id = _identifier("scope_id", scope_id, MAX_SCOPE_ID_LENGTH) - _version("version", version) - row = ( - ( - await connection.execute( - select(HANDOFF_REPORT_WORKSTREAM_REVISIONS_TABLE).where( - HANDOFF_REPORT_WORKSTREAM_REVISIONS_TABLE.c.scope_id == scope_id, - HANDOFF_REPORT_WORKSTREAM_REVISIONS_TABLE.c.version == version, - ) - ) - ) - .mappings() - .one_or_none() - ) - if row is None: - raise WorkstreamNotFoundError(scope_id) - return _decode_workstream(row) - - async def workstream_at( - self, - connection: AsyncConnection, - scope_id: str, - effective_at: datetime, - /, - ) -> WorkstreamDescriptor | None: - scope_id = _identifier("scope_id", scope_id, MAX_SCOPE_ID_LENGTH) - boundary = _effective_at_text(effective_at) - row = ( - ( - await connection.execute( - select(HANDOFF_REPORT_WORKSTREAM_REVISIONS_TABLE) - .where( - HANDOFF_REPORT_WORKSTREAM_REVISIONS_TABLE.c.scope_id == scope_id, - HANDOFF_REPORT_WORKSTREAM_REVISIONS_TABLE.c.effective_at <= boundary, - ) - .order_by( - HANDOFF_REPORT_WORKSTREAM_REVISIONS_TABLE.c.effective_at.desc(), - HANDOFF_REPORT_WORKSTREAM_REVISIONS_TABLE.c.version.desc(), - ) - .limit(1) - ) - ) - .mappings() - .one_or_none() - ) - return None if row is None else _decode_workstream(row) - - async def _find_project(self, connection: AsyncConnection, project_id: str) -> Mapping[Any, Any] | None: - return ( - ( - await connection.execute( - select(HANDOFF_REPORT_PROJECTS_TABLE).where( - HANDOFF_REPORT_PROJECTS_TABLE.c.project_id == project_id - ) - ) - ) - .mappings() - .one_or_none() - ) - - async def _find_project_by_key(self, connection: AsyncConnection, project_key: str) -> Mapping[Any, Any] | None: - return ( - ( - await connection.execute( - select(HANDOFF_REPORT_PROJECTS_TABLE).where( - HANDOFF_REPORT_PROJECTS_TABLE.c.project_key == project_key - ) - ) - ) - .mappings() - .one_or_none() - ) - - async def _find_workstream(self, connection: AsyncConnection, scope_id: str) -> Mapping[Any, Any] | None: - return ( - ( - await connection.execute( - select(HANDOFF_REPORT_WORKSTREAMS_TABLE).where( - HANDOFF_REPORT_WORKSTREAMS_TABLE.c.scope_id == scope_id - ) - ) - ) - .mappings() - .one_or_none() - ) - - async def _find_workstream_by_key( - self, - connection: AsyncConnection, - project_id: str, - key: str | None, - ) -> Mapping[Any, Any] | None: - if key is None: - return None - return ( - ( - await connection.execute( - select(HANDOFF_REPORT_WORKSTREAMS_TABLE).where( - HANDOFF_REPORT_WORKSTREAMS_TABLE.c.project_id == project_id, - HANDOFF_REPORT_WORKSTREAMS_TABLE.c.workstream_key == key, - ) - ) - ) - .mappings() - .one_or_none() - ) - - -def _validate_project_descriptor(value: ProjectDescriptor) -> None: - if not isinstance(value, ProjectDescriptor): - raise HandoffReportCatalogArgumentError("descriptor", "must be a ProjectDescriptor") - - -def _validate_workstream_descriptor(value: WorkstreamDescriptor) -> None: - if not isinstance(value, WorkstreamDescriptor): - raise HandoffReportCatalogArgumentError("descriptor", "must be a WorkstreamDescriptor") - - -def _dump_descriptor(value: ProjectDescriptor | WorkstreamDescriptor) -> str: - return json.dumps( - value.model_dump(mode="json", by_alias=True), - ensure_ascii=False, - sort_keys=True, - separators=(",", ":"), - allow_nan=False, - ) - - -def _decode_project(row: Mapping[Any, Any]) -> ProjectDescriptor: - try: - value = ProjectDescriptor.model_validate_json(str(row["payload"])) - except ValidationError as error: - raise InvalidStoredCatalogError("Project descriptor", "does not match its schema") from error # noqa: TRY003 - if value.project_id != str(row["project_id"]) or value.version != int(row["version"]): - raise InvalidStoredCatalogError( # noqa: TRY003 - "Project descriptor", - "identity does not match indexed columns", - ) - return value - - -def _decode_workstream(row: Mapping[Any, Any]) -> WorkstreamDescriptor: - try: - value = WorkstreamDescriptor.model_validate_json(str(row["payload"])) - except ValidationError as error: - raise InvalidStoredCatalogError("Workstream descriptor", "does not match its schema") from error # noqa: TRY003 - if value.scope_id != str(row["scope_id"]) or value.version != int(row["version"]): - raise InvalidStoredCatalogError( # noqa: TRY003 - "Workstream descriptor", - "identity does not match indexed columns", - ) - return value - - -def _identifier(field: str, value: object, maximum: int) -> str: - if not isinstance(value, str) or not value or value != value.strip(): - raise HandoffReportCatalogArgumentError(field, "must be a non-empty trimmed string") - if len(value) > maximum: - raise HandoffReportCatalogArgumentError(field, f"must not exceed {maximum} characters") - return value - - -def _version(field: str, value: object) -> None: - if not isinstance(value, int) or isinstance(value, bool) or value < 1: - raise HandoffReportCatalogArgumentError(field, "must be a positive integer") - - -def _page_limit(value: object) -> None: - if not isinstance(value, int) or isinstance(value, bool) or not 1 <= value <= MAX_CATALOG_PAGE_SIZE: - raise HandoffReportCatalogArgumentError( - "limit", - f"must be between 1 and {MAX_CATALOG_PAGE_SIZE}", - ) - - -def _effective_at_text(value: datetime | None) -> str: - current = datetime.now(UTC) if value is None else value - if current.tzinfo is None or current.utcoffset() is None: - raise HandoffReportCatalogArgumentError("effective_at", "must include a UTC offset") - return current.astimezone(UTC).isoformat(timespec="microseconds").replace("+00:00", "Z") - - -__all__ = [ - "DEFAULT_CATALOG_PAGE_SIZE", - "HANDOFF_REPORT_CATALOG_METADATA", - "HANDOFF_REPORT_CATALOG_TABLES", - "HANDOFF_REPORT_PROJECTS_TABLE", - "HANDOFF_REPORT_PROJECT_REVISIONS_TABLE", - "HANDOFF_REPORT_WORKSTREAMS_TABLE", - "HANDOFF_REPORT_WORKSTREAM_REVISIONS_TABLE", - "MAX_CATALOG_PAGE_SIZE", - "CatalogPage", - "ReportCatalogRepository", -] diff --git a/src/powercontext/builtin/handoff_report/errors.py b/src/powercontext/builtin/handoff_report/errors.py index 778dfa23d..771e9f81e 100644 --- a/src/powercontext/builtin/handoff_report/errors.py +++ b/src/powercontext/builtin/handoff_report/errors.py @@ -12,185 +12,26 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Typed failures owned by the optional Handoff Report feature.""" - -from __future__ import annotations +"""Failures specific to Handoff Report projection.""" from powercontext.errors import PowerContextError class HandoffReportError(PowerContextError): - """Base class for failures isolated to Handoff Report operations.""" - - -class HandoffReportBusyError(HandoffReportError): - """Raised when repeated head reads cannot form an optimistic-stable selection.""" - - def __init__(self, attempts: int) -> None: - self.attempts = attempts - super().__init__(f"Handoff heads remained unstable after {attempts} attempts") + pass class HandoffReportInconsistentError(HandoffReportError): - """Raised when an adapter cannot return the exact Handoff frozen in selection.""" - def __init__(self, scope_id: str) -> None: self.scope_id = scope_id - super().__init__(f"the frozen Handoff selection became inconsistent for scope {scope_id!r}") - - -class HandoffReportEvidenceCheckUnavailableError(HandoffReportError): - """Raised when a read adapter has no independent evidence-check capability.""" + super().__init__(f"the exact Handoff could not be read for Scope {scope_id!r}") class HandoffReportTooLargeError(HandoffReportError): - """Raised when an untruncated report exceeds a deterministic resource limit.""" - - def __init__( - self, - *, - selected_workstreams: int, - selected_activities: int, - estimated_bytes: int | None = None, - ) -> None: - self.selected_workstreams = selected_workstreams - self.selected_activities = selected_activities + def __init__(self, *, selected_scopes: int, estimated_bytes: int | None = None) -> None: + self.selected_scopes = selected_scopes self.estimated_bytes = estimated_bytes - super().__init__("the Handoff Report exceeds the configured projection limit") - - -class HandoffReportCatalogArgumentError(HandoffReportError, ValueError): - """Raised when a catalog operation receives an invalid control value.""" - - def __init__(self, field: str, detail: str) -> None: - self.field = field - self.detail = detail - super().__init__(f"invalid Handoff Report catalog argument {field}: {detail}") - - -class InvalidStoredCatalogError(HandoffReportError): - """Raised when a persisted catalog descriptor is malformed or inconsistent.""" - - def __init__(self, kind: str, detail: str) -> None: - self.kind = kind - self.detail = detail - super().__init__(f"invalid stored Handoff Report {kind}: {detail}") - - -class ProjectNotFoundError(HandoffReportError, LookupError): - """Raised when a Report Project is absent.""" - - code = "project_not_found" - - def __init__(self, project_id: str) -> None: - self.project_id = project_id - super().__init__(f"Report Project {project_id!r} was not found") - - -class WorkstreamNotFoundError(HandoffReportError, LookupError): - """Raised when a Report Workstream is absent.""" - - code = "scope_not_grouped" - - def __init__(self, scope_id: str) -> None: - self.scope_id = scope_id - super().__init__(f"Report Workstream {scope_id!r} was not found") - - -class ProjectConflictError(HandoffReportError, ValueError): - """Raised when Project CAS or uniqueness validation fails.""" - - code = "project_conflict" - - def __init__( - self, - project_id: str, - expected_version: int | None, - current_version: int | None, - *, - detail: str = "Project version or key conflicts with the current catalog", - ) -> None: - self.project_id = project_id - self.expected_version = expected_version - self.current_version = current_version - self.detail = detail - super().__init__(detail) - - -class WorkstreamConflictError(HandoffReportError, ValueError): - """Raised when Workstream CAS or uniqueness validation fails.""" - - code = "workstream_conflict" - - def __init__( - self, - scope_id: str, - expected_version: int | None, - current_version: int | None, - *, - detail: str = "Workstream version or key conflicts with the current catalog", - ) -> None: - self.scope_id = scope_id - self.expected_version = expected_version - self.current_version = current_version - self.detail = detail - super().__init__(detail) - - -class ScopeAlreadyGroupedError(HandoffReportError, ValueError): - """Raised when a scope is already a member of another Project.""" - - code = "scope_already_grouped" - - def __init__(self, scope_id: str, project_id: str) -> None: - self.scope_id = scope_id - self.project_id = project_id - super().__init__(f"scope {scope_id!r} already belongs to Project {project_id!r}") - - -class WorkspaceBindingNotFoundError(HandoffReportError, LookupError): - """Raised when a workspace has no confirmed Project binding.""" - - code = "workspace_not_bound" - - def __init__(self, workspace_instance_id: str) -> None: - self.workspace_instance_id = workspace_instance_id - super().__init__(f"workspace {workspace_instance_id!r} has no confirmed Report binding") - - -class WorkspaceBindingConflictError(HandoffReportError, ValueError): - """Raised when workspace binding CAS or single-binding rules fail.""" - - code = "workspace_binding_conflict" - - def __init__( - self, - workspace_instance_id: str, - expected_version: int | None, - current_version: int | None, - *, - detail: str = "workspace binding version conflicts with the current catalog", - ) -> None: - self.workspace_instance_id = workspace_instance_id - self.expected_version = expected_version - self.current_version = current_version - self.detail = detail - super().__init__(detail) + super().__init__("the Handoff Report exceeds the response limit") -__all__ = [ - "HandoffReportBusyError", - "HandoffReportCatalogArgumentError", - "HandoffReportError", - "HandoffReportEvidenceCheckUnavailableError", - "HandoffReportInconsistentError", - "HandoffReportTooLargeError", - "InvalidStoredCatalogError", - "ProjectConflictError", - "ProjectNotFoundError", - "ScopeAlreadyGroupedError", - "WorkspaceBindingConflictError", - "WorkspaceBindingNotFoundError", - "WorkstreamConflictError", - "WorkstreamNotFoundError", -] +__all__ = ["HandoffReportError", "HandoffReportInconsistentError", "HandoffReportTooLargeError"] diff --git a/src/powercontext/builtin/handoff_report/models.py b/src/powercontext/builtin/handoff_report/models.py deleted file mode 100644 index 5348d2e29..000000000 --- a/src/powercontext/builtin/handoff_report/models.py +++ /dev/null @@ -1,483 +0,0 @@ -# Copyright (c) 2026 OceanBase. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -"""Immutable domain values owned by the optional Handoff Report feature.""" - -from __future__ import annotations - -import posixpath -from datetime import UTC, datetime, timedelta -from typing import Annotated, Literal, TypeAlias -from unicodedata import normalize -from urllib.parse import urlsplit, urlunsplit -from zoneinfo import ZoneInfo, ZoneInfoNotFoundError - -from pydantic import BaseModel, ConfigDict, Field, StrictInt, field_validator, model_validator - -from powercontext.artifacts import ArtifactRef -from powercontext.limits import MAX_SCOPE_ID_LENGTH - -MAX_REPORT_ID_LENGTH = 256 -MAX_PROJECT_KEY_LENGTH = 64 -MAX_WORKSTREAM_KEY_LENGTH = 64 -MAX_REPORT_TITLE_LENGTH = 256 -MAX_REPORT_DESCRIPTION_LENGTH = 2_000 -MAX_REPORT_LABEL_LENGTH = 128 -MAX_REPORT_PROVIDER_LENGTH = 64 -MAX_REPORT_AGENT_LABEL_LENGTH = 128 -MAX_REPORT_SOURCE_SUMMARY_LENGTH = 2_000 -MAX_REPORT_EXTERNAL_ID_LENGTH = 256 -MAX_REPORT_URL_LENGTH = 2_048 -MAX_REPORT_REPOSITORY_ID_LENGTH = 256 -MAX_REPORT_NORMALIZED_REMOTE_LENGTH = 2_048 -MAX_REPORT_SUBPATH_LENGTH = 1_024 -MAX_WORKSPACE_INSTANCE_ID_LENGTH = 256 -MAX_REPORT_EXTERNAL_REFS = 32 -MAX_REPORT_LABELS = 32 -MAX_REPORT_EVIDENCE_REFS = 32 - -ReportLocale: TypeAlias = Literal["zh-CN", "en"] -CatalogState: TypeAlias = Literal["included", "archived"] -WorkstreamKind: TypeAlias = Literal["feature", "bug", "refactor", "operations", "research", "other"] -ExternalReferenceKind: TypeAlias = Literal[ - "issue", - "task", - "pull_request", - "branch", - "feature", - "release", - "program", - "other", -] -ReportActivitySource: TypeAlias = Literal[ - "handoff_observation", - "git_commit", - "git_worktree", - "coding_session", - "other", -] -ReportTimeBasis: TypeAlias = Literal[ - "source_reported", - "host_observed", - "first_seen", - "current_only", - "unknown", -] -ReportSelectionConsistency: TypeAlias = Literal["exact_input", "optimistic_stable"] -ReportSelectionStatus: TypeAlias = Literal["selected", "no_handoff"] -ReportActivityTrust: TypeAlias = Literal["untrusted_observation"] -HandoffReportTrust: TypeAlias = Literal["untrusted_history"] -GeneratedSummaryTrust: TypeAlias = Literal["generated_untrusted"] -RepositoryProvider: TypeAlias = Literal["github", "gitlab", "local", "other"] -WorkspaceBindingState: TypeAlias = Literal["confirmed", "detached"] - - -class _ReportValue(BaseModel): - model_config = ConfigDict(extra="forbid", frozen=True, strict=True) - - -class ExternalReference(_ReportValue): - """A navigation or filtering reference that is not identity or evidence by itself.""" - - kind: ExternalReferenceKind - provider: Annotated[str, Field(max_length=MAX_REPORT_PROVIDER_LENGTH)] - external_id: Annotated[str, Field(max_length=MAX_REPORT_EXTERNAL_ID_LENGTH)] - url: Annotated[str, Field(max_length=MAX_REPORT_URL_LENGTH)] | None = None - - @field_validator("provider", "external_id", "url") - @classmethod - def require_trimmed_text(cls, value: str | None, info) -> str | None: - return _require_optional_text(info.field_name, value) - - -class RepositoryRef(_ReportValue): - """Credential-free repository identity hints attached to a workspace.""" - - provider: RepositoryProvider - repository_id: Annotated[str, Field(max_length=MAX_REPORT_REPOSITORY_ID_LENGTH)] | None = None - normalized_remote: Annotated[str, Field(max_length=MAX_REPORT_NORMALIZED_REMOTE_LENGTH)] | None = None - subpath: Annotated[str, Field(max_length=MAX_REPORT_SUBPATH_LENGTH)] | None = None - - @field_validator("repository_id", "normalized_remote", "subpath") - @classmethod - def require_trimmed_text(cls, value: str | None, info) -> str | None: - return _require_optional_text(info.field_name, value) - - @model_validator(mode="after") - def require_repository_signal(self) -> RepositoryRef: - if self.repository_id is None and self.normalized_remote is None and self.subpath is None: - raise ValueError("repository_ref must contain a repository id, remote, or subpath") # noqa: TRY003 - if self.normalized_remote is not None and any(marker in self.normalized_remote for marker in ("@", "?", "#")): - raise ValueError("normalized_remote must not contain credentials or query fragments") # noqa: TRY003 - return self - - -class WorkspaceBinding(_ReportValue): - """One CAS-versioned binding between a local checkout and a Report Project.""" - - schema_version: Literal["powercontext.workspace-binding.v1"] = Field( - default="powercontext.workspace-binding.v1", - alias="schema", - ) - workspace_instance_id: Annotated[str, Field(max_length=MAX_WORKSPACE_INSTANCE_ID_LENGTH)] - project_id: Annotated[str, Field(max_length=MAX_REPORT_ID_LENGTH)] - repository_ref: RepositoryRef - state: WorkspaceBindingState = "confirmed" - confirmed_at: datetime - version: StrictInt = Field(ge=1) - - @field_validator("workspace_instance_id", "project_id") - @classmethod - def require_trimmed_text(cls, value: str, info) -> str: - return _require_text(info.field_name, value) - - @field_validator("confirmed_at") - @classmethod - def normalize_confirmed_at(cls, value: datetime) -> datetime: - if value.tzinfo is None or value.utcoffset() is None: - raise ValueError("confirmed_at must include a UTC offset") # noqa: TRY003 - return value.astimezone(UTC) - - -class ProjectDescriptor(_ReportValue): - """One versioned Report-owned Project catalog snapshot.""" - - schema_version: Literal["powercontext.project.v1"] = Field( - default="powercontext.project.v1", - alias="schema", - ) - project_id: Annotated[str, Field(max_length=MAX_REPORT_ID_LENGTH)] - project_key: Annotated[str, Field(max_length=MAX_PROJECT_KEY_LENGTH)] - title: Annotated[str, Field(max_length=MAX_REPORT_TITLE_LENGTH)] - description: Annotated[str, Field(max_length=MAX_REPORT_DESCRIPTION_LENGTH)] | None = None - default_locale: ReportLocale = "zh-CN" - timezone: Annotated[str, Field(max_length=MAX_REPORT_ID_LENGTH)] - catalog_state: CatalogState = "included" - version: StrictInt = Field(ge=1) - - @field_validator("project_id", "project_key", "title", "description") - @classmethod - def require_trimmed_text(cls, value: str | None, info) -> str | None: - return _require_optional_text(info.field_name, value) - - @field_validator("timezone") - @classmethod - def require_iana_timezone(cls, value: str) -> str: - _require_text("timezone", value) - try: - ZoneInfo(value) - except ZoneInfoNotFoundError as error: - raise ValueError("timezone must be a recognized IANA timezone") from error # noqa: TRY003 - return value - - -class WorkstreamDescriptor(_ReportValue): - """One versioned Report-owned descriptor for an existing Handoff scope.""" - - schema_version: Literal["powercontext.workstream.v1"] = Field( - default="powercontext.workstream.v1", - alias="schema", - ) - scope_id: Annotated[str, Field(max_length=MAX_SCOPE_ID_LENGTH)] - project_id: Annotated[str, Field(max_length=MAX_REPORT_ID_LENGTH)] - key: Annotated[str, Field(max_length=MAX_WORKSTREAM_KEY_LENGTH)] | None = None - title: Annotated[str, Field(max_length=MAX_REPORT_TITLE_LENGTH)] - kind: WorkstreamKind - catalog_state: CatalogState = "included" - external_refs: Annotated[tuple[ExternalReference, ...], Field(max_length=MAX_REPORT_EXTERNAL_REFS)] = () - labels: Annotated[tuple[str, ...], Field(max_length=MAX_REPORT_LABELS)] = () - version: StrictInt = Field(ge=1) - - @field_validator("scope_id", "project_id", "key", "title") - @classmethod - def require_trimmed_text(cls, value: str | None, info) -> str | None: - return _require_optional_text(info.field_name, value) - - @field_validator("labels") - @classmethod - def require_valid_labels(cls, values: tuple[str, ...]) -> tuple[str, ...]: - for value in values: - _require_text("label", value) - if len(value) > MAX_REPORT_LABEL_LENGTH: - raise ValueError(f"label must not exceed {MAX_REPORT_LABEL_LENGTH} characters") # noqa: TRY003 - if len(set(values)) != len(values): - raise ValueError("Workstream labels must be unique") # noqa: TRY003 - return values - - @model_validator(mode="after") - def require_unique_external_refs(self) -> WorkstreamDescriptor: - if len(set(self.external_refs)) != len(self.external_refs): - raise ValueError("Workstream external references must be unique") # noqa: TRY003 - return self - - -class ActivityAgent(_ReportValue): - """Untrusted Agent attribution reported by an activity source.""" - - provider: Annotated[str, Field(max_length=MAX_REPORT_PROVIDER_LENGTH)] | None = None - label: Annotated[str, Field(max_length=MAX_REPORT_AGENT_LABEL_LENGTH)] | None = None - - @field_validator("provider", "label") - @classmethod - def require_trimmed_text(cls, value: str | None, info) -> str | None: - return _require_optional_text(info.field_name, value) - - @model_validator(mode="after") - def require_attribution(self) -> ActivityAgent: - if self.provider is None and self.label is None: - raise ValueError("Activity Agent must contain a provider or label") # noqa: TRY003 - return self - - -class ActivityVcsContext(_ReportValue): - """Untrusted VCS display context observed for an activity.""" - - branch: Annotated[str, Field(max_length=MAX_REPORT_TITLE_LENGTH)] | None = None - head_revision: Annotated[str, Field(max_length=MAX_REPORT_ID_LENGTH)] | None = None - - @field_validator("branch", "head_revision") - @classmethod - def require_trimmed_text(cls, value: str | None, info) -> str | None: - return _require_optional_text(info.field_name, value) - - @model_validator(mode="after") - def require_context(self) -> ActivityVcsContext: - if self.branch is None and self.head_revision is None: - raise ValueError("Activity VCS context must contain a branch or head revision") # noqa: TRY003 - return self - - -class ReportActivityEvent(_ReportValue): - """One idempotent, untrusted observation in the independent Report activity store.""" - - schema_version: Literal["powercontext.handoff-report-activity.v1"] = Field( - default="powercontext.handoff-report-activity.v1", - alias="schema", - ) - event_id: Annotated[str, Field(max_length=MAX_REPORT_ID_LENGTH)] - project_id: Annotated[str, Field(max_length=MAX_REPORT_ID_LENGTH)] - scope_id: Annotated[str, Field(max_length=MAX_SCOPE_ID_LENGTH)] | None = None - source: ReportActivitySource - source_event_id: Annotated[str, Field(max_length=MAX_REPORT_ID_LENGTH)] - source_ref: ExternalReference | None = None - occurred_at: datetime | None = None - observed_at: datetime - time_basis: ReportTimeBasis - title: Annotated[str, Field(max_length=MAX_REPORT_TITLE_LENGTH)] | None = None - summary: Annotated[str, Field(max_length=MAX_REPORT_SOURCE_SUMMARY_LENGTH)] | None = None - agent: ActivityAgent | None = None - session_id: Annotated[str, Field(max_length=MAX_REPORT_ID_LENGTH)] | None = None - vcs_context: ActivityVcsContext | None = None - evidence_refs: Annotated[tuple[ExternalReference, ...], Field(max_length=MAX_REPORT_EVIDENCE_REFS)] = () - trust: ReportActivityTrust = "untrusted_observation" - - @field_validator("event_id", "project_id", "scope_id", "source_event_id", "title", "summary", "session_id") - @classmethod - def require_trimmed_text(cls, value: str | None, info) -> str | None: - return _require_optional_text(info.field_name, value) - - @field_validator("occurred_at", "observed_at") - @classmethod - def require_aware_timestamp(cls, value: datetime | None, info) -> datetime | None: - if value is not None and (value.tzinfo is None or value.utcoffset() is None): - raise ValueError(f"{info.field_name} must include a UTC offset") # noqa: TRY003 - return value - - @field_validator("observed_at") - @classmethod - def require_utc_observation(cls, value: datetime) -> datetime: - if value.utcoffset() != timedelta(0): - raise ValueError("observed_at must be UTC") # noqa: TRY003 - return value - - @model_validator(mode="after") - def validate_time_semantics_and_evidence(self) -> ReportActivityEvent: - if self.time_basis == "source_reported": - if self.occurred_at is None: - raise ValueError("source-reported activity must contain occurred_at") # noqa: TRY003 - elif self.occurred_at is not None: - raise ValueError("occurred_at is only valid for source-reported activity") # noqa: TRY003 - if len(set(self.evidence_refs)) != len(self.evidence_refs): - raise ValueError("Activity evidence references must be unique") # noqa: TRY003 - return self - - def effective_period_time(self) -> datetime | None: - """Return the reportable event time, without inventing time for current or unknown activity.""" - - if self.time_basis == "source_reported": - return self.occurred_at - if self.time_basis in {"host_observed", "first_seen"}: - return self.observed_at - return None - - -class ReportSelectionEntry(_ReportValue): - """Freeze one Workstream descriptor revision and exact Handoff selection.""" - - scope_id: Annotated[str, Field(max_length=MAX_SCOPE_ID_LENGTH)] - workstream_revision: StrictInt = Field(ge=1) - status: ReportSelectionStatus - handoff_ref: ArtifactRef | None = None - - @field_validator("scope_id") - @classmethod - def require_scope_id(cls, value: str) -> str: - return _require_text("scope_id", value) - - @model_validator(mode="after") - def validate_selection(self) -> ReportSelectionEntry: - if self.status == "selected": - if self.handoff_ref is None: - raise ValueError("selected Report entry must contain an exact Handoff reference") # noqa: TRY003 - if self.handoff_ref.family != "handoff": - raise ValueError("selected Report entry must reference the Handoff family") # noqa: TRY003 - elif self.handoff_ref is not None: - raise ValueError("no-handoff Report entry cannot contain a Handoff reference") # noqa: TRY003 - return self - - -def normalized_sort_text(value: str) -> str: - """Normalize user-visible text for deterministic, locale-independent ordering.""" - - return normalize("NFC", value).casefold() - - -def workstream_sort_key(workstream: WorkstreamDescriptor) -> tuple[str, str]: - """Sort descriptors by normalized title and stable scope identity.""" - - return normalized_sort_text(workstream.title), workstream.scope_id - - -def activity_sort_key(event: ReportActivityEvent) -> tuple[bool, datetime, datetime, str]: - """Sort reportable activity first and unknown/current activity deterministically last.""" - - effective_time = event.effective_period_time() - return effective_time is None, effective_time or event.observed_at, event.observed_at, event.event_id - - -def selection_sort_key(entry: ReportSelectionEntry) -> str: - """Sort exact selections by canonical Workstream identity.""" - - return entry.scope_id - - -def normalize_repository_ref(value: RepositoryRef) -> RepositoryRef: - """Apply the versioned, credential-free normalization used for binding keys.""" - - if not isinstance(value, RepositoryRef): - raise TypeError("repository_ref must be a RepositoryRef") # noqa: TRY003 - remote = _normalize_repository_remote(value.normalized_remote) - subpath = _normalize_repository_subpath(value.subpath) - - return RepositoryRef( - provider=value.provider, - repository_id=value.repository_id, - normalized_remote=remote, - subpath=subpath, - ) - - -def _normalize_repository_remote(value: str | None) -> str | None: - if value is None or "://" not in value: - return None if value is None else value.rstrip("/") - parsed = urlsplit(value) - if parsed.username is not None or parsed.password is not None or parsed.query or parsed.fragment: - raise ValueError("normalized_remote must not contain credentials or query fragments") # noqa: TRY003 - if parsed.hostname is None: - raise ValueError("normalized_remote must contain a host") # noqa: TRY003 - try: - port = parsed.port - except ValueError as error: - raise ValueError("normalized_remote must contain a valid port") from error # noqa: TRY003 - host = parsed.hostname.lower() - netloc = host if port is None else f"{host}:{port}" - path = "/" + "/".join(part for part in parsed.path.split("/") if part not in {"", "."}) - return urlunsplit((parsed.scheme.lower(), netloc, path or "/", "", "")) - - -def _normalize_repository_subpath(value: str | None) -> str | None: - if value is None: - return None - candidate = value.replace("\\", "/") - if any(part == ".." for part in candidate.split("/")): - raise ValueError("repository subpath must not contain parent traversal") # noqa: TRY003 - normalized = posixpath.normpath(candidate) - if normalized in {"", "."}: - return "." - if normalized.startswith("/"): - raise ValueError("repository subpath must be relative") # noqa: TRY003 - return normalized - - -def _require_text(field_name: str, value: str) -> str: - if not value.strip(): - raise ValueError(f"{field_name} must contain non-whitespace text") # noqa: TRY003 - if value != value.strip(): - raise ValueError(f"{field_name} must not contain leading or trailing whitespace") # noqa: TRY003 - return value - - -def _require_optional_text(field_name: str, value: str | None) -> str | None: - if value is not None: - _require_text(field_name, value) - return value - - -__all__ = [ - "MAX_PROJECT_KEY_LENGTH", - "MAX_REPORT_AGENT_LABEL_LENGTH", - "MAX_REPORT_DESCRIPTION_LENGTH", - "MAX_REPORT_EVIDENCE_REFS", - "MAX_REPORT_EXTERNAL_ID_LENGTH", - "MAX_REPORT_EXTERNAL_REFS", - "MAX_REPORT_ID_LENGTH", - "MAX_REPORT_LABELS", - "MAX_REPORT_LABEL_LENGTH", - "MAX_REPORT_NORMALIZED_REMOTE_LENGTH", - "MAX_REPORT_PROVIDER_LENGTH", - "MAX_REPORT_REPOSITORY_ID_LENGTH", - "MAX_REPORT_SOURCE_SUMMARY_LENGTH", - "MAX_REPORT_SUBPATH_LENGTH", - "MAX_REPORT_TITLE_LENGTH", - "MAX_REPORT_URL_LENGTH", - "MAX_WORKSPACE_INSTANCE_ID_LENGTH", - "MAX_WORKSTREAM_KEY_LENGTH", - "ActivityAgent", - "ActivityVcsContext", - "CatalogState", - "ExternalReference", - "ExternalReferenceKind", - "GeneratedSummaryTrust", - "HandoffReportTrust", - "ProjectDescriptor", - "ReportActivityEvent", - "ReportActivitySource", - "ReportActivityTrust", - "ReportLocale", - "ReportSelectionConsistency", - "ReportSelectionEntry", - "ReportSelectionStatus", - "ReportTimeBasis", - "RepositoryProvider", - "RepositoryRef", - "WorkspaceBinding", - "WorkspaceBindingState", - "WorkstreamDescriptor", - "WorkstreamKind", - "activity_sort_key", - "normalize_repository_ref", - "normalized_sort_text", - "selection_sort_key", - "workstream_sort_key", -] diff --git a/src/powercontext/builtin/handoff_report/protocols.py b/src/powercontext/builtin/handoff_report/protocols.py index 5d77cae1b..8ffc98f2c 100644 --- a/src/powercontext/builtin/handoff_report/protocols.py +++ b/src/powercontext/builtin/handoff_report/protocols.py @@ -12,50 +12,25 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Read-only ports consumed by the optional Handoff Report feature.""" +"""Read ports used by Handoff Report projection.""" from __future__ import annotations from typing import Protocol from powercontext.artifacts import ArtifactRef -from powercontext.builtin.artifacts.handoff import Handoff, HandoffEvidenceCheck -from powercontext.builtin.work import WorkContinuity +from powercontext.builtin.artifacts.handoff import Handoff +from powercontext.builtin.scope.models import ScopeDescriptor, ScopeSelection class HandoffReadAdapter(Protocol): - """Read committed Handoffs without extending their persistence protocol.""" + async def latest(self, scope_id: str, /) -> Handoff | None: ... - async def latest(self, scope_id: str, /) -> Handoff | None: - """Return one scope's current committed Handoff, if it exists.""" + async def get(self, scope_id: str, reference: ArtifactRef, /) -> Handoff: ... - ... - async def get(self, scope_id: str, reference: ArtifactRef, /) -> Handoff: - """Return the exact committed Handoff addressed by ``reference``.""" +class ScopeSelectionResolver(Protocol): + async def resolve_selection(self, selection: ScopeSelection, /) -> tuple[ScopeDescriptor, ...]: ... - ... - async def revisions(self, scope_id: str, /) -> tuple[Handoff, ...]: - """Return one scope's committed Handoffs in ascending Revision order.""" - - ... - - async def check_evidence( - self, - scope_id: str, - reference: ArtifactRef, - /, - ) -> tuple[HandoffEvidenceCheck, ...]: - """Recheck evidence readability for one exact committed Handoff.""" - - ... - - -class WorkContinuityReadAdapter(Protocol): - """Read the high-level Work loop projection for one scope.""" - - async def get(self, scope_id: str, reference: ArtifactRef | None, /) -> WorkContinuity: ... - - -__all__ = ["HandoffReadAdapter", "WorkContinuityReadAdapter"] +__all__ = ["HandoffReadAdapter", "ScopeSelectionResolver"] diff --git a/src/powercontext/builtin/handoff_report/rendering.py b/src/powercontext/builtin/handoff_report/rendering.py index 00d2d1da4..669177353 100644 --- a/src/powercontext/builtin/handoff_report/rendering.py +++ b/src/powercontext/builtin/handoff_report/rendering.py @@ -12,443 +12,58 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Deterministic Markdown rendering for canonical Handoff Reports.""" +"""Markdown rendering for Scope-based Handoff Reports.""" from __future__ import annotations -import html -import json -import re -from datetime import datetime -from unicodedata import category - -from powercontext.builtin.handoff_report.canonical import finalize_digests -from powercontext.builtin.handoff_report.models import ExternalReference, ReportActivityEvent -from powercontext.builtin.handoff_report.report import HandoffReport, WorkstreamReport - -_LABELS = { - "zh-CN": { - "title": "PowerContext 项目交接报告", - "overview": "项目概览", - "blockers": "阻塞事项", - "workstreams": "Workstream 状态", - "details": "Workstream 详情", - "objective": "目标", - "progress": "当前进度", - "next": "下一步", - "omissions": "缺失信息", - "activities": "观察到的 Activity", - "unassigned_activities": "未分配 Activity", - "event": "事件", - "schema": "Schema", - "event_id": "事件 ID", - "project_id": "Project ID", - "source": "来源", - "source_event_id": "来源事件 ID", - "scope": "Scope", - "time_basis": "时间依据", - "occurred_at": "发生时间", - "observed_at": "观察时间", - "event_title": "标题", - "event_summary": "摘要", - "source_ref": "来源引用", - "agent": "Agent", - "session": "Session", - "vcs": "VCS 上下文", - "evidence": "证据引用", - "evidence_checks": "Evidence 检查", - "revision_history": "Handoff Revision 历史", - "revision_history_summary": "共 {total} 个 Revision，显示最近 {shown} 个。", # noqa: RUF001 - "revision_state_count": "状态条目", - "revision_omission_count": "缺失条目", - "continuity": "连续性时间线", - "transfer_state": "交接状态", - "outcome_state": "结果状态", - "journal_order_notice": "按 Source journal 的稳定位置排序；位置表示先后顺序，不代表时间戳。", # noqa: RUF001 - "invalid_work_records": "无法读取的 Work 记录", - "metadata": "报告元数据", - "selection_digest": "Selection Digest", - "report_digest": "Report Digest", - "report_kind": "报告类型", - "period": "报告周期", - "period_comparison": "与前一周期对比", - "current_activity_count": "本周期 Activity 数", - "previous_activity_count": "前一周期 Activity 数", - "activity_delta": "Activity 变化", - "handoff_boundary_coverage": "Handoff 时间边界覆盖", - "format": "格式", - "trust": "信任标记", - "none": "无", - "activity_notice": "Activity Adapter 未配置；此处不能解释为没有活动。", # noqa: RUF001 - }, - "en": { - "title": "PowerContext Project Handoff Report", - "overview": "Project Overview", - "blockers": "Blockers", - "workstreams": "Workstream Status", - "details": "Workstream Details", - "objective": "Objective", - "progress": "Current Progress", - "next": "Next Action", - "omissions": "Omissions", - "activities": "Observed Activity", - "unassigned_activities": "Unassigned Activity", - "event": "Event", - "schema": "Schema", - "event_id": "Event ID", - "project_id": "Project ID", - "source": "Source", - "source_event_id": "Source Event ID", - "scope": "Scope", - "time_basis": "Time Basis", - "occurred_at": "Occurred At", - "observed_at": "Observed At", - "event_title": "Title", - "event_summary": "Summary", - "source_ref": "Source Reference", - "agent": "Agent", - "session": "Session", - "vcs": "VCS Context", - "evidence": "Evidence References", - "evidence_checks": "Evidence Checks", - "revision_history": "Handoff Revision History", - "revision_history_summary": "{total} Revisions total. Showing the latest {shown}.", - "revision_state_count": "State Items", - "revision_omission_count": "Omissions", - "continuity": "Continuity Timeline", - "transfer_state": "Transfer State", - "outcome_state": "Outcome State", - "journal_order_notice": "Ordered by stable Source journal position; positions show sequence, not timestamps.", - "invalid_work_records": "Unreadable Work Records", - "metadata": "Report Metadata", - "selection_digest": "Selection Digest", - "report_digest": "Report Digest", - "report_kind": "Report Kind", - "period": "Report Period", - "period_comparison": "Previous Period Comparison", - "current_activity_count": "Current Activity Count", - "previous_activity_count": "Previous Activity Count", - "activity_delta": "Activity Delta", - "handoff_boundary_coverage": "Handoff Boundary Coverage", - "format": "Format", - "trust": "Trust", - "none": "None", - "activity_notice": "Activity adapters are not configured; this does not mean that no activity occurred.", - }, -} +from powercontext.builtin.handoff_report.report import HandoffReport, ScopeHandoffReport def render_markdown(report: HandoffReport, /) -> str: - """Render one stable human projection without invoking a model or parsing Markdown input.""" - - projection = finalize_digests(report.model_copy(update={"format": "markdown", "renderer_version": "markdown-v1"})) - labels = _LABELS[projection.locale] - lines = _front_matter_lines(projection) - overview_identity = ( - f"Scope: {_code_span(projection.workstreams[0].workstream.scope_id)}" - if _is_scope_report(projection) - else f"Project: {_text(projection.project.title)}" - ) - lines.extend([ - "---", - "", - f"# {labels['title']}", + lines = [ + "# Handoff Report", "", - f"## {labels['overview']}", + f"Selection: `{report.selection.mode}`", + f"Scopes: {len(report.scopes)}", "", - f"- {overview_identity}", - f"- Workstreams: {projection.coverage.selected_workstreams}", - f"- Missing Handoff: {projection.coverage.missing_handoff_workstreams}", - f"- Continuable: {projection.summary.continuable_count}", - f"- Blocked: {projection.summary.blocked_count}", - f"- Complete: {projection.summary.complete_count}", - f"- No Handoff: {projection.summary.no_handoff_count}", - ]) - if projection.coverage.activity_coverage == "not_configured": - lines.extend((f"- {_text(labels['activity_notice'])}", "")) - else: - lines.append("") - if projection.normalized_period is not None: - lines.extend(( - f"## {labels['period']}", - "", - f"- Start: {_code_span(str(projection.normalized_period['start']))}", - f"- End: {_code_span(str(projection.normalized_period['end']))}", - f"- Timezone: {_code_span(str(projection.normalized_period['timezone']))}", - "", - )) - if projection.period_comparison is not None: - comparison = projection.period_comparison - lines.extend(( - f"## {labels['period_comparison']}", - "", - f"- {labels['current_activity_count']}: {comparison.current_activity_count}", - f"- {labels['previous_activity_count']}: {comparison.previous_activity_count}", - f"- {labels['activity_delta']}: {comparison.activity_delta:+d}", - f"- {labels['handoff_boundary_coverage']}: {_code_span(comparison.handoff_boundary_coverage)}", - "", - )) - lines.extend((f"## {labels['blockers']}", "")) - blockers = tuple(item for item in projection.workstreams if item.work_status == "blocked") - if blockers: - lines.extend( - f"- {_text(item.workstream.title)} ({_code_span(item.workstream.scope_id)}): " - f"{_code_span(item.reporting_status)}" - for item in blockers - ) - else: - lines.extend((labels["none"], "")) - lines.extend((f"## {labels['workstreams']}", "")) - lines.extend( - f"- {_text(item.workstream.title)} ({_code_span(item.workstream.scope_id)}): " - f"{_code_span(item.work_status)} / {_code_span(item.reporting_status)}" - for item in projection.workstreams - ) - lines.extend(("", f"## {labels['details']}", "")) - for item in projection.workstreams: - lines.extend(_render_workstream(item, labels)) - lines.extend((f"## {labels['unassigned_activities']}", "")) - if projection.unassigned_activity: - for event in projection.unassigned_activity: - lines.extend(_render_activity(event, labels)) - else: - lines.extend((labels["none"], "")) - lines.extend((f"## {labels['metadata']}", "")) - lines.extend(( - f"- {labels['selection_digest']}: {_code_span(projection.selection_digest or labels['none'])}", - f"- {labels['report_digest']}: {_code_span(projection.report_digest or labels['none'])}", - f"- {labels['report_kind']}: {_code_span(projection.report_kind)}", - f"- {labels['format']}: {_code_span(projection.format)}", - f"- {labels['trust']}: {_code_span(projection.trust)}", - )) - return "\n".join(lines).rstrip() + "\n" - - -def _render_workstream(item: WorkstreamReport, labels: dict[str, str]) -> list[str]: - lines = [f"### {_text(item.workstream.title)} ({_code_span(item.workstream.scope_id)})", ""] - if item.content is None: - lines.extend((f"#### {labels['objective']}", "", labels["none"], "")) - else: - lines.extend((f"#### {labels['objective']}", "", _text(item.content.objective), "")) - lines.extend((f"#### {labels['progress']}", "")) - lines.extend(f"- {_text(statement.text)}" for statement in item.content.state) - lines.extend(("", f"#### {labels['next']}", "")) - lines.append(labels["none"] if item.content.next_action is None else _text(item.content.next_action.text)) - lines.extend(("", f"#### {labels['omissions']}", "")) - if item.content.omissions: - lines.extend(f"- {_text(omission.text)}" for omission in item.content.omissions) - else: - lines.append(labels["none"]) - lines.append("") - lines.extend((f"#### {labels['evidence_checks']}", "")) - if item.evidence_checks == "not_checked": - evidence_state = "not_checked" - if item.evidence_unavailable: - evidence_state = "not_checked (adapter unavailable)" - lines.extend((_code_span(evidence_state), "")) - elif item.evidence_checks: - lines.extend(f"- {_code_span(check.claim)}: {_code_span(check.status)}" for check in item.evidence_checks) - lines.append("") - lines.extend(_render_revision_history(item, labels)) - continuity = item.continuity - lines.extend((f"#### {labels['continuity']}", "")) - lines.extend(( - f"- {labels['transfer_state']}: {_code_span(continuity.coverage.transfer_state)}", - f"- {labels['outcome_state']}: {_code_span(continuity.coverage.outcome_state)}", - f"- {labels['invalid_work_records']}: {continuity.invalid_record_count}", - f"- {_text(labels['journal_order_notice'])}", - )) - if continuity.events: - for event in continuity.events: - detail = event.summary or event.actor or labels["none"] - lines.append( - f"- {_code_span(f'#{event.position}')} {_code_span(event.kind)} / " - f"{_code_span(event.status)}: {_text(detail)}" - ) - else: - lines.append(labels["none"]) - lines.append("") - lines.extend((f"#### {labels['activities']}", "")) - if item.activities: - for event in item.activities: - lines.extend(_render_activity(event, labels)) - else: - lines.extend((labels["none"], "")) - return lines - - -def _render_revision_history(item: WorkstreamReport, labels: dict[str, str]) -> list[str]: - lines = [f"#### {labels['revision_history']}", ""] - if item.handoff_history: - lines.extend(( - _text( - labels["revision_history_summary"].format( - total=item.handoff_revision_count, - shown=len(item.handoff_history), - ) - ), - "", - )) - for revision in reversed(item.handoff_history): - reference = revision.reference - lines.append( - f"- {_code_span(f'@{reference.revision}')} {_code_span(revision.disposition)}: " - f"{_text(revision.objective_excerpt)}" - ) - lines.append( - f" - {labels['revision_state_count']}: {revision.state_count}; " - f"{labels['revision_omission_count']}: {revision.omission_count}" - ) - if revision.next_action_excerpt is not None: - lines.append(f" - {labels['next']}: {_text(revision.next_action_excerpt)}") - else: - lines.append(labels["none"]) - lines.append("") - return lines - - -def _render_activity(event: ReportActivityEvent, labels: dict[str, str]) -> list[str]: - lines = [f"- **{labels['event']}** {_code_span(event.event_id)}"] - lines.extend(( - f" - {labels['schema']}: {_code_span(event.schema_version)}", - f" - {labels['event_id']}: {_code_span(event.event_id)}", - f" - {labels['project_id']}: {_code_span(event.project_id)}", - f" - {labels['source']}: {_code_span(event.source)}", - f" - {labels['source_event_id']}: {_code_span(event.source_event_id)}", - f" - {labels['scope']}: {_optional_code(event.scope_id, labels)}", - f" - {labels['time_basis']}: {_code_span(event.time_basis)}", - f" - {labels['occurred_at']}: {_optional_timestamp(event.occurred_at, labels)}", - f" - {labels['observed_at']}: {_code_span(event.observed_at.isoformat())}", - f" - {labels['event_title']}: {_optional_text(event.title, labels)}", - f" - {labels['event_summary']}: {_optional_text(event.summary, labels)}", - f" - {labels['source_ref']}: {_optional_reference(event.source_ref, labels)}", - f" - {labels['agent']}: {_agent(event, labels)}", - f" - {labels['session']}: {_optional_code(event.session_id, labels)}", - f" - {labels['vcs']}: {_vcs(event, labels)}", - f" - {labels['trust']}: {_code_span(event.trust)}", - f" - {labels['evidence']}:", - )) - if event.evidence_refs: - lines.extend(f" - {_reference(reference)}" for reference in event.evidence_refs) - else: - lines.append(f" - {labels['none']}") - lines.append("") - return lines - - -def _front_matter_lines(report: HandoffReport) -> list[str]: - lines = [ - "---", - "schema: powercontext.handoff-report.v1", - f"locale: {report.locale}", - "format: markdown", + "| Scope | Parent | Status | Handoff |", + "| --- | --- | --- | --- |", ] - if _is_scope_report(report): - lines.append(f"scope_id: {_yaml_string(report.workstreams[0].workstream.scope_id)}") - else: - lines.extend(( - f"project_id: {_yaml_string(report.project.project_id)}", - f"project_key: {_yaml_string(report.project.project_key)}", - f"project_version: {report.project.version}", - )) - lines.extend(( - f"report_kind: {report.report_kind}", - f"selection_digest: {_yaml_string(report.selection_digest or '')}", - f"report_digest: {_yaml_string(report.report_digest or '')}", - f"generated_at: {_yaml_string(report.generated_at.isoformat())}", - f"trust: {report.trust}", - f"selection_consistency: {report.selection_consistency}", - f"activity_cursor: {report.activity_cursor}", - )) - if report.end_selection: - lines.append("end_selection:") - for entry in report.end_selection: - lines.extend(( - f" - scope_id: {_yaml_string(entry.scope_id)}", - f" workstream_revision: {entry.workstream_revision}", - f" status: {entry.status}", - )) - if entry.handoff_ref is None: - lines.append(" handoff_ref: null") - else: - lines.extend(( - " handoff_ref:", - f" family: {_yaml_string(entry.handoff_ref.family)}", - f" artifact_id: {_yaml_string(entry.handoff_ref.artifact_id)}", - f" revision: {entry.handoff_ref.revision}", - )) - else: - lines.append("end_selection: []") - if report.activity_selection: - lines.append("activity_selection:") - lines.extend(f" - {_yaml_string(event_id)}" for event_id in report.activity_selection) - else: - lines.append("activity_selection: []") + for entry in report.scopes: + parent = entry.scope.parent_scope_id or "—" + reference = "—" if entry.handoff is None else _format_address(entry) + lines.append(f"| {_cell(entry.scope.title)} | `{_cell(parent)}` | {entry.status} | {reference} |") + + for entry in report.scopes: + lines.extend(_scope_section(entry)) + lines.extend(["", f"Selection digest: `{report.selection_digest}`", f"Report digest: `{report.report_digest}`", ""]) + return "\n".join(lines) + + +def _scope_section(entry: ScopeHandoffReport) -> list[str]: + lines = ["", f"## {entry.scope.title}", "", entry.scope.summary] + if entry.content is None: + return [*lines, "", "No committed Handoff."] + lines.extend(["", f"Status: **{entry.status}**", "", f"Objective: {entry.content.objective}", "", "Current state:"]) + lines.extend(f"- {statement.text}" for statement in entry.content.state) + if entry.content.next_action is not None: + lines.extend(["", f"Next action: {entry.content.next_action.text}"]) + if entry.content.omissions: + lines.extend(["", "Known omissions:"]) + lines.extend(f"- {omission.text}" for omission in entry.content.omissions) return lines -def _is_scope_report(report: HandoffReport) -> bool: - return report.project.project_id == "unused" and len(report.workstreams) == 1 - - -def _agent(event: ReportActivityEvent, labels: dict[str, str]) -> str: - if event.agent is None: - return labels["none"] - values = tuple(value for value in (event.agent.provider, event.agent.label) if value is not None) - return " / ".join(_code_span(value) for value in values) - - -def _vcs(event: ReportActivityEvent, labels: dict[str, str]) -> str: - if event.vcs_context is None: - return labels["none"] - values = tuple(value for value in (event.vcs_context.branch, event.vcs_context.head_revision) if value is not None) - return " / ".join(_code_span(value) for value in values) - - -def _optional_reference(reference: ExternalReference | None, labels: dict[str, str]) -> str: - return labels["none"] if reference is None else _reference(reference) - - -def _reference(reference: ExternalReference) -> str: - values = [_code_span(reference.kind), _code_span(reference.provider), _code_span(reference.external_id)] - if reference.url is not None: - values.append(_code_span(reference.url)) - return " / ".join(values) - - -def _optional_text(value: str | None, labels: dict[str, str]) -> str: - return labels["none"] if value is None else _text(value) - - -def _optional_code(value: str | None, labels: dict[str, str]) -> str: - return labels["none"] if value is None else _code_span(value) - - -def _optional_timestamp(value: datetime | None, labels: dict[str, str]) -> str: - return labels["none"] if value is None else _code_span(value.isoformat()) - - -def _collapse_lines(value: str) -> str: - flattened = " ".join(value.splitlines()) - return "".join(" " if category(character) == "Cc" else character for character in flattened) - - -def _text(value: str) -> str: - escaped_html = html.escape(_collapse_lines(value), quote=True) - return re.sub(r"([\\`*_{}\[\]()#+\-.!|>~])", r"\\\1", escaped_html) - - -def _code_span(value: str) -> str: - escaped_html = html.escape(_collapse_lines(value), quote=True) - runs = tuple(len(match.group(0)) for match in re.finditer(r"`+", escaped_html)) - delimiter = "`" * (max(runs, default=0) + 1) - if runs: - return f"{delimiter} {escaped_html} {delimiter}" - return f"{delimiter}{escaped_html}{delimiter}" +def _format_address(entry: ScopeHandoffReport) -> str: + handoff = entry.handoff + if handoff is None: + return "—" + artifact = handoff.artifact + return f"`{handoff.scope_id}/{artifact.family}/{artifact.artifact_id}@{artifact.revision}`" -def _yaml_string(value: str) -> str: - return json.dumps(value, ensure_ascii=False) +def _cell(value: str) -> str: + return value.replace("|", "\\|").replace("\n", " ") __all__ = ["render_markdown"] diff --git a/src/powercontext/builtin/handoff_report/report.py b/src/powercontext/builtin/handoff_report/report.py index 7e0d6d662..d43597a97 100644 --- a/src/powercontext/builtin/handoff_report/report.py +++ b/src/powercontext/builtin/handoff_report/report.py @@ -12,371 +12,86 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Canonical output values for the optional Handoff Report feature.""" +"""Canonical Handoff Report values.""" from __future__ import annotations -from datetime import UTC, datetime -from typing import Annotated, Literal, TypeAlias +from datetime import datetime +from typing import Literal -from pydantic import BaseModel, ConfigDict, Field, JsonValue, StrictInt, field_validator, model_validator +from pydantic import BaseModel, ConfigDict, Field, StrictInt, model_validator -from powercontext.artifacts import ArtifactRef -from powercontext.builtin.artifacts.handoff import HandoffContent, HandoffDisposition, HandoffEvidenceCheck -from powercontext.builtin.handoff_report.models import ( - HandoffReportTrust, - ProjectDescriptor, - ReportActivityEvent, - ReportLocale, - ReportSelectionConsistency, - ReportSelectionEntry, - WorkstreamDescriptor, -) -from powercontext.builtin.work import WorkContinuity +from powercontext.artifacts import ArtifactAddress +from powercontext.builtin.artifacts.handoff import HandoffContent +from powercontext.builtin.scope.models import ScopeDescriptor, ScopeSelection -ReportEvidenceChecks: TypeAlias = tuple[HandoffEvidenceCheck, ...] | Literal["not_checked"] -ReportActivityCoverageStatus: TypeAlias = Literal["not_configured", "captured", "unavailable"] -ReportFormat: TypeAlias = Literal["json", "markdown"] -ReportKind: TypeAlias = Literal["handoff", "periodic"] -ReportWorkStatus: TypeAlias = Literal["continuable", "blocked", "complete", "no_handoff"] -ReportActivityStatus: TypeAlias = Literal[ - "no_observed_activity", - "activity_after_handoff", - "activity_without_handoff", - "current_only", - "unknown", -] -ReportReportingStatus: TypeAlias = Literal[ - "reported", - "reported_with_omissions", - "evidence_unavailable", - "no_handoff", -] -ReportHandoffActivityRelation: TypeAlias = Literal[ - "activity_after_handoff", - "no_observed_activity_after_handoff", - "unknown", -] -ReportHandoffBoundaryCoverage: TypeAlias = Literal["unavailable"] -MAX_REPORT_WORKSTREAMS = 100 -MAX_REPORT_ACTIVITIES = 5_000 -MAX_REPORT_HANDOFF_HISTORY = 20 -MAX_REPORT_HANDOFF_HISTORY_EXCERPT_LENGTH = 240 +HandoffReportStatus = Literal["continuable", "blocked", "complete", "no_handoff"] -class _ReportOutputValue(BaseModel): - model_config = ConfigDict(extra="forbid", frozen=True, strict=True) +class _ReportValue(BaseModel): + model_config = ConfigDict(extra="forbid", frozen=True) -class ReportCoverage(_ReportOutputValue): - """Counts and explicit adapter coverage for one frozen report.""" +class ScopeHandoffReport(_ReportValue): + """The exact latest Handoff projected for one selected Scope.""" - total_included_workstreams: StrictInt = Field(ge=0) - catalog_matched_workstreams: StrictInt = Field(default=0, ge=0) - selected_workstreams: StrictInt = Field(ge=0) - missing_handoff_workstreams: StrictInt = Field(ge=0) - reported_with_omissions: StrictInt = Field(ge=0) - unchecked_evidence_workstreams: StrictInt = Field(default=0, ge=0) - unavailable_evidence_workstreams: StrictInt = Field(ge=0) - activity_without_handoff_workstreams: StrictInt = Field(ge=0) - activity_after_handoff_workstreams: StrictInt = Field(default=0, ge=0) - unknown_time_events: StrictInt = Field(default=0, ge=0) - unassigned_activity_count: StrictInt = Field(ge=0) - unassigned_activity_events: StrictInt = Field(default=0, ge=0) - activity_coverage: ReportActivityCoverageStatus + scope: ScopeDescriptor + status: HandoffReportStatus + handoff: ArtifactAddress | None = None + content: HandoffContent | None = None + @model_validator(mode="after") + def validate_state(self) -> ScopeHandoffReport: + if self.status == "no_handoff": + if self.handoff is not None or self.content is not None: + raise ValueError("no_handoff cannot contain Handoff data") # noqa: TRY003 + return self + if self.handoff is None or self.content is None: + raise ValueError("reported Scope must contain an exact Handoff") # noqa: TRY003 + if self.handoff.scope_id != self.scope.scope_id: + raise ValueError("Handoff address must belong to the reported Scope") # noqa: TRY003 + if self.status != self.content.disposition: + raise ValueError("report status must match Handoff disposition") # noqa: TRY003 + return self -class ReportSummary(_ReportOutputValue): - """Deterministic work-status counts derived from exact Handoff content.""" +class HandoffReportSummary(_ReportValue): continuable_count: StrictInt = Field(ge=0) blocked_count: StrictInt = Field(ge=0) complete_count: StrictInt = Field(ge=0) no_handoff_count: StrictInt = Field(ge=0) -class ReportPeriodComparison(_ReportOutputValue): - """Truthful Activity comparison when Handoff boundary time is unavailable.""" - - previous_start: datetime - previous_end: datetime - current_activity_count: StrictInt = Field(ge=0) - previous_activity_count: StrictInt = Field(ge=0) - activity_delta: StrictInt - handoff_boundary_coverage: ReportHandoffBoundaryCoverage = "unavailable" - - @field_validator("previous_start", "previous_end") - @classmethod - def require_aware_boundary(cls, value: datetime) -> datetime: - if value.tzinfo is None or value.utcoffset() is None: - raise ValueError("period comparison boundaries must be timezone-aware") # noqa: TRY003 - return value.astimezone(UTC) - - @model_validator(mode="after") - def validate_comparison(self) -> ReportPeriodComparison: - if self.previous_start >= self.previous_end: - raise ValueError("previous period start must precede its end") # noqa: TRY003 - if self.activity_delta != self.current_activity_count - self.previous_activity_count: - raise ValueError("activity_delta must match current minus previous Activity count") # noqa: TRY003 - return self - - -class HandoffRevisionSummary(_ReportOutputValue): - """Bounded display metadata for one committed Handoff Revision.""" - - reference: ArtifactRef - objective_excerpt: Annotated[str, Field(max_length=MAX_REPORT_HANDOFF_HISTORY_EXCERPT_LENGTH)] - disposition: HandoffDisposition - next_action_excerpt: Annotated[str | None, Field(max_length=MAX_REPORT_HANDOFF_HISTORY_EXCERPT_LENGTH)] = None - state_count: StrictInt = Field(ge=1) - omission_count: StrictInt = Field(ge=0) - - -class WorkstreamReport(_ReportOutputValue): - """One Workstream projected from an exact Handoff selection.""" - - workstream: WorkstreamDescriptor - continuity: WorkContinuity - handoff_ref: ArtifactRef | None - content: HandoffContent | None - handoff_revision_count: StrictInt = Field(default=0, ge=0) - handoff_history_truncated: bool = False - handoff_history: Annotated[tuple[HandoffRevisionSummary, ...], Field(max_length=MAX_REPORT_HANDOFF_HISTORY)] = () - evidence_checks: ReportEvidenceChecks = "not_checked" - evidence_unavailable: bool = False - activities: Annotated[tuple[ReportActivityEvent, ...], Field(max_length=MAX_REPORT_ACTIVITIES)] = () - work_status: ReportWorkStatus - reporting_status: ReportReportingStatus - activity_status: ReportActivityStatus - handoff_activity_relation: ReportHandoffActivityRelation | None = None - observed_activity_count: StrictInt = Field(default=0, ge=0) - - @model_validator(mode="after") - def validate_handoff_projection(self) -> WorkstreamReport: - if self.continuity.scope_id != self.workstream.scope_id: - raise ValueError("continuity scope must match its Workstream") # noqa: TRY003 - if self.handoff_ref is None: - _validate_no_handoff(self) - else: - _validate_selected_handoff(self) - if self.observed_activity_count != len(self.activities): - raise ValueError("observed_activity_count must match the Workstream activity count") # noqa: TRY003 - return self - - -def _validate_no_handoff(report: WorkstreamReport) -> None: - if report.content is not None: - raise ValueError("a Workstream without Handoff cannot contain Handoff content") # noqa: TRY003 - if report.evidence_checks != "not_checked": - raise ValueError("a Workstream without Handoff cannot contain evidence checks") # noqa: TRY003 - if report.evidence_unavailable: - raise ValueError("a Workstream without Handoff cannot have unavailable evidence checks") # noqa: TRY003 - if report.work_status != "no_handoff": - raise ValueError("a Workstream without Handoff must have no_handoff work status") # noqa: TRY003 - if report.reporting_status != "no_handoff": - raise ValueError("a Workstream without Handoff must report missing Handoff state") # noqa: TRY003 - if report.handoff_revision_count != 0 or report.handoff_history or report.handoff_history_truncated: - raise ValueError("a Workstream without Handoff cannot contain Handoff Revision history") # noqa: TRY003 +class HandoffReport(_ReportValue): + """A read-only projection over all, exact, or subtree Scope selection.""" - -def _validate_selected_handoff(report: WorkstreamReport) -> None: - if report.content is None: - raise ValueError("an exact Handoff selection must contain Handoff content") # noqa: TRY003 - if report.evidence_unavailable and report.evidence_checks != "not_checked": - raise ValueError("an unavailable evidence check must remain not_checked") # noqa: TRY003 - if report.work_status != report.content.disposition: - raise ValueError("work status must match the exact Handoff disposition") # noqa: TRY003 - if report.reporting_status == "no_handoff": - raise ValueError("an exact Handoff selection cannot report missing Handoff state") # noqa: TRY003 - _validate_handoff_history(report) - - -def _validate_handoff_history(report: WorkstreamReport) -> None: - handoff_ref = report.handoff_ref - if handoff_ref is None: - raise ValueError("Handoff Revision history requires an exact selected Handoff") # noqa: TRY003 - if not report.handoff_history: - raise ValueError("an exact Handoff selection must contain Handoff Revision history") # noqa: TRY003 - if report.handoff_history[-1].reference != handoff_ref: - raise ValueError("Handoff Revision history must end at the exact selected Handoff") # noqa: TRY003 - if report.handoff_revision_count < len(report.handoff_history): - raise ValueError("Handoff Revision count cannot be smaller than its projected history") # noqa: TRY003 - if report.handoff_history_truncated != (report.handoff_revision_count > len(report.handoff_history)): - raise ValueError("Handoff Revision truncation must match its projected history") # noqa: TRY003 - references = tuple(item.reference for item in report.handoff_history) - if any( - reference.family != handoff_ref.family or reference.artifact_id != handoff_ref.artifact_id - for reference in references - ): - raise ValueError("Handoff Revision history must belong to the selected Artifact lifecycle") # noqa: TRY003 - if tuple(reference.revision for reference in references) != tuple( - sorted({reference.revision for reference in references}) - ): - raise ValueError("Handoff Revision history must be unique and ascending") # noqa: TRY003 - - -class HandoffReport(_ReportOutputValue): - """Language-neutral canonical report used by renderers and Agents.""" - - schema_version: Literal["powercontext.handoff-report.v1"] = Field( - default="powercontext.handoff-report.v1", + schema_version: Literal["powercontext.handoff-report.v2"] = Field( + default="powercontext.handoff-report.v2", alias="schema", ) - trust: HandoffReportTrust = "untrusted_history" - locale: ReportLocale - format: ReportFormat = "json" - report_kind: ReportKind = "handoff" - renderer_version: str = "canonical-v1" + selection: ScopeSelection + scope_ids: tuple[str, ...] generated_at: datetime - selection_consistency: ReportSelectionConsistency - project: ProjectDescriptor - project_revision: StrictInt = Field(default=1, ge=1) - normalized_filters: dict[str, JsonValue] = Field(default_factory=dict) - normalized_period: dict[str, JsonValue] | None = None - period_comparison: ReportPeriodComparison | None = None - baseline_selection: Annotated[tuple[ReportSelectionEntry, ...], Field(max_length=MAX_REPORT_WORKSTREAMS)] | None = ( - None - ) - end_selection: Annotated[tuple[ReportSelectionEntry, ...], Field(max_length=MAX_REPORT_WORKSTREAMS)] - activity_cursor: StrictInt = Field(ge=0) - activity_selection: Annotated[tuple[str, ...], Field(max_length=MAX_REPORT_ACTIVITIES)] = () - selection_digest: str | None = Field(default=None, pattern=r"sha256:[0-9a-f]{64}") - report_digest: str | None = Field(default=None, pattern=r"sha256:[0-9a-f]{64}") - coverage: ReportCoverage - summary: ReportSummary - unassigned_activity: Annotated[tuple[ReportActivityEvent, ...], Field(max_length=MAX_REPORT_ACTIVITIES)] = () - workstreams: Annotated[tuple[WorkstreamReport, ...], Field(max_length=MAX_REPORT_WORKSTREAMS)] - - @field_validator("generated_at") - @classmethod - def require_utc_generated_at(cls, value: datetime) -> datetime: - if value.tzinfo is None or value.utcoffset() is None: - raise ValueError("generated_at must be timezone-aware") # noqa: TRY003 - return value.astimezone(UTC) + summary: HandoffReportSummary + scopes: tuple[ScopeHandoffReport, ...] + selection_digest: str | None = None + report_digest: str | None = None @model_validator(mode="after") - def validate_selection_projection(self) -> HandoffReport: - _validate_scope_projection(self) - if self.project_revision != self.project.version: - raise ValueError("project_revision must match the projected Project descriptor") # noqa: TRY003 - if self.coverage.selected_workstreams != len(self.workstreams): - raise ValueError("selected_workstreams must match Workstream report count") # noqa: TRY003 - _validate_activity_projection(self) - _validate_coverage_projection(self) - _validate_summary_projection(self) - if self.report_kind == "periodic" and self.normalized_period is None: - raise ValueError("a periodic report must contain a normalized period") # noqa: TRY003 - if self.report_kind == "handoff" and (self.normalized_period is not None or self.period_comparison is not None): - raise ValueError("a point-in-time Handoff report cannot contain period values") # noqa: TRY003 - if self.period_comparison is not None and self.report_kind != "periodic": - raise ValueError("period comparison is only valid for a periodic report") # noqa: TRY003 + def validate_projection(self) -> HandoffReport: + if self.generated_at.tzinfo is None or self.generated_at.utcoffset() is None: + raise ValueError("generated_at must be timezone-aware") # noqa: TRY003 + if self.scope_ids != tuple(entry.scope.scope_id for entry in self.scopes): + raise ValueError("scope_ids must match report entries") # noqa: TRY003 + expected = { + "continuable_count": sum(entry.status == "continuable" for entry in self.scopes), + "blocked_count": sum(entry.status == "blocked" for entry in self.scopes), + "complete_count": sum(entry.status == "complete" for entry in self.scopes), + "no_handoff_count": sum(entry.status == "no_handoff" for entry in self.scopes), + } + if self.summary.model_dump() != expected: + raise ValueError("summary must match report entries") # noqa: TRY003 return self -def _validate_scope_projection(report: HandoffReport) -> None: - selection_scopes = tuple(entry.scope_id for entry in report.end_selection) - report_scopes = tuple(item.workstream.scope_id for item in report.workstreams) - if len(set(selection_scopes)) != len(selection_scopes): - raise ValueError("Handoff Report selection scopes must be unique") # noqa: TRY003 - if len(set(report_scopes)) != len(report_scopes): - raise ValueError("Handoff Report Workstream scopes must be unique") # noqa: TRY003 - if selection_scopes != report_scopes: - raise ValueError("Workstream reports must exactly match selection scope order") # noqa: TRY003 - for entry, item in zip(report.end_selection, report.workstreams, strict=True): - if item.workstream.project_id != report.project.project_id: - raise ValueError("every Workstream report must belong to the Report Project") # noqa: TRY003 - if entry.workstream_revision != item.workstream.version: - raise ValueError("selection Workstream revision must match the projected descriptor") # noqa: TRY003 - if entry.handoff_ref != item.handoff_ref: - raise ValueError("selection Handoff reference must match the Workstream report") # noqa: TRY003 - - -def _validate_activity_projection(report: HandoffReport) -> None: - known_scopes = {item.workstream.scope_id for item in report.workstreams} - assigned_activity: list[ReportActivityEvent] = [] - for item in report.workstreams: - for event in item.activities: - if event.project_id != report.project.project_id: - raise ValueError("every assigned Activity Event must belong to the Report Project") # noqa: TRY003 - if event.scope_id != item.workstream.scope_id: - raise ValueError("assigned Activity Event scope must match its Workstream report") # noqa: TRY003 - assigned_activity.append(event) - for event in report.unassigned_activity: - if event.project_id != report.project.project_id: - raise ValueError("every unassigned Activity Event must belong to the Report Project") # noqa: TRY003 - if event.scope_id in known_scopes: - raise ValueError("Activity Event for a selected scope cannot be unassigned") # noqa: TRY003 - activity_ids = tuple(event.event_id for event in (*assigned_activity, *report.unassigned_activity)) - if len(set(activity_ids)) != len(activity_ids): - raise ValueError("Activity Event ids must be unique within a Handoff Report") # noqa: TRY003 - if report.activity_selection != activity_ids: - raise ValueError("activity_selection must match projected Activity Event order") # noqa: TRY003 - - -def _validate_coverage_projection(report: HandoffReport) -> None: - if report.coverage.total_included_workstreams < len(report.workstreams): - raise ValueError("total_included_workstreams cannot be smaller than the selected report") # noqa: TRY003 - if report.coverage.catalog_matched_workstreams > report.coverage.total_included_workstreams: - raise ValueError("catalog_matched_workstreams cannot exceed total_included_workstreams") # noqa: TRY003 - all_events = tuple(event for item in report.workstreams for event in item.activities) + report.unassigned_activity - expected = { - "missing_handoff_workstreams": sum(item.handoff_ref is None for item in report.workstreams), - "reported_with_omissions": sum( - item.reporting_status == "reported_with_omissions" for item in report.workstreams - ), - "unchecked_evidence_workstreams": sum( - item.handoff_ref is not None and item.evidence_checks == "not_checked" for item in report.workstreams - ), - "unavailable_evidence_workstreams": sum( - item.evidence_unavailable - or ( - item.evidence_checks != "not_checked" - and any(check.status == "unavailable" for check in item.evidence_checks) - ) - for item in report.workstreams - ), - "activity_without_handoff_workstreams": sum( - item.activity_status == "activity_without_handoff" for item in report.workstreams - ), - "activity_after_handoff_workstreams": sum( - item.handoff_activity_relation == "activity_after_handoff" for item in report.workstreams - ), - "unknown_time_events": sum(event.effective_period_time() is None for event in all_events), - "unassigned_activity_count": len(report.unassigned_activity), - "unassigned_activity_events": len(report.unassigned_activity), - } - for field, value in expected.items(): - if getattr(report.coverage, field) != value: - raise ValueError(f"{field} must match the canonical report projection") # noqa: TRY003 - - -def _validate_summary_projection(report: HandoffReport) -> None: - expected = { - "continuable_count": sum(item.work_status == "continuable" for item in report.workstreams), - "blocked_count": sum(item.work_status == "blocked" for item in report.workstreams), - "complete_count": sum(item.work_status == "complete" for item in report.workstreams), - "no_handoff_count": sum(item.work_status == "no_handoff" for item in report.workstreams), - } - for field, value in expected.items(): - if getattr(report.summary, field) != value: - raise ValueError(f"{field} must match the canonical report projection") # noqa: TRY003 - - -__all__ = [ - "MAX_REPORT_ACTIVITIES", - "MAX_REPORT_WORKSTREAMS", - "HandoffReport", - "ReportActivityCoverageStatus", - "ReportActivityStatus", - "ReportCoverage", - "ReportEvidenceChecks", - "ReportFormat", - "ReportHandoffActivityRelation", - "ReportHandoffBoundaryCoverage", - "ReportKind", - "ReportPeriodComparison", - "ReportReportingStatus", - "ReportSummary", - "ReportWorkStatus", - "WorkstreamReport", -] +__all__ = ["HandoffReport", "HandoffReportStatus", "HandoffReportSummary", "ScopeHandoffReport"] diff --git a/src/powercontext/builtin/handoff_report/repository.py b/src/powercontext/builtin/handoff_report/repository.py deleted file mode 100644 index f4eb7a3d7..000000000 --- a/src/powercontext/builtin/handoff_report/repository.py +++ /dev/null @@ -1,149 +0,0 @@ -# Copyright (c) 2026 OceanBase. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -"""Repository boundary for Report-owned activity observations. - -The boundary accepts structural event values and validates their complete payload -against the canonical domain model at the persistence edge. -""" - -from __future__ import annotations - -from collections.abc import Iterable, Mapping -from dataclasses import dataclass -from datetime import datetime -from typing import Literal, Protocol, TypeAlias, runtime_checkable - -from sqlalchemy.ext.asyncio import AsyncConnection - -from powercontext.builtin.handoff_report.errors import HandoffReportError -from powercontext.builtin.handoff_report.models import ReportTimeBasis - -ActivityTimeBasis: TypeAlias = ReportTimeBasis - - -@runtime_checkable -class ActivityEventLike(Protocol): - """Structural input required by an activity repository.""" - - @property - def event_id(self) -> str: ... - - @property - def project_id(self) -> str: ... - - @property - def scope_id(self) -> str | None: ... - - @property - def source(self) -> str: ... - - @property - def source_event_id(self) -> str: ... - - @property - def occurred_at(self) -> datetime | None: ... - - @property - def observed_at(self) -> datetime: ... - - @property - def time_basis(self) -> ActivityTimeBasis: ... - - @property - def trust(self) -> str: ... - - def model_dump(self, *, mode: Literal["json"], by_alias: Literal[True]) -> dict[str, object]: - """Return the complete canonical event payload.""" - - -@dataclass(frozen=True, slots=True) -class StoredActivityEvent: - """One stored observation plus its stable per-Project cursor.""" - - cursor: int - event_id: str - project_id: str - scope_id: str | None - source: str - source_event_id: str - occurred_at: datetime | None - observed_at: datetime - time_basis: ActivityTimeBasis - payload: Mapping[str, object] - - -class ActivityEventConflictError(HandoffReportError, ValueError): - """An idempotency key was reused for a different canonical event.""" - - def __init__(self, source: str, source_event_id: str) -> None: - super().__init__(f"activity event conflict for ({source!r}, {source_event_id!r})") - self.source = source - self.source_event_id = source_event_id - - -class InvalidActivityRepositoryArgumentError(HandoffReportError, ValueError): - """A repository argument is structurally invalid.""" - - def __init__(self, field: str, reason: str) -> None: - super().__init__(f"invalid {field}: {reason}") - - -class InvalidActivityEventError(HandoffReportError, ValueError): - """An activity does not satisfy the persistence boundary.""" - - def __init__(self, field: str, reason: str) -> None: - super().__init__(f"invalid activity event {field}: {reason}") - - -class ActivityEventSerializationError(HandoffReportError, TypeError): - """An activity cannot be converted to its canonical JSON payload.""" - - def __init__(self, operation: str, reason: str) -> None: - super().__init__(f"activity event serialization failed during {operation}: {reason}") - - -class StoredActivityEventError(HandoffReportError, RuntimeError): - """Persisted activity data violates the store schema.""" - - def __init__(self, field: str, reason: str) -> None: - super().__init__(f"invalid stored activity event {field}: {reason}") - - -class ActivityEventRepository(Protocol): - """Persistence operations needed by Activity capture and report assembly.""" - - async def record(self, connection: AsyncConnection, event: ActivityEventLike, /) -> StoredActivityEvent: - """Record an event or return an identical existing capture.""" - - async def list( - self, - connection: AsyncConnection, - project_id: str, - /, - *, - period_start: datetime | None = None, - period_end: datetime | None = None, - sources: Iterable[str] | None = None, - after_cursor: int = 0, - through_cursor: int | None = None, - limit: int | None = 50, - ) -> tuple[StoredActivityEvent, ...]: - """List a stable cursor-ordered Project page.""" - - async def high_watermark(self, connection: AsyncConnection, project_id: str, /) -> int: - """Return the latest allocated cursor without regressing after retention purge.""" - - async def purge(self, connection: AsyncConnection, project_id: str, observed_before: datetime, /) -> int: - """Delete expired Report-owned events and return the deleted row count.""" diff --git a/src/powercontext/builtin/handoff_report/selection.py b/src/powercontext/builtin/handoff_report/selection.py deleted file mode 100644 index 8766ef58f..000000000 --- a/src/powercontext/builtin/handoff_report/selection.py +++ /dev/null @@ -1,91 +0,0 @@ -# Copyright (c) 2026 OceanBase. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -"""Optimistic, read-only selection of exact Handoff heads.""" - -from __future__ import annotations - -from collections.abc import Sequence -from itertools import pairwise - -from powercontext.artifacts import ArtifactRef -from powercontext.builtin.handoff_report.errors import HandoffReportBusyError -from powercontext.builtin.handoff_report.models import ( - ReportSelectionEntry, - WorkstreamDescriptor, -) -from powercontext.builtin.handoff_report.protocols import HandoffReadAdapter - -DEFAULT_HANDOFF_SELECTION_ATTEMPTS = 3 -MAX_HANDOFF_SELECTION_ATTEMPTS = 5 - - -async def select_optimistic_stable_handoffs( - adapter: HandoffReadAdapter, - workstreams: Sequence[WorkstreamDescriptor], - /, - *, - attempts: int = DEFAULT_HANDOFF_SELECTION_ATTEMPTS, -) -> tuple[ReportSelectionEntry, ...]: - """Freeze exact heads after two equal vectors, retrying bounded instability.""" - - _validate_attempts(attempts) - ordered = _ordered_workstreams(workstreams) - for _ in range(attempts): - first = await _read_head_vector(adapter, ordered) - second = await _read_head_vector(adapter, ordered) - if first == second: - return tuple( - ReportSelectionEntry( - scope_id=workstream.scope_id, - workstream_revision=workstream.version, - status="no_handoff" if reference is None else "selected", - handoff_ref=reference, - ) - for workstream, reference in zip(ordered, second, strict=True) - ) - raise HandoffReportBusyError(attempts) - - -async def _read_head_vector( - adapter: HandoffReadAdapter, - workstreams: tuple[WorkstreamDescriptor, ...], -) -> tuple[ArtifactRef | None, ...]: - values: list[ArtifactRef | None] = [] - for workstream in workstreams: - handoff = await adapter.latest(workstream.scope_id) - values.append(None if handoff is None else handoff.as_ref()) - return tuple(values) - - -def _ordered_workstreams(values: Sequence[WorkstreamDescriptor]) -> tuple[WorkstreamDescriptor, ...]: - ordered = tuple(sorted(values, key=lambda value: value.scope_id)) - for previous, current in pairwise(ordered): - if previous.scope_id == current.scope_id: - raise ValueError(f"duplicate Workstream scope_id: {current.scope_id}") # noqa: TRY003 - return ordered - - -def _validate_attempts(value: int) -> None: - if not isinstance(value, int) or isinstance(value, bool) or not 1 <= value <= MAX_HANDOFF_SELECTION_ATTEMPTS: - raise ValueError( # noqa: TRY003 - f"attempts must be between 1 and {MAX_HANDOFF_SELECTION_ATTEMPTS}" - ) - - -__all__ = [ - "DEFAULT_HANDOFF_SELECTION_ATTEMPTS", - "MAX_HANDOFF_SELECTION_ATTEMPTS", - "select_optimistic_stable_handoffs", -] diff --git a/src/powercontext/builtin/handoff_report/service.py b/src/powercontext/builtin/handoff_report/service.py deleted file mode 100644 index 978252dc9..000000000 --- a/src/powercontext/builtin/handoff_report/service.py +++ /dev/null @@ -1,322 +0,0 @@ -# Copyright (c) 2026 OceanBase. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -"""Read-only assembly of canonical Handoff Reports.""" - -from __future__ import annotations - -from collections.abc import Sequence -from datetime import UTC, datetime - -from pydantic import JsonValue - -from powercontext.artifacts import ArtifactRef -from powercontext.builtin.artifacts.handoff import Handoff -from powercontext.builtin.handoff_report.canonical import finalize_digests -from powercontext.builtin.handoff_report.errors import ( - HandoffReportEvidenceCheckUnavailableError, - HandoffReportInconsistentError, -) -from powercontext.builtin.handoff_report.models import ( - ProjectDescriptor, - ReportActivityEvent, - ReportLocale, - WorkstreamDescriptor, - activity_sort_key, -) -from powercontext.builtin.handoff_report.protocols import HandoffReadAdapter, WorkContinuityReadAdapter -from powercontext.builtin.handoff_report.report import ( - MAX_REPORT_ACTIVITIES, - MAX_REPORT_HANDOFF_HISTORY, - MAX_REPORT_HANDOFF_HISTORY_EXCERPT_LENGTH, - MAX_REPORT_WORKSTREAMS, - HandoffReport, - HandoffRevisionSummary, - ReportActivityCoverageStatus, - ReportActivityStatus, - ReportCoverage, - ReportEvidenceChecks, - ReportFormat, - ReportKind, - ReportPeriodComparison, - ReportReportingStatus, - ReportSummary, - WorkstreamReport, -) -from powercontext.builtin.handoff_report.selection import select_optimistic_stable_handoffs -from powercontext.builtin.work import WorkContinuity - - -class HandoffReportService: - """Assemble reports without entering Handoff prepare, commit, or Continue control flow.""" - - def __init__( - self, - handoffs: HandoffReadAdapter, - /, - continuity: WorkContinuityReadAdapter | None = None, - ) -> None: - self._handoffs = handoffs - self._continuity = continuity - - async def generate( - self, - project: ProjectDescriptor, - workstreams: Sequence[WorkstreamDescriptor], - /, - *, - locale: ReportLocale | None = None, - include_evidence_checks: bool = True, - activities: Sequence[ReportActivityEvent] = (), - activity_cursor: int = 0, - activity_coverage: ReportActivityCoverageStatus = "not_configured", - generated_at: datetime | None = None, - selection_attempts: int = 3, - report_format: ReportFormat = "json", - report_kind: ReportKind = "handoff", - normalized_filters: dict[str, JsonValue] | None = None, - normalized_period: dict[str, JsonValue] | None = None, - period_comparison: ReportPeriodComparison | None = None, - ) -> HandoffReport: - """Freeze exact heads and project only exact Handoffs plus explicit Activity Events.""" - - ordered_workstreams = _validate_inputs(project, workstreams, activities, activity_cursor) - selection = await select_optimistic_stable_handoffs( - self._handoffs, - ordered_workstreams, - attempts=selection_attempts, - ) - activities_by_scope, unassigned = _group_activities(activities, ordered_workstreams) - projected: list[WorkstreamReport] = [] - for descriptor, entry in zip(ordered_workstreams, selection, strict=True): - scoped_activity = activities_by_scope.get(descriptor.scope_id, ()) - continuity = ( - WorkContinuity(scope_id=descriptor.scope_id) - if self._continuity is None - else await self._continuity.get(descriptor.scope_id, entry.handoff_ref) - ) - if entry.handoff_ref is None: - projected.append( - WorkstreamReport( - workstream=descriptor, - continuity=continuity, - handoff_ref=None, - content=None, - activities=scoped_activity, - work_status="no_handoff", - reporting_status="no_handoff", - activity_status=("activity_without_handoff" if scoped_activity else "no_observed_activity"), - handoff_activity_relation=None, - observed_activity_count=len(scoped_activity), - ) - ) - continue - - handoff = await self._handoffs.get(descriptor.scope_id, entry.handoff_ref) - if handoff.as_ref() != entry.handoff_ref: - raise HandoffReportInconsistentError(descriptor.scope_id) - revision_count, revision_history = await self._revision_history( - descriptor.scope_id, - entry.handoff_ref, - ) - checks: ReportEvidenceChecks = "not_checked" - evidence_unavailable = False - if include_evidence_checks: - try: - checks = await self._handoffs.check_evidence(descriptor.scope_id, entry.handoff_ref) - except HandoffReportEvidenceCheckUnavailableError: - evidence_unavailable = True - projected.append( - WorkstreamReport( - workstream=descriptor, - continuity=continuity, - handoff_ref=entry.handoff_ref, - content=handoff.content, - handoff_revision_count=revision_count, - handoff_history_truncated=revision_count > len(revision_history), - handoff_history=revision_history, - evidence_checks=checks, - evidence_unavailable=evidence_unavailable, - activities=scoped_activity, - work_status=handoff.content.disposition, - reporting_status=_reporting_status(handoff.content.omissions, checks, evidence_unavailable), - activity_status=_activity_status(scoped_activity), - handoff_activity_relation=(None if not scoped_activity else "unknown"), - observed_activity_count=len(scoped_activity), - ) - ) - - reports = tuple(projected) - activity_selection = tuple(event.event_id for report in reports for event in report.activities) + tuple( - event.event_id for event in unassigned - ) - report = HandoffReport( - locale=project.default_locale if locale is None else locale, - format=report_format, - report_kind=report_kind, - renderer_version="canonical-v1" if report_format == "json" else "markdown-v1", - generated_at=datetime.now(UTC) if generated_at is None else generated_at, - selection_consistency="optimistic_stable", - project=project, - project_revision=project.version, - normalized_filters={} if normalized_filters is None else normalized_filters, - normalized_period=normalized_period, - period_comparison=period_comparison, - end_selection=selection, - activity_cursor=activity_cursor, - activity_selection=activity_selection, - coverage=ReportCoverage( - total_included_workstreams=len(ordered_workstreams), - catalog_matched_workstreams=len(ordered_workstreams), - selected_workstreams=len(reports), - missing_handoff_workstreams=sum(item.handoff_ref is None for item in reports), - reported_with_omissions=sum(item.reporting_status == "reported_with_omissions" for item in reports), - unchecked_evidence_workstreams=sum( - item.handoff_ref is not None and item.evidence_checks == "not_checked" for item in reports - ), - unavailable_evidence_workstreams=sum( - item.reporting_status == "evidence_unavailable" for item in reports - ), - activity_without_handoff_workstreams=sum( - item.activity_status == "activity_without_handoff" for item in reports - ), - activity_after_handoff_workstreams=sum( - item.handoff_activity_relation == "activity_after_handoff" for item in reports - ), - unknown_time_events=sum( - event.effective_period_time() is None for item in reports for event in item.activities - ) - + sum(event.effective_period_time() is None for event in unassigned), - unassigned_activity_count=len(unassigned), - unassigned_activity_events=len(unassigned), - activity_coverage=activity_coverage, - ), - summary=ReportSummary( - continuable_count=sum(item.work_status == "continuable" for item in reports), - blocked_count=sum(item.work_status == "blocked" for item in reports), - complete_count=sum(item.work_status == "complete" for item in reports), - no_handoff_count=sum(item.work_status == "no_handoff" for item in reports), - ), - unassigned_activity=unassigned, - workstreams=reports, - ) - return finalize_digests(report) - - async def _revision_history( - self, - scope_id: str, - selected_ref: ArtifactRef, - /, - ) -> tuple[int, tuple[HandoffRevisionSummary, ...]]: - revisions = await self._handoffs.revisions(scope_id) - lifecycle = tuple( - handoff - for handoff in revisions - if handoff.as_ref().family == selected_ref.family and handoff.artifact_id == selected_ref.artifact_id - ) - references = tuple(handoff.as_ref() for handoff in lifecycle) - if tuple(reference.revision for reference in references) != tuple( - sorted({reference.revision for reference in references}) - ): - raise HandoffReportInconsistentError(scope_id) - try: - selected_index = references.index(selected_ref) - except ValueError as error: - raise HandoffReportInconsistentError(scope_id) from error - selected_history = lifecycle[: selected_index + 1] - recent_history = selected_history[-MAX_REPORT_HANDOFF_HISTORY:] - return len(selected_history), tuple(_revision_summary(handoff) for handoff in recent_history) - - -def _validate_inputs( - project: ProjectDescriptor, - workstreams: Sequence[WorkstreamDescriptor], - activities: Sequence[ReportActivityEvent], - activity_cursor: int, -) -> tuple[WorkstreamDescriptor, ...]: - if not isinstance(activity_cursor, int) or isinstance(activity_cursor, bool) or activity_cursor < 0: - raise ValueError("activity_cursor must be a non-negative integer") # noqa: TRY003 - if len(workstreams) > MAX_REPORT_WORKSTREAMS: - raise ValueError(f"a Handoff Report selects at most {MAX_REPORT_WORKSTREAMS} Workstreams") # noqa: TRY003 - if len(activities) > MAX_REPORT_ACTIVITIES: - raise ValueError(f"a Handoff Report selects at most {MAX_REPORT_ACTIVITIES} Activity Events") # noqa: TRY003 - ordered = tuple(sorted(workstreams, key=lambda value: value.scope_id)) - for workstream in ordered: - if workstream.project_id != project.project_id: - raise ValueError("every Workstream must belong to the requested Project") # noqa: TRY003 - if len({workstream.scope_id for workstream in ordered}) != len(ordered): - raise ValueError("Workstream scope_id values must be unique") # noqa: TRY003 - for event in activities: - if event.project_id != project.project_id: - raise ValueError("every Activity Event must belong to the requested Project") # noqa: TRY003 - return ordered - - -def _revision_summary(handoff: Handoff, /) -> HandoffRevisionSummary: - next_action = handoff.content.next_action - return HandoffRevisionSummary( - reference=handoff.as_ref(), - objective_excerpt=_history_excerpt(handoff.content.objective), - disposition=handoff.content.disposition, - next_action_excerpt=None if next_action is None else _history_excerpt(next_action.text), - state_count=len(handoff.content.state), - omission_count=len(handoff.content.omissions), - ) - - -def _history_excerpt(value: str, /) -> str: - compact = " ".join(value.split()) - if len(compact) <= MAX_REPORT_HANDOFF_HISTORY_EXCERPT_LENGTH: - return compact - return compact[: MAX_REPORT_HANDOFF_HISTORY_EXCERPT_LENGTH - 1].rstrip() + "…" - - -def _group_activities( - activities: Sequence[ReportActivityEvent], - workstreams: Sequence[WorkstreamDescriptor], -) -> tuple[dict[str, tuple[ReportActivityEvent, ...]], tuple[ReportActivityEvent, ...]]: - known_scopes = {workstream.scope_id for workstream in workstreams} - grouped: dict[str, list[ReportActivityEvent]] = {} - unassigned: list[ReportActivityEvent] = [] - for event in sorted(activities, key=activity_sort_key): - if event.scope_id is None or event.scope_id not in known_scopes: - unassigned.append(event) - else: - grouped.setdefault(event.scope_id, []).append(event) - return {scope_id: tuple(values) for scope_id, values in grouped.items()}, tuple(unassigned) - - -def _reporting_status( - omissions: tuple[object, ...], - checks: ReportEvidenceChecks, - evidence_unavailable: bool, -) -> ReportReportingStatus: - if evidence_unavailable or (checks != "not_checked" and any(check.status == "unavailable" for check in checks)): - return "evidence_unavailable" - if omissions: - return "reported_with_omissions" - return "reported" - - -def _activity_status(events: tuple[ReportActivityEvent, ...]) -> ReportActivityStatus: - if not events: - return "no_observed_activity" - if all(event.time_basis == "current_only" for event in events): - return "current_only" - # Existing Handoff has no authoritative commit timestamp, so the first slice - # must not claim that an observation happened after it. - return "unknown" - - -__all__ = ["HandoffReportService"] diff --git a/src/powercontext/builtin/handoff_report/sqlite.py b/src/powercontext/builtin/handoff_report/sqlite.py deleted file mode 100644 index 137ec61ca..000000000 --- a/src/powercontext/builtin/handoff_report/sqlite.py +++ /dev/null @@ -1,454 +0,0 @@ -# Copyright (c) 2026 OceanBase. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -"""SQLite-compatible relational Activity Event Store owned by Handoff Report.""" - -from __future__ import annotations - -import asyncio -import json -from collections.abc import Iterable, Mapping -from datetime import UTC, datetime -from typing import Any, cast - -from pydantic import ValidationError -from sqlalchemy import ( - BigInteger, - Column, - Index, - MetaData, - Table, - Text, - UniqueConstraint, - delete, - insert, - select, - update, -) -from sqlalchemy.dialects.mysql import insert as mysql_insert -from sqlalchemy.dialects.sqlite import insert as sqlite_insert -from sqlalchemy.exc import IntegrityError -from sqlalchemy.ext.asyncio import AsyncConnection - -from powercontext.builtin.handoff_report.catalog_store import HANDOFF_REPORT_CATALOG_TABLES -from powercontext.builtin.handoff_report.models import MAX_REPORT_ID_LENGTH, ReportActivityEvent -from powercontext.builtin.handoff_report.report import MAX_REPORT_ACTIVITIES -from powercontext.builtin.handoff_report.repository import ( - ActivityEventConflictError, - ActivityEventLike, - ActivityEventSerializationError, - ActivityTimeBasis, - InvalidActivityEventError, - InvalidActivityRepositoryArgumentError, - StoredActivityEvent, - StoredActivityEventError, -) -from powercontext.builtin.handoff_report.workspace_store import HANDOFF_REPORT_WORKSPACE_TABLES -from powercontext.builtin.persistence.tables import identity_string -from powercontext.limits import MAX_SCOPE_ID_LENGTH - -HANDOFF_REPORT_METADATA = MetaData() - -HANDOFF_REPORT_ACTIVITY_HEADS_TABLE = Table( - "pc_handoff_report_activity_heads", - HANDOFF_REPORT_METADATA, - Column("project_id", identity_string(MAX_REPORT_ID_LENGTH), primary_key=True), - Column("cursor", BigInteger, nullable=False), -) - -HANDOFF_REPORT_ACTIVITIES_TABLE = Table( - "pc_handoff_report_activities", - HANDOFF_REPORT_METADATA, - Column("project_id", identity_string(MAX_REPORT_ID_LENGTH), primary_key=True), - Column("cursor", BigInteger, primary_key=True), - Column("event_id", identity_string(MAX_REPORT_ID_LENGTH), nullable=False, unique=True), - Column("scope_id", identity_string(MAX_SCOPE_ID_LENGTH)), - Column("source", identity_string(64), nullable=False), - Column("source_event_id", identity_string(MAX_REPORT_ID_LENGTH), nullable=False), - Column("occurred_at", identity_string(32)), - Column("observed_at", identity_string(32), nullable=False), - Column("period_at", identity_string(32)), - Column("time_basis", identity_string(32), nullable=False), - Column("payload", Text, nullable=False), - UniqueConstraint("source", "source_event_id", name="uq_pc_handoff_report_activities_source_event"), -) -Index( - "ix_pc_handoff_report_activities_project_period", - HANDOFF_REPORT_ACTIVITIES_TABLE.c.project_id, - HANDOFF_REPORT_ACTIVITIES_TABLE.c.period_at, - HANDOFF_REPORT_ACTIVITIES_TABLE.c.cursor, -) -Index( - "ix_pc_handoff_report_activities_project_source_cursor", - HANDOFF_REPORT_ACTIVITIES_TABLE.c.project_id, - HANDOFF_REPORT_ACTIVITIES_TABLE.c.source, - HANDOFF_REPORT_ACTIVITIES_TABLE.c.cursor, -) - -HANDOFF_REPORT_TABLES = ( - *HANDOFF_REPORT_CATALOG_TABLES, - *HANDOFF_REPORT_WORKSPACE_TABLES, - HANDOFF_REPORT_ACTIVITY_HEADS_TABLE, - HANDOFF_REPORT_ACTIVITIES_TABLE, -) - -_TIME_BASES: frozenset[str] = frozenset({"source_reported", "host_observed", "first_seen", "current_only", "unknown"}) -_MAX_ACTIVITY_LIST_LIMIT = MAX_REPORT_ACTIVITIES + 1 - - -class SQLiteActivityEventRepository: - """Persist activity events without reading or writing Handoff/Core tables. - - The coroutine lock serializes ``record`` calls only through this repository - instance. Multiple instances or processes still rely on SQLite's writer lock - and configured busy timeout; deployments must handle lock timeout failures. - """ - - def __init__(self) -> None: - self._record_lock = asyncio.Lock() - - async def record(self, connection: AsyncConnection, event: ActivityEventLike, /) -> StoredActivityEvent: - payload, indexed = _canonical_event(event) - async with self._record_lock: - return await self._record_locked(connection, payload, indexed) - - async def _record_locked( - self, - connection: AsyncConnection, - payload: str, - indexed: Mapping[str, Any], - ) -> StoredActivityEvent: - # Take SQLite's writer reservation before the idempotency read. This - # avoids two DEFERRED/WAL transactions reading the same old snapshot - # and then both attempting to upgrade it to a writer. - await _reserve_project_writer(connection, str(indexed["project_id"])) - existing = await self._find_by_source_identity(connection, indexed["source"], indexed["source_event_id"]) - if existing is not None: - return _idempotent_result(existing, payload) - - cursor = await _allocate_cursor(connection, indexed["project_id"]) - try: - await connection.execute( - insert(HANDOFF_REPORT_ACTIVITIES_TABLE).values( - project_id=indexed["project_id"], - cursor=cursor, - event_id=indexed["event_id"], - scope_id=indexed["scope_id"], - source=indexed["source"], - source_event_id=indexed["source_event_id"], - occurred_at=indexed["occurred_at"], - observed_at=indexed["observed_at"], - period_at=indexed["period_at"], - time_basis=indexed["time_basis"], - payload=payload, - ) - ) - except IntegrityError: - existing = await self._find_by_source_identity(connection, indexed["source"], indexed["source_event_id"]) - if existing is None: - raise - return _idempotent_result(existing, payload) - - row = await self._find_by_project_cursor(connection, indexed["project_id"], cursor) - if row is None: # pragma: no cover - a successful insert must be visible in its transaction - raise StoredActivityEventError("event", "inserted row is not readable") - return _decode_row(row) - - async def list( - self, - connection: AsyncConnection, - project_id: str, - /, - *, - period_start: datetime | None = None, - period_end: datetime | None = None, - sources: Iterable[str] | None = None, - after_cursor: int = 0, - through_cursor: int | None = None, - limit: int | None = 50, - ) -> tuple[StoredActivityEvent, ...]: - project_id, start, end, normalized_sources = _validate_list_arguments( - project_id, - period_start=period_start, - period_end=period_end, - sources=sources, - after_cursor=after_cursor, - through_cursor=through_cursor, - limit=limit, - ) - if normalized_sources == (): - return () - statement = _activity_list_statement( - project_id, - start=start, - end=end, - sources=normalized_sources, - after_cursor=after_cursor, - through_cursor=through_cursor, - limit=limit, - ) - rows = (await connection.execute(statement)).mappings() - return tuple(_decode_row(row) for row in rows) - - async def high_watermark(self, connection: AsyncConnection, project_id: str, /) -> int: - project_id = _identifier("project_id", project_id, maximum=MAX_REPORT_ID_LENGTH) - value = await connection.scalar( - select(HANDOFF_REPORT_ACTIVITY_HEADS_TABLE.c.cursor).where( - HANDOFF_REPORT_ACTIVITY_HEADS_TABLE.c.project_id == project_id - ) - ) - return 0 if value is None else int(value) - - async def purge(self, connection: AsyncConnection, project_id: str, observed_before: datetime, /) -> int: - project_id = _identifier("project_id", project_id, maximum=MAX_REPORT_ID_LENGTH) - boundary = _utc_text("observed_before", observed_before) - result = await connection.execute( - delete(HANDOFF_REPORT_ACTIVITIES_TABLE).where( - HANDOFF_REPORT_ACTIVITIES_TABLE.c.project_id == project_id, - HANDOFF_REPORT_ACTIVITIES_TABLE.c.observed_at < boundary, - ) - ) - return int(result.rowcount or 0) - - async def _find_by_source_identity( - self, connection: AsyncConnection, source: str, source_event_id: str - ) -> Mapping[Any, Any] | None: - return ( - ( - await connection.execute( - select(HANDOFF_REPORT_ACTIVITIES_TABLE).where( - HANDOFF_REPORT_ACTIVITIES_TABLE.c.source == source, - HANDOFF_REPORT_ACTIVITIES_TABLE.c.source_event_id == source_event_id, - ) - ) - ) - .mappings() - .one_or_none() - ) - - async def _find_by_project_cursor( - self, connection: AsyncConnection, project_id: str, cursor: int - ) -> Mapping[Any, Any] | None: - return ( - ( - await connection.execute( - select(HANDOFF_REPORT_ACTIVITIES_TABLE).where( - HANDOFF_REPORT_ACTIVITIES_TABLE.c.project_id == project_id, - HANDOFF_REPORT_ACTIVITIES_TABLE.c.cursor == cursor, - ) - ) - ) - .mappings() - .one_or_none() - ) - - -def _validate_list_arguments( - project_id: str, - *, - period_start: datetime | None, - period_end: datetime | None, - sources: Iterable[str] | None, - after_cursor: int, - through_cursor: int | None, - limit: int | None, -) -> tuple[str, str | None, str | None, tuple[str, ...] | None]: - project_id = _identifier("project_id", project_id, maximum=MAX_REPORT_ID_LENGTH) - _require_integer("after_cursor", after_cursor, minimum=0) - if through_cursor is not None: - _require_integer("through_cursor", through_cursor, minimum=0) - if limit is not None: - _require_integer("limit", limit, minimum=1, maximum=_MAX_ACTIVITY_LIST_LIMIT) - start = None if period_start is None else _utc_text("period_start", period_start) - end = None if period_end is None else _utc_text("period_end", period_end) - if start is not None and end is not None and start >= end: - raise InvalidActivityRepositoryArgumentError("period", "start must be before end") - normalized_sources = None - if sources is not None: - normalized_sources = tuple(dict.fromkeys(_identifier("source", item, maximum=64) for item in sources)) - return project_id, start, end, normalized_sources - - -def _activity_list_statement( - project_id: str, - *, - start: str | None, - end: str | None, - sources: tuple[str, ...] | None, - after_cursor: int, - through_cursor: int | None, - limit: int | None, -): - statement = select(HANDOFF_REPORT_ACTIVITIES_TABLE).where( - HANDOFF_REPORT_ACTIVITIES_TABLE.c.project_id == project_id, - HANDOFF_REPORT_ACTIVITIES_TABLE.c.cursor > after_cursor, - ) - if through_cursor is not None: - statement = statement.where(HANDOFF_REPORT_ACTIVITIES_TABLE.c.cursor <= through_cursor) - if start is not None: - statement = statement.where(HANDOFF_REPORT_ACTIVITIES_TABLE.c.period_at >= start) - if end is not None: - statement = statement.where(HANDOFF_REPORT_ACTIVITIES_TABLE.c.period_at < end) - if sources is not None: - statement = statement.where(HANDOFF_REPORT_ACTIVITIES_TABLE.c.source.in_(sources)) - statement = statement.order_by(HANDOFF_REPORT_ACTIVITIES_TABLE.c.cursor) - return statement if limit is None else statement.limit(limit) - - -async def _reserve_project_writer(connection: AsyncConnection, project_id: str) -> None: - dialect = connection.dialect.name - if dialect == "sqlite": - statement = sqlite_insert(HANDOFF_REPORT_ACTIVITY_HEADS_TABLE).values(project_id=project_id, cursor=0) - statement = statement.on_conflict_do_update( - index_elements=(HANDOFF_REPORT_ACTIVITY_HEADS_TABLE.c.project_id,), - set_={"cursor": HANDOFF_REPORT_ACTIVITY_HEADS_TABLE.c.cursor}, - ) - elif dialect == "mysql": - statement = mysql_insert(HANDOFF_REPORT_ACTIVITY_HEADS_TABLE).values(project_id=project_id, cursor=0) - statement = statement.on_duplicate_key_update(cursor=HANDOFF_REPORT_ACTIVITY_HEADS_TABLE.c.cursor) - else: - raise InvalidActivityRepositoryArgumentError("dialect", f"unsupported database dialect: {dialect}") - await connection.execute(statement) - - -async def _allocate_cursor(connection: AsyncConnection, project_id: str) -> int: - result = await connection.execute( - update(HANDOFF_REPORT_ACTIVITY_HEADS_TABLE) - .where(HANDOFF_REPORT_ACTIVITY_HEADS_TABLE.c.project_id == project_id) - .values(cursor=HANDOFF_REPORT_ACTIVITY_HEADS_TABLE.c.cursor + 1) - ) - if result.rowcount != 1: - raise StoredActivityEventError("cursor", "Project allocator is missing") - value = await connection.scalar( - select(HANDOFF_REPORT_ACTIVITY_HEADS_TABLE.c.cursor).where( - HANDOFF_REPORT_ACTIVITY_HEADS_TABLE.c.project_id == project_id - ) - ) - if not isinstance(value, int) or isinstance(value, bool) or value < 1: - raise StoredActivityEventError("cursor", "must be a positive integer") - return value - - -def _canonical_event(event: ActivityEventLike) -> tuple[str, dict[str, Any]]: - try: - dumped = event.model_dump(mode="json", by_alias=True) - except (AttributeError, TypeError, ValueError) as error: - raise ActivityEventSerializationError("model_dump", "JSON mode failed") from error - if not isinstance(dumped, dict): - raise ActivityEventSerializationError("model_dump", "result must be a dictionary") - try: - candidate_payload = json.dumps( - dumped, - ensure_ascii=False, - sort_keys=True, - separators=(",", ":"), - allow_nan=False, - ) - except (TypeError, ValueError) as error: - raise ActivityEventSerializationError("JSON encoding", "not serializable") from error # noqa: TRY003 - try: - validated = ReportActivityEvent.model_validate_json(candidate_payload) - except ValidationError as error: - raise InvalidActivityEventError("payload", "does not match ReportActivityEvent") from error - - canonical = validated.model_dump(mode="json", by_alias=True) - payload = json.dumps(canonical, ensure_ascii=False, sort_keys=True, separators=(",", ":"), allow_nan=False) - event_id = _identifier("event_id", validated.event_id, maximum=MAX_REPORT_ID_LENGTH) - project_id = _identifier("project_id", validated.project_id, maximum=MAX_REPORT_ID_LENGTH) - scope_id = ( - None if validated.scope_id is None else _identifier("scope_id", validated.scope_id, maximum=MAX_SCOPE_ID_LENGTH) - ) - source = _identifier("source", validated.source, maximum=64) - source_event_id = _identifier("source_event_id", validated.source_event_id, maximum=MAX_REPORT_ID_LENGTH) - observed_at = _utc_text("observed_at", validated.observed_at) - occurred_at = None if validated.occurred_at is None else _utc_text("occurred_at", validated.occurred_at) - period_time = validated.effective_period_time() - period_at = None if period_time is None else _utc_text("period_at", period_time) - return payload, { - "event_id": event_id, - "project_id": project_id, - "scope_id": scope_id, - "source": source, - "source_event_id": source_event_id, - "occurred_at": occurred_at, - "observed_at": observed_at, - "period_at": period_at, - "time_basis": validated.time_basis, - } - - -def _idempotent_result(row: Mapping[Any, Any], payload: str) -> StoredActivityEvent: - if _semantic_payload(str(row["payload"])) != _semantic_payload(payload): - raise ActivityEventConflictError(str(row["source"]), str(row["source_event_id"])) - return _decode_row(row) - - -def _semantic_payload(payload: str) -> str: - try: - value = json.loads(payload) - except (TypeError, ValueError) as error: - raise StoredActivityEventError("payload", "must be valid JSON") from error - if not isinstance(value, dict): - raise StoredActivityEventError("payload", "must be a JSON object") - value.pop("event_id", None) - value.pop("observed_at", None) - return json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":"), allow_nan=False) - - -def _decode_row(row: Mapping[Any, Any]) -> StoredActivityEvent: - time_basis = str(row["time_basis"]) - if time_basis not in _TIME_BASES: - raise StoredActivityEventError("time_basis", "unsupported value") - payload = json.loads(str(row["payload"])) - if not isinstance(payload, dict): - raise StoredActivityEventError("payload", "must be a JSON object") - return StoredActivityEvent( - cursor=int(row["cursor"]), - event_id=str(row["event_id"]), - project_id=str(row["project_id"]), - scope_id=None if row["scope_id"] is None else str(row["scope_id"]), - source=str(row["source"]), - source_event_id=str(row["source_event_id"]), - occurred_at=None if row["occurred_at"] is None else _parse_utc(str(row["occurred_at"])), - observed_at=_parse_utc(str(row["observed_at"])), - time_basis=cast(ActivityTimeBasis, time_basis), - payload=payload, - ) - - -def _identifier(field: str, value: object, *, maximum: int) -> str: - if not isinstance(value, str) or not value or value != value.strip(): - raise InvalidActivityRepositoryArgumentError(field, "must be a non-empty trimmed string") - if len(value) > maximum: - raise InvalidActivityRepositoryArgumentError(field, f"must not exceed {maximum} characters") - return value - - -def _require_integer(field: str, value: object, *, minimum: int, maximum: int | None = None) -> None: - if not isinstance(value, int) or isinstance(value, bool): - raise InvalidActivityRepositoryArgumentError(field, "must be an integer") - if value < minimum: - raise InvalidActivityRepositoryArgumentError(field, f"must be at least {minimum}") - if maximum is not None and value > maximum: - raise InvalidActivityRepositoryArgumentError(field, f"must not exceed {maximum}") - - -def _utc_text(field: str, value: datetime) -> str: - if not isinstance(value, datetime) or value.tzinfo is None or value.utcoffset() is None: - raise InvalidActivityRepositoryArgumentError(field, "must be timezone-aware") - return value.astimezone(UTC).isoformat(timespec="microseconds").replace("+00:00", "Z") - - -def _parse_utc(value: str) -> datetime: - return datetime.fromisoformat(value.replace("Z", "+00:00")).astimezone(UTC) diff --git a/src/powercontext/builtin/handoff_report/workspace.py b/src/powercontext/builtin/handoff_report/workspace.py deleted file mode 100644 index 04e92a5af..000000000 --- a/src/powercontext/builtin/handoff_report/workspace.py +++ /dev/null @@ -1,101 +0,0 @@ -# Copyright (c) 2026 OceanBase. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -"""Explicit WorkspaceBinding application operations.""" - -from __future__ import annotations - -from datetime import UTC, datetime - -from sqlalchemy.ext.asyncio import AsyncConnection - -from powercontext.builtin.handoff_report.catalog import HandoffReportCatalog -from powercontext.builtin.handoff_report.errors import ( - WorkspaceBindingConflictError, - WorkspaceBindingNotFoundError, -) -from powercontext.builtin.handoff_report.models import RepositoryRef, WorkspaceBinding, normalize_repository_ref -from powercontext.builtin.handoff_report.workspace_store import WorkspaceBindingRepository - - -class WorkspaceBindingService: - """Attach and detach a workspace only after exact Project selection.""" - - def __init__( - self, - catalog: HandoffReportCatalog | None = None, - repository: WorkspaceBindingRepository | None = None, - ) -> None: - self._catalog = HandoffReportCatalog() if catalog is None else catalog - self._repository = WorkspaceBindingRepository() if repository is None else repository - - async def get(self, connection: AsyncConnection, workspace_instance_id: str, /) -> WorkspaceBinding: - return await self._repository.get_confirmed(connection, workspace_instance_id) - - async def attach( - self, - connection: AsyncConnection, - *, - workspace_instance_id: str, - project_id: str, - repository_ref: RepositoryRef, - expected_version: int | None, - confirmed_at: datetime | None = None, - ) -> WorkspaceBinding: - await self._catalog.get_project(connection, project_id) - normalized_ref = normalize_repository_ref(repository_ref) - current = None - if expected_version is not None: - try: - current = await self._repository.get(connection, workspace_instance_id) - except WorkspaceBindingNotFoundError as error: - raise WorkspaceBindingConflictError( - workspace_instance_id, - expected_version, - None, - detail="workspace binding record is missing", - ) from error - version = 1 if expected_version is None else expected_version + 1 - binding = WorkspaceBinding( - workspace_instance_id=workspace_instance_id, - project_id=project_id, - repository_ref=normalized_ref, - state="confirmed", - confirmed_at=datetime.now(UTC) if confirmed_at is None else confirmed_at, - version=version, - ) - if current is not None and current.state == "confirmed" and current.project_id != project_id: - raise WorkspaceBindingConflictError( - workspace_instance_id, - expected_version, - current.version, - detail="detach the confirmed binding before attaching another Project", - ) - return await self._repository.attach(connection, binding, expected_version) - - async def detach( - self, - connection: AsyncConnection, - workspace_instance_id: str, - expected_version: int, - ) -> WorkspaceBinding: - return await self._repository.detach(connection, workspace_instance_id, expected_version) - - async def get_record(self, connection: AsyncConnection, workspace_instance_id: str, /) -> WorkspaceBinding: - """Read a detached record for explicit re-attach workflows.""" - - return await self._repository.get(connection, workspace_instance_id) - - -__all__ = ["WorkspaceBindingService"] diff --git a/src/powercontext/builtin/handoff_report/workspace_store.py b/src/powercontext/builtin/handoff_report/workspace_store.py deleted file mode 100644 index 9c8f466fc..000000000 --- a/src/powercontext/builtin/handoff_report/workspace_store.py +++ /dev/null @@ -1,322 +0,0 @@ -# Copyright (c) 2026 OceanBase. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -"""Report-owned persistence for explicit WorkspaceBinding CAS transitions.""" - -from __future__ import annotations - -import json -from collections.abc import Mapping -from datetime import UTC, datetime -from typing import Any - -from pydantic import ValidationError -from sqlalchemy import CheckConstraint, Column, Integer, MetaData, Table, Text, insert, select, update -from sqlalchemy.exc import IntegrityError -from sqlalchemy.ext.asyncio import AsyncConnection - -from powercontext.builtin.handoff_report.errors import ( - HandoffReportCatalogArgumentError, - InvalidStoredCatalogError, - WorkspaceBindingConflictError, - WorkspaceBindingNotFoundError, -) -from powercontext.builtin.handoff_report.models import ( - MAX_REPORT_ID_LENGTH, - MAX_REPORT_NORMALIZED_REMOTE_LENGTH, - MAX_REPORT_REPOSITORY_ID_LENGTH, - MAX_REPORT_SUBPATH_LENGTH, - MAX_WORKSPACE_INSTANCE_ID_LENGTH, - WorkspaceBinding, -) -from powercontext.builtin.persistence.tables import identity_string - -HANDOFF_REPORT_WORKSPACE_METADATA = MetaData() - -HANDOFF_REPORT_WORKSPACE_BINDINGS_TABLE = Table( - "pc_handoff_report_workspace_bindings", - HANDOFF_REPORT_WORKSPACE_METADATA, - Column("workspace_instance_id", identity_string(MAX_WORKSPACE_INSTANCE_ID_LENGTH), primary_key=True), - Column("project_id", identity_string(MAX_REPORT_ID_LENGTH), nullable=False), - Column("provider", identity_string(32), nullable=False), - Column("repository_id", identity_string(MAX_REPORT_REPOSITORY_ID_LENGTH)), - Column("normalized_remote", identity_string(MAX_REPORT_NORMALIZED_REMOTE_LENGTH)), - Column("subpath", identity_string(MAX_REPORT_SUBPATH_LENGTH)), - Column("state", identity_string(16), nullable=False), - Column("confirmed_at", identity_string(32), nullable=False), - Column("version", Integer, nullable=False), - Column("payload", Text, nullable=False), - CheckConstraint("version > 0", name="ck_pc_handoff_report_workspace_bindings_version_positive"), -) - -HANDOFF_REPORT_WORKSPACE_TABLES = (HANDOFF_REPORT_WORKSPACE_BINDINGS_TABLE,) - - -class WorkspaceBindingRepository: - """Store one mutable binding record per local workspace instance.""" - - async def get( - self, - connection: AsyncConnection, - workspace_instance_id: str, - /, - ) -> WorkspaceBinding: - workspace_instance_id = _identifier( - "workspace_instance_id", - workspace_instance_id, - MAX_WORKSPACE_INSTANCE_ID_LENGTH, - ) - row = await self._find(connection, workspace_instance_id) - if row is None: - raise WorkspaceBindingNotFoundError(workspace_instance_id) - return _decode_binding(row) - - async def get_confirmed( - self, - connection: AsyncConnection, - workspace_instance_id: str, - /, - ) -> WorkspaceBinding: - binding = await self.get(connection, workspace_instance_id) - if binding.state != "confirmed": - raise WorkspaceBindingNotFoundError(workspace_instance_id) - return binding - - async def attach( - self, - connection: AsyncConnection, - binding: WorkspaceBinding, - expected_version: int | None, - /, - ) -> WorkspaceBinding: - _validate_binding(binding) - if binding.state != "confirmed": - raise HandoffReportCatalogArgumentError("state", "attach requires a confirmed binding") - _optional_version(expected_version) - current = await self._find(connection, binding.workspace_instance_id) - if expected_version is None: - return await self._attach_absent(connection, binding, current) - return await self._attach_existing(connection, binding, expected_version, current) - - async def _attach_absent( - self, - connection: AsyncConnection, - binding: WorkspaceBinding, - current: Mapping[Any, Any] | None, - ) -> WorkspaceBinding: - if binding.version != 1: - raise HandoffReportCatalogArgumentError( - "version", - "an expect-absent attach must create version 1", - ) - if current is not None: - raise WorkspaceBindingConflictError( - binding.workspace_instance_id, - None, - int(current["version"]), - detail="workspace already has a binding record", - ) - try: - await connection.execute(insert(HANDOFF_REPORT_WORKSPACE_BINDINGS_TABLE).values(_row(binding))) - except IntegrityError as error: - raise WorkspaceBindingConflictError( - binding.workspace_instance_id, - None, - None, - detail="workspace already has a binding record", - ) from error - return binding - - async def _attach_existing( - self, - connection: AsyncConnection, - binding: WorkspaceBinding, - expected_version: int, - current: Mapping[Any, Any] | None, - ) -> WorkspaceBinding: - if current is None: - raise WorkspaceBindingConflictError( - binding.workspace_instance_id, - expected_version, - None, - detail="workspace binding record is missing", - ) - current_binding = _decode_binding(current) - if current_binding.version != expected_version: - raise WorkspaceBindingConflictError( - binding.workspace_instance_id, - expected_version, - current_binding.version, - ) - if binding.version != expected_version + 1: - raise HandoffReportCatalogArgumentError( - "version", - "updated binding version must equal expected_version + 1", - ) - if current_binding.state == "confirmed" and current_binding.project_id != binding.project_id: - raise WorkspaceBindingConflictError( - binding.workspace_instance_id, - expected_version, - current_binding.version, - detail="detach the confirmed binding before attaching another Project", - ) - result = await connection.execute( - update(HANDOFF_REPORT_WORKSPACE_BINDINGS_TABLE) - .where( - HANDOFF_REPORT_WORKSPACE_BINDINGS_TABLE.c.workspace_instance_id == binding.workspace_instance_id, - HANDOFF_REPORT_WORKSPACE_BINDINGS_TABLE.c.version == expected_version, - ) - .values(_row(binding)) - ) - if result.rowcount != 1: - latest = await self.get(connection, binding.workspace_instance_id) - raise WorkspaceBindingConflictError( - binding.workspace_instance_id, - expected_version, - latest.version, - ) - return binding - - async def detach( - self, - connection: AsyncConnection, - workspace_instance_id: str, - expected_version: int, - /, - ) -> WorkspaceBinding: - workspace_instance_id = _identifier( - "workspace_instance_id", - workspace_instance_id, - MAX_WORKSPACE_INSTANCE_ID_LENGTH, - ) - _required_version(expected_version) - current = await self._find(connection, workspace_instance_id) - if current is None: - raise WorkspaceBindingConflictError( - workspace_instance_id, - expected_version, - None, - detail="workspace binding record is missing", - ) - binding = _decode_binding(current) - if binding.version != expected_version: - raise WorkspaceBindingConflictError(workspace_instance_id, expected_version, binding.version) - if binding.state != "confirmed": - raise WorkspaceBindingConflictError( - workspace_instance_id, - expected_version, - binding.version, - detail="workspace binding is already detached", - ) - detached = binding.model_copy(update={"state": "detached", "version": expected_version + 1}) - result = await connection.execute( - update(HANDOFF_REPORT_WORKSPACE_BINDINGS_TABLE) - .where( - HANDOFF_REPORT_WORKSPACE_BINDINGS_TABLE.c.workspace_instance_id == workspace_instance_id, - HANDOFF_REPORT_WORKSPACE_BINDINGS_TABLE.c.version == expected_version, - ) - .values(_row(detached)) - ) - if result.rowcount != 1: - latest = await self.get(connection, workspace_instance_id) - raise WorkspaceBindingConflictError( - workspace_instance_id, - expected_version, - latest.version, - ) - return detached - - async def _find(self, connection: AsyncConnection, workspace_instance_id: str) -> Mapping[Any, Any] | None: - return ( - ( - await connection.execute( - select(HANDOFF_REPORT_WORKSPACE_BINDINGS_TABLE).where( - HANDOFF_REPORT_WORKSPACE_BINDINGS_TABLE.c.workspace_instance_id == workspace_instance_id - ) - ) - ) - .mappings() - .one_or_none() - ) - - -def _validate_binding(value: WorkspaceBinding) -> None: - if not isinstance(value, WorkspaceBinding): - raise HandoffReportCatalogArgumentError("binding", "must be a WorkspaceBinding") - - -def _row(binding: WorkspaceBinding) -> dict[str, object]: - reference = binding.repository_ref - return { - "workspace_instance_id": binding.workspace_instance_id, - "project_id": binding.project_id, - "provider": reference.provider, - "repository_id": reference.repository_id, - "normalized_remote": reference.normalized_remote, - "subpath": reference.subpath, - "state": binding.state, - "confirmed_at": _utc_text(binding.confirmed_at), - "version": binding.version, - "payload": json.dumps( - binding.model_dump(mode="json", by_alias=True), - ensure_ascii=False, - sort_keys=True, - separators=(",", ":"), - allow_nan=False, - ), - } - - -def _decode_binding(row: Mapping[Any, Any]) -> WorkspaceBinding: - try: - value = WorkspaceBinding.model_validate_json(str(row["payload"])) - except ValidationError as error: - raise InvalidStoredCatalogError("WorkspaceBinding", "does not match its schema") from error - if value.workspace_instance_id != str(row["workspace_instance_id"]) or value.version != int(row["version"]): - raise InvalidStoredCatalogError( - "WorkspaceBinding", - "identity does not match indexed columns", - ) - return value - - -def _identifier(field: str, value: object, maximum: int) -> str: - if not isinstance(value, str) or not value or value != value.strip(): - raise HandoffReportCatalogArgumentError(field, "must be a non-empty trimmed string") - if len(value) > maximum: - raise HandoffReportCatalogArgumentError(field, f"must not exceed {maximum} characters") - return value - - -def _required_version(value: object) -> None: - if not isinstance(value, int) or isinstance(value, bool) or value < 1: - raise HandoffReportCatalogArgumentError("expected_version", "must be a positive integer") - - -def _optional_version(value: object) -> None: - if value is not None: - _required_version(value) - - -def _utc_text(value: datetime) -> str: - if value.tzinfo is None or value.utcoffset() is None: - raise HandoffReportCatalogArgumentError("confirmed_at", "must include a UTC offset") - return value.astimezone(UTC).isoformat(timespec="microseconds").replace("+00:00", "Z") - - -__all__ = [ - "HANDOFF_REPORT_WORKSPACE_BINDINGS_TABLE", - "HANDOFF_REPORT_WORKSPACE_TABLES", - "WorkspaceBindingRepository", -] diff --git a/src/powercontext/builtin/runtime/__init__.py b/src/powercontext/builtin/runtime/__init__.py index ef7eba4e3..1268ff1c7 100644 --- a/src/powercontext/builtin/runtime/__init__.py +++ b/src/powercontext/builtin/runtime/__init__.py @@ -151,6 +151,7 @@ RecallTokenStatistics, RecallTokenValue, ResolvedUsagePeriod, + ScopeStatistics, SourceInventoryStatistics, Statistics, StatisticsPeriod, @@ -260,6 +261,7 @@ "RuntimeReadinessStatus", "ScheduledExperienceProcessor", "ScheduledSourceProcessor", + "ScopeStatistics", "ScopedExperienceApplication", "ScopedExternalSkillApplication", "ScopedHandoffApplication", diff --git a/src/powercontext/builtin/runtime/application.py b/src/powercontext/builtin/runtime/application.py index 750b7d20e..4b0a01dc4 100644 --- a/src/powercontext/builtin/runtime/application.py +++ b/src/powercontext/builtin/runtime/application.py @@ -71,6 +71,7 @@ from powercontext.builtin.context import BuiltinArtifacts, BuiltinSources from powercontext.builtin.inference.models import InferenceUsage from powercontext.builtin.inference.usage import bind_usage_reporter +from powercontext.builtin.publication import ArtifactPublicationApplication from powercontext.builtin.review.generation import GeneratedCandidateResult, ReviewedGenerationService from powercontext.builtin.review.service import ReviewService from powercontext.builtin.runtime._scope_cache import ( @@ -119,7 +120,12 @@ SkillCandidate, SourceReceipt, ) -from powercontext.builtin.runtime.prepared_context import PreparedContextBuild, PreparedContextBuilder +from powercontext.builtin.runtime.prepared_context import ( + PreparedContextBuild, + PreparedContextBuilder, + PreparedExperienceCandidates, + PreparedMemoryCandidates, +) from powercontext.builtin.runtime.protocols import ( BuiltinTriggers, PowerContextProvider, @@ -133,6 +139,7 @@ RuntimeReadinessChecks, ) from powercontext.builtin.runtime.statistics import RelationalScopedStatistics +from powercontext.builtin.scope import ScopeApplication, ScopeNotFoundError, ScopeSelection from powercontext.builtin.sources import ( ContentCapture, ContentSource, @@ -147,6 +154,7 @@ Statistics, StatisticsPeriod, ) +from powercontext.builtin.statistics.aggregation import aggregate_statistics from powercontext.builtin.work import ( HANDOFF_BOUNDARY_SOURCE_KIND, HANDOFF_RECEIPT_SOURCE_KIND, @@ -322,6 +330,27 @@ def __init__(self, runtime: BuiltinRuntime) -> None: def for_scope(self, scope_id: str, /) -> ScopedStatisticsApplication: return ScopedStatisticsApplication(self._runtime, scope_id) + async def overview( + self, + selection: ScopeSelection, + *, + period: StatisticsPeriod = StatisticsPeriod.THIRTY_DAYS, + ) -> Statistics: + if self._runtime.scopes is None: + raise _RuntimeStateError("statistics") + async with self._runtime._operation(): + resolved = await self._runtime.scopes.resolve_selection(selection) + captured_at = self._runtime._clock() + snapshots = tuple([ + await self._runtime._statistics(scope.scope_id).overview(period, captured_at) for scope in resolved + ]) + return aggregate_statistics( + selection, + tuple(scope.scope_id for scope in resolved), + snapshots, + captured_at, + ) + class ScopedContextApplication: """Prepare final context for one scope using Runtime-owned source policy.""" @@ -336,26 +365,103 @@ async def prepare(self, request: PrepareContextRequest, /) -> PreparedContext: async def _prepare(self, request: PrepareContextRequest, /) -> PreparedContext: builder = PreparedContextBuilder() + scope_ids = [self.scope_id] + if self._runtime.scopes is not None: + try: + scope = await self._runtime.scopes.get(self.scope_id) + except ScopeNotFoundError: + pass + else: + scope_ids.extend(scope.context_references) + + memory_candidates: list[PreparedMemoryCandidates] = [] + experience_candidates: list[PreparedExperienceCandidates] = [] + remaining_memory = builder.memory_candidate_limit + remaining_experience = builder.experience_candidate_limit + for scope_id in scope_ids: + memory, experiences = await self._recall_scope( + scope_id, + request, + memory_limit=remaining_memory, + experience_limit=remaining_experience, + ) + memory_candidates.append(memory) + experience_candidates.append(experiences) + remaining_memory -= len(memory.hits) + remaining_experience -= len(experiences.hits) + + with self._runtime._stage( + "context.build", + attributes={ + "powercontext.context.build.scope_count": len(scope_ids), + "powercontext.context.build.memory_candidate_count": sum( + len(candidates.hits) for candidates in memory_candidates + ), + "powercontext.context.build.experience_candidate_count": sum( + len(candidates.hits) for candidates in experience_candidates + ), + }, + ) as span: + build = builder.build_scopes_result( + request=request, + current_scope_id=self.scope_id, + memory_candidates=memory_candidates, + experience_candidates=experience_candidates, + ) + if span is not None: + span.set_attributes({ + "powercontext.context.build.selected_count": len(build.origins), + "powercontext.context.build.status": build.context.status, + "powercontext.context.build.content_bytes": build.context.content_bytes, + }) + if self._runtime._recall_token_estimator is not None: + try: + measurement = await self._runtime._recall_token_estimator(self.scope_id, build) + except Exception as error: + log_safely( + logger, + logging.ERROR, + "Recall token estimation failed", + exc_info=error, + extra={ + "event": "statistics.recall_tokens.estimation_failed", + "outcome": "failure", + "unit": "statistics", + }, + ) + else: + if measurement is not None: + await self._runtime.statistics.for_scope(self.scope_id).record_recall(measurement) + return build.context + + async def _recall_scope( + self, + scope_id: str, + request: PrepareContextRequest, + *, + memory_limit: int, + experience_limit: int, + ) -> tuple[PreparedMemoryCandidates, PreparedExperienceCandidates]: async with ( - self._runtime._context(self.scope_id, embedding_purpose=ModelUsagePurpose.MEMORY_RECALL) as context, - self._runtime._locked(self.scope_id), + self._runtime._context(scope_id, embedding_purpose=ModelUsagePurpose.MEMORY_RECALL) as context, + self._runtime._locked(scope_id), ): with self._runtime._stage( _MEMORY_SEARCH_STAGE, attributes={ _MEMORY_SEARCH_REQUESTED_MODE: "auto", - _MEMORY_SEARCH_LIMIT: builder.memory_candidate_limit, + _MEMORY_SEARCH_LIMIT: memory_limit, }, ) as span: service = context.artifacts.memory current = await _head_or_none(service, context.artifacts.memory_artifact_id) memory_hits = () search_mode: str | None = None - if current is not None: + if current is not None and memory_limit > 0: result = await service.search( request.query, memories=(current,), - limit=builder.memory_candidate_limit, + limit=memory_limit, mode="auto", ) memory_hits = result.hits @@ -374,59 +480,28 @@ async def _prepare(self, request: PrepareContextRequest, /) -> PreparedContext: "experience.search", attributes={ "powercontext.experience.search.configured": experience_recall is not None, - "powercontext.experience.search.limit": builder.experience_candidate_limit, + "powercontext.experience.search.limit": experience_limit, }, ) as span: experience_hits = ( () - if experience_recall is None + if experience_recall is None or experience_limit == 0 else await experience_recall( - self.scope_id, + scope_id, request.query, - builder.experience_candidate_limit, + experience_limit, ) ) if span is not None: span.set_attributes({"powercontext.experience.search.result_count": len(experience_hits)}) - - with self._runtime._stage( - "context.build", - attributes={ - "powercontext.context.build.memory_candidate_count": len(memory_hits), - "powercontext.context.build.experience_candidate_count": len(experience_hits), - }, - ) as span: - build = builder.build_result( - request=request, - memory_ref=None if current is None else current.as_ref(), - hits=memory_hits, - experience_hits=experience_hits, - ) - if span is not None: - span.set_attributes({ - "powercontext.context.build.selected_count": len(build.origins), - "powercontext.context.build.status": build.context.status, - "powercontext.context.build.content_bytes": build.context.content_bytes, - }) - if self._runtime._recall_token_estimator is not None: - try: - measurement = await self._runtime._recall_token_estimator(self.scope_id, build) - except Exception as error: - log_safely( - logger, - logging.ERROR, - "Recall token estimation failed", - exc_info=error, - extra={ - "event": "statistics.recall_tokens.estimation_failed", - "outcome": "failure", - "unit": "statistics", - }, - ) - else: - if measurement is not None: - await self._runtime.statistics.for_scope(self.scope_id).record_recall(measurement) - return build.context + return ( + PreparedMemoryCandidates( + scope_id=scope_id, + memory_ref=None if current is None else current.as_ref(), + hits=memory_hits, + ), + PreparedExperienceCandidates(scope_id=scope_id, hits=experience_hits), + ) class ContextApplication: @@ -1227,6 +1302,8 @@ def __init__( external_skill_importer: ExternalSkillImporter | None = None, statistics_service: StatisticsServiceFactory | None = None, recall_token_estimator: RecallTokenEstimator | None = None, + publication_application: ArtifactPublicationApplication | None = None, + scope_application: ScopeApplication | None = None, readiness: RuntimeReadinessChecks | None = None, clock: Clock | None = None, tracing: RuntimeTracing | None = None, @@ -1245,6 +1322,8 @@ def __init__( self._external_skill_importer = external_skill_importer self._statistics_service = statistics_service self._recall_token_estimator = recall_token_estimator + self.publications = publication_application + self.scopes = scope_application self._readiness = RuntimeReadinessChecks() if readiness is None else readiness self._clock = _utc_now if clock is None else clock self._tracing = tracing diff --git a/src/powercontext/builtin/runtime/composition.py b/src/powercontext/builtin/runtime/composition.py index 3867a28e9..014637371 100644 --- a/src/powercontext/builtin/runtime/composition.py +++ b/src/powercontext/builtin/runtime/composition.py @@ -38,9 +38,8 @@ MemoryReranker, ) from powercontext.builtin.artifacts.skill import AgentSkillProvider, ExternalSkillProvider, SkillGenerator -from powercontext.builtin.handoff_report.adapters import RuntimeHandoffReadAdapter, RuntimeWorkContinuityReadAdapter +from powercontext.builtin.handoff_report.adapters import RuntimeHandoffReadAdapter from powercontext.builtin.handoff_report.application import HandoffReportApplication -from powercontext.builtin.handoff_report.sqlite import HANDOFF_REPORT_TABLES from powercontext.builtin.inference import EmbeddingModel, TokenEstimator, character_token_estimator from powercontext.builtin.inference.usage import ( UsageReportingEmbeddingModel, @@ -279,16 +278,16 @@ async def open_builtin_runtime( external_skill_importer=contexts.import_external_skill if contexts.external_skill_registry else None, statistics_service=contexts.statistics, recall_token_estimator=contexts.estimate_recall_tokens, + publication_application=contexts.publications, + scope_application=contexts.scopes, readiness=RuntimeReadinessChecks(readiness_probes), tracing=tracing, ) ) if config.handoff_report.enabled: runtime.handoff_report = HandoffReportApplication( - contexts.database, + contexts.scopes, RuntimeHandoffReadAdapter(runtime.handoff), - continuity=RuntimeWorkContinuityReadAdapter(runtime.work), - scope_ids=contexts.handoff_scope_ids, ) if config.runtime.schedule_seconds is not None and configured_pipeline is None: raise BuiltinConfigurationError("scheduled-pipeline") @@ -322,7 +321,6 @@ async def open_builtin_contexts( """Open the selected database and expose scope-bound PowerContext providers.""" database = config.database - report_tables = HANDOFF_REPORT_TABLES if config.handoff_report.enabled else () configured_token_estimator = character_token_estimator() if token_estimator is None else token_estimator if isinstance(database, SQLiteConfig): experience_index = SQLiteExperienceFTSIndex() @@ -332,13 +330,13 @@ async def open_builtin_contexts( index = CompositeMemoryIndex(*indexes) async with SQLiteProfile.open( database, - tables=BUILTIN_TABLES + report_tables + index.tables, + tables=BUILTIN_TABLES + index.tables, load_vector_extension=embedding_model is not None, ) as profile: async with profile.database.transaction() as connection: await index.initialize(connection) await experience_index.initialize(connection) - yield RelationalContexts( + contexts = RelationalContexts( database=profile.database, index=index, experience_index=experience_index, @@ -353,13 +351,16 @@ async def open_builtin_contexts( memory_reranker=memory_reranker, memory_rerank_candidate_limit=config.runtime.memory_rerank_candidate_limit, ) + await contexts.scopes.register_existing() + await contexts.scopes.bootstrap_default() + yield contexts return experience_index = OceanBaseExperienceFTSIndex() indexes = [OceanBaseMemoryFTSIndex()] if embedding_model is not None: indexes.append(OceanBaseMemoryVectorIndex(embedding_model.profile)) index = CompositeMemoryIndex(*indexes) - tables = BUILTIN_TABLES + report_tables + index.tables + tables = BUILTIN_TABLES + index.tables if isinstance(database, OceanBaseConfig): profile_context = OceanBaseProfile.open(database, tables=tables) elif isinstance(database, SeekDBConfig): @@ -370,7 +371,7 @@ async def open_builtin_contexts( async with profile.database.transaction() as connection: await index.initialize(connection) await experience_index.initialize(connection) - yield RelationalContexts( + contexts = RelationalContexts( database=profile.database, index=index, experience_index=experience_index, @@ -385,6 +386,9 @@ async def open_builtin_contexts( memory_reranker=memory_reranker, memory_rerank_candidate_limit=config.runtime.memory_rerank_candidate_limit, ) + await contexts.scopes.register_existing() + await contexts.scopes.bootstrap_default() + yield contexts async def _generation_pipelines( diff --git a/src/powercontext/builtin/runtime/prepared_context.py b/src/powercontext/builtin/runtime/prepared_context.py index a1c3d8189..218dbc2cd 100644 --- a/src/powercontext/builtin/runtime/prepared_context.py +++ b/src/powercontext/builtin/runtime/prepared_context.py @@ -20,7 +20,7 @@ from collections.abc import Sequence from dataclasses import dataclass -from powercontext.artifacts import ArtifactRef +from powercontext.artifacts import ArtifactAddress, ArtifactRef from powercontext.builtin.artifacts.experience import Experience, ExperienceSearchHit, render_experience from powercontext.builtin.artifacts.memory.models import MemoryCitation, MemoryHit from powercontext.builtin.runtime.errors import PreparedContextInvariantError @@ -39,7 +39,7 @@ @dataclass(frozen=True) class _PreparedContextEntry: - origin: MemoryCitation | ArtifactRef + origin: PreparedContextOrigin kind: str citation: dict[str, object] content: str @@ -51,7 +51,36 @@ class PreparedContextBuild: """Final public context and the exact origins selected to produce it.""" context: PreparedContext - origins: tuple[MemoryCitation | ArtifactRef, ...] + origins: tuple[PreparedContextOrigin, ...] + + +@dataclass(frozen=True) +class MemoryEntryAddress: + """Identify one exact Memory entry version across Scope boundaries.""" + + memory: ArtifactAddress + entry_id: str + entry_version_id: str + + +PreparedContextOrigin = MemoryCitation | ArtifactRef | MemoryEntryAddress | ArtifactAddress + + +@dataclass(frozen=True) +class PreparedMemoryCandidates: + """Memory candidates read from one Scope.""" + + scope_id: str + memory_ref: ArtifactRef | None = None + hits: tuple[MemoryHit, ...] = () + + +@dataclass(frozen=True) +class PreparedExperienceCandidates: + """Experience candidates read from one Scope.""" + + scope_id: str + hits: tuple[ExperienceSearchHit, ...] = () class PreparedContextBuilder: @@ -90,15 +119,43 @@ def build_result( hits: Sequence[MemoryHit] = (), experience_hits: Sequence[ExperienceSearchHit] = (), ) -> PreparedContextBuild: - if len(hits) > self.memory_candidate_limit: + return self.build_scopes_result( + request=request, + current_scope_id=None, + memory_candidates=(PreparedMemoryCandidates(scope_id="", memory_ref=memory_ref, hits=tuple(hits)),), + experience_candidates=(PreparedExperienceCandidates(scope_id="", hits=tuple(experience_hits)),), + ) + + def build_scopes_result( + self, + *, + request: PrepareContextRequest, + current_scope_id: str | None, + memory_candidates: Sequence[PreparedMemoryCandidates] = (), + experience_candidates: Sequence[PreparedExperienceCandidates] = (), + ) -> PreparedContextBuild: + if sum(len(candidates.hits) for candidates in memory_candidates) > self.memory_candidate_limit: raise PreparedContextInvariantError("memory-candidate-limit") - if len(experience_hits) > self.experience_candidate_limit: + if sum(len(candidates.hits) for candidates in experience_candidates) > self.experience_candidate_limit: raise PreparedContextInvariantError("experience-candidate-limit") - if hits and memory_ref is None: - raise PreparedContextInvariantError("memory-ref-missing") - memory_entries = self._memory_entries(memory_ref, hits) - experience_entries = self._experience_entries(experience_hits) + memory_entries = tuple( + entry + for candidates in memory_candidates + for entry in self._memory_entries( + candidates.memory_ref, + candidates.hits, + scope_id=None if candidates.scope_id == current_scope_id else candidates.scope_id or None, + ) + ) + experience_entries = tuple( + entry + for candidates in experience_candidates + for entry in self._experience_entries( + candidates.hits, + scope_id=None if candidates.scope_id == current_scope_id else candidates.scope_id or None, + ) + ) entries = self._fit_entries(request, memory_entries, experience_entries) if not entries: @@ -116,7 +173,11 @@ def _memory_entries( self, memory_ref: ArtifactRef | None, hits: Sequence[MemoryHit], + *, + scope_id: str | None = None, ) -> tuple[_PreparedContextEntry, ...]: + if hits and memory_ref is None: + raise PreparedContextInvariantError("memory-ref-missing") memory_entries: list[_PreparedContextEntry] = [] seen: set[tuple[str, str]] = set() for hit in hits: @@ -136,11 +197,25 @@ def _memory_entries( entry_id=hit.entry_id, entry_version_id=hit.entry_version_id, ) + origin: PreparedContextOrigin = citation + rendered_citation = citation.model_dump(mode="json") + if scope_id is not None: + memory = ArtifactAddress(scope_id=scope_id, artifact=hit.memory_ref) + origin = MemoryEntryAddress( + memory=memory, + entry_id=hit.entry_id, + entry_version_id=hit.entry_version_id, + ) + rendered_citation = { + "memory": memory.model_dump(mode="json"), + "entry_id": hit.entry_id, + "entry_version_id": hit.entry_version_id, + } memory_entries.append( _PreparedContextEntry( - origin=citation, + origin=origin, kind="memory", - citation=citation.model_dump(mode="json"), + citation=rendered_citation, content=hit.text, truncated=False, ) @@ -150,6 +225,8 @@ def _memory_entries( def _experience_entries( self, hits: Sequence[ExperienceSearchHit], + *, + scope_id: str | None = None, ) -> tuple[_PreparedContextEntry, ...]: experience_entries: list[_PreparedContextEntry] = [] seen_experiences: set[tuple[str, int]] = set() @@ -162,11 +239,16 @@ def _experience_entries( seen_experiences.add(identity) if len(experience_entries) >= self.experience_entry_limit: break + origin: PreparedContextOrigin = hit.artifact_ref + rendered_citation: dict[str, object] = {"artifact_ref": hit.artifact_ref.model_dump(mode="json")} + if scope_id is not None: + origin = ArtifactAddress(scope_id=scope_id, artifact=hit.artifact_ref) + rendered_citation = {"artifact": origin.model_dump(mode="json")} experience_entries.append( _PreparedContextEntry( - origin=hit.artifact_ref, + origin=origin, kind="experience", - citation={"artifact_ref": hit.artifact_ref.model_dump(mode="json")}, + citation=rendered_citation, content=render_experience(hit.content), truncated=False, ) @@ -199,7 +281,7 @@ def _fit_entry( self, entries: Sequence[_PreparedContextEntry], *, - origin: MemoryCitation | ArtifactRef, + origin: PreparedContextOrigin, kind: str, citation: dict[str, object], text: str, diff --git a/src/powercontext/builtin/runtime/recall.py b/src/powercontext/builtin/runtime/recall.py index b5b2d195c..470bcc1e5 100644 --- a/src/powercontext/builtin/runtime/recall.py +++ b/src/powercontext/builtin/runtime/recall.py @@ -20,13 +20,17 @@ from sqlalchemy.ext.asyncio import AsyncConnection -from powercontext.artifacts import ArtifactRef +from powercontext.artifacts import ArtifactAddress, ArtifactRef from powercontext.builtin.artifacts.memory import MemoryCitation, MemoryService from powercontext.builtin.inference import TokenEstimator from powercontext.builtin.persistence.artifacts import ArtifactRepository from powercontext.builtin.persistence.database import AsyncDatabase from powercontext.builtin.persistence.sources import SourceRepository -from powercontext.builtin.runtime.prepared_context import PreparedContextBuild +from powercontext.builtin.runtime.prepared_context import ( + MemoryEntryAddress, + PreparedContextBuild, + PreparedContextOrigin, +) from powercontext.builtin.sources import ContentSource, ExternalSkillSnapshotSource from powercontext.builtin.statistics import RecallTokenMeasurement from powercontext.sources import Source, SourceRef @@ -39,6 +43,66 @@ def __init__(self, source: Source) -> None: super().__init__(f"no recall token projection is registered for {type(source).__name__}") +SourceAddress = tuple[str, str, str] + + +class _RecallOriginResolver: + def __init__( + self, + *, + connection: AsyncConnection, + current_scope_id: str, + artifacts: ArtifactRepository, + memory_service: Callable[[str, AsyncConnection], MemoryService], + ) -> None: + self._connection = connection + self._current_scope_id = current_scope_id + self._artifacts = artifacts + self._memory_service = memory_service + self._artifact_sources: dict[tuple[str, str, str, int], frozenset[SourceAddress]] = {} + self._resolving_artifacts: set[tuple[str, str, str, int]] = set() + + async def resolve(self, origin: PreparedContextOrigin, /) -> set[SourceAddress]: + if isinstance(origin, MemoryCitation): + return await self._memory(self._current_scope_id, origin) + if isinstance(origin, MemoryEntryAddress): + return await self._memory( + origin.memory.scope_id, + MemoryCitation( + memory_ref=origin.memory.artifact, + entry_id=origin.entry_id, + entry_version_id=origin.entry_version_id, + ), + ) + if isinstance(origin, ArtifactAddress): + return set(await self._artifact(origin.scope_id, origin.artifact)) + return set(await self._artifact(self._current_scope_id, origin)) + + async def _memory(self, scope_id: str, citation: MemoryCitation) -> set[SourceAddress]: + memory = self._memory_service(scope_id, self._connection) + entry = await memory.validate_citation(citation) + sources = _source_identities(scope_id, entry.sources) + for artifact_ref in entry.artifacts: + sources.update(await self._artifact(scope_id, artifact_ref)) + return sources + + async def _artifact(self, scope_id: str, artifact_ref: ArtifactRef) -> frozenset[SourceAddress]: + identity = _artifact_identity(scope_id, artifact_ref) + if identity in self._artifact_sources: + return self._artifact_sources[identity] + if identity in self._resolving_artifacts: + return frozenset() + self._resolving_artifacts.add(identity) + artifact = await self._artifacts.get(self._connection, scope_id, artifact_ref) + resolved = _source_identities(scope_id, artifact.lineage.sources) + for parent in artifact.lineage.artifacts: + resolved.update(await self._artifact(scope_id, parent)) + self._resolving_artifacts.remove(identity) + result = frozenset(resolved) + self._artifact_sources[identity] = result + return result + + class RelationalRecallTokenEstimator: """Resolve exact recall lineage and estimate its token reduction.""" @@ -49,7 +113,7 @@ def __init__( scope_id: str, sources: SourceRepository, artifacts: ArtifactRepository, - memory_service: Callable[[AsyncConnection], MemoryService], + memory_service: Callable[[str, AsyncConnection], MemoryService], estimator: TokenEstimator, ) -> None: self._database = database @@ -60,38 +124,18 @@ def __init__( self._estimator = estimator async def estimate(self, build: PreparedContextBuild, /) -> RecallTokenMeasurement: - source_refs: set[tuple[str, str]] = set() + source_refs: set[tuple[str, str, str]] = set() comparable = build.context.status == "ready" and bool(build.origins) async with self._database.transaction() as connection: - memory = self._memory_service(connection) - artifact_sources: dict[tuple[str, str, int], frozenset[tuple[str, str]]] = {} - resolving_artifacts: set[tuple[str, str, int]] = set() - - async def resolve_artifact(artifact_ref: ArtifactRef) -> frozenset[tuple[str, str]]: - identity = _artifact_identity(artifact_ref) - if identity in artifact_sources: - return artifact_sources[identity] - if identity in resolving_artifacts: - return frozenset() - resolving_artifacts.add(identity) - artifact = await self._artifacts.get(connection, self._scope_id, artifact_ref) - resolved = _source_identities(artifact.lineage.sources) - for parent in artifact.lineage.artifacts: - resolved.update(await resolve_artifact(parent)) - resolving_artifacts.remove(identity) - result = frozenset(resolved) - artifact_sources[identity] = result - return result - + resolver = _RecallOriginResolver( + connection=connection, + current_scope_id=self._scope_id, + artifacts=self._artifacts, + memory_service=self._memory_service, + ) for origin in build.origins: - if isinstance(origin, MemoryCitation): - entry = await memory.validate_citation(origin) - origin_sources = _source_identities(entry.sources) - for artifact_ref in entry.artifacts: - origin_sources.update(await resolve_artifact(artifact_ref)) - else: - origin_sources = set(await resolve_artifact(origin)) + origin_sources = await resolver.resolve(origin) comparable = comparable and bool(origin_sources) source_refs.update(origin_sources) @@ -105,10 +149,13 @@ async def resolve_artifact(artifact_ref: ArtifactRef) -> frozenset[tuple[str, st ) texts = [] - for source_type, source_id in sorted(source_refs, key=lambda ref: (ref[0].encode(), ref[1].encode())): + for scope_id, source_type, source_id in sorted( + source_refs, + key=lambda ref: (ref[0].encode(), ref[1].encode(), ref[2].encode()), + ): stored = await self._sources.get( connection, - self._scope_id, + scope_id, SourceRef(source_type=source_type, source_id=source_id), ) texts.append(_source_text(stored.value)) @@ -123,12 +170,12 @@ async def resolve_artifact(artifact_ref: ArtifactRef) -> frozenset[tuple[str, st ) -def _source_identities(sources: tuple[SourceRef, ...], /) -> set[tuple[str, str]]: - return {(source.source_type, source.source_id) for source in sources} +def _source_identities(scope_id: str, sources: tuple[SourceRef, ...], /) -> set[SourceAddress]: + return {(scope_id, source.source_type, source.source_id) for source in sources} -def _artifact_identity(artifact: ArtifactRef, /) -> tuple[str, str, int]: - return artifact.family, artifact.artifact_id, artifact.revision +def _artifact_identity(scope_id: str, artifact: ArtifactRef, /) -> tuple[str, str, str, int]: + return scope_id, artifact.family, artifact.artifact_id, artifact.revision def _source_text(source: Source, /) -> str: diff --git a/src/powercontext/builtin/runtime/relational.py b/src/powercontext/builtin/runtime/relational.py index 534a828f5..debdd0fa4 100644 --- a/src/powercontext/builtin/runtime/relational.py +++ b/src/powercontext/builtin/runtime/relational.py @@ -18,7 +18,7 @@ import asyncio from collections.abc import Callable -from dataclasses import dataclass +from dataclasses import dataclass, replace from typing import Any, cast from uuid import uuid4 @@ -77,6 +77,7 @@ from powercontext.builtin.persistence.sources import SourceRepository, StoredSource from powercontext.builtin.persistence.statistics import StatisticsRepository from powercontext.builtin.persistence.tables import ARTIFACT_HEADS_TABLE, SOURCE_JOURNAL_HEADS_TABLE +from powercontext.builtin.publication import ArtifactPublicationApplication from powercontext.builtin.review.generation import ( GeneratedCandidateResult, GenerationCapabilityUnavailableError, @@ -89,6 +90,7 @@ from powercontext.builtin.runtime.protocols import BuiltinTriggers from powercontext.builtin.runtime.recall import RelationalRecallTokenEstimator from powercontext.builtin.runtime.statistics import RelationalScopedStatistics +from powercontext.builtin.scope import ScopeApplication from powercontext.builtin.sources import ( CONTENT_SOURCE_ADAPTER, EXTERNAL_SKILL_SNAPSHOT_SOURCE_ADAPTER, @@ -228,6 +230,18 @@ def handoff( source_resolver: SourceCatalog, ) -> HandoffService: memory = self.memory(source_resolver) + + def evidence_resolver(scope_id: str) -> RelationalHandoffEvidenceResolver: + services = self if scope_id == self.scope_id else replace(self, scope_id=scope_id) + _, catalog = services.sources() + return RelationalHandoffEvidenceResolver( + database=services.database, + scope_id=scope_id, + sources=services.repositories.sources, + artifacts=services.repositories.artifacts, + memory=services.memory(catalog), + ) + return HandoffService( scope_id=self.scope_id, artifact_id=self.handoff_artifact_id, @@ -243,6 +257,7 @@ def handoff( artifacts=self.repositories.artifacts, memory=memory, ), + evidence_resolver_for_scope=evidence_resolver, generation_pipeline=self.handoff_pipeline, ) @@ -267,9 +282,10 @@ def recall_tokens(self) -> RelationalRecallTokenEstimator | None: if self.token_estimator is None: return None - def memory_service(connection: AsyncConnection) -> MemoryService: - _, source_catalog = self.sources(connection) - return self.memory(source_catalog, connection) + def memory_service(scope_id: str, connection: AsyncConnection) -> MemoryService: + services = self if scope_id == self.scope_id else replace(self, scope_id=scope_id) + _, source_catalog = services.sources(connection) + return services.memory(source_catalog, connection) return RelationalRecallTokenEstimator( database=self.database, @@ -305,6 +321,7 @@ def __init__( memory_artifact_id: str = "memory", ) -> None: self.database = database + self.scopes = ScopeApplication(database) self.index = NoMemoryIndex() if index is None else index self.experience_index = NoExperienceIndex() if experience_index is None else experience_index self.repositories = _Repositories( @@ -318,6 +335,11 @@ def __init__( external_skills=ExternalSkillRepository(), statistics=StatisticsRepository(), ) + self.publications = ArtifactPublicationApplication( + database, + self.repositories.artifacts, + self.scopes, + ) self._candidate_pipeline = candidate_pipeline self.memory_extraction = candidate_pipeline is not None self._experience_pipeline = experience_pipeline diff --git a/src/powercontext/builtin/runtime/statistics.py b/src/powercontext/builtin/runtime/statistics.py index 0fe8d5dbf..96d6e9159 100644 --- a/src/powercontext/builtin/runtime/statistics.py +++ b/src/powercontext/builtin/runtime/statistics.py @@ -31,6 +31,7 @@ StoredModelUsage, StoredRecallTokenUsage, ) +from powercontext.builtin.scope import ScopeSelection from powercontext.builtin.statistics import ( ArtifactInventoryStatistics, CandidateFamilyCount, @@ -51,6 +52,7 @@ RecallTokenStatistics, RecallTokenValue, ResolvedUsagePeriod, + ScopeStatistics, SourceInventoryStatistics, Statistics, StatisticsPeriod, @@ -123,24 +125,36 @@ async def overview(self, period: StatisticsPeriod, as_of: datetime, /) -> Statis processed = 0 if cursor is None else cursor.cursor.sequence artifacts = tuple(FamilyCount(family=family, total=total) for family, total in stored_inventory.artifacts) candidates = _candidate_inventory(stored_inventory.candidates) + inventory = InventoryStatistics( + sources=SourceInventoryStatistics( + total=stored_inventory.sources, + memory_processed=processed, + memory_pending=max(stored_inventory.sources - processed, 0), + ), + artifacts=ArtifactInventoryStatistics( + total=sum(item.total for item in artifacts), + by_family=artifacts, + ), + candidates=candidates, + memory=MemoryInventoryStatistics(entries=_memory_inventory(memory_entries)), + ) + usage = _usage_statistics(resolved_period, usage_rows) + recall = _recall_statistics(resolved_period, self._token_estimator, recall_rows) return Statistics( - scope_id=self._scope_id, + selection=ScopeSelection(mode="exact", scope_ids=(self._scope_id,)), + scope_ids=(self._scope_id,), as_of=captured_at, - inventory=InventoryStatistics( - sources=SourceInventoryStatistics( - total=stored_inventory.sources, - memory_processed=processed, - memory_pending=max(stored_inventory.sources - processed, 0), - ), - artifacts=ArtifactInventoryStatistics( - total=sum(item.total for item in artifacts), - by_family=artifacts, + inventory=inventory, + usage=usage, + recall=recall, + by_scope=( + ScopeStatistics( + scope_id=self._scope_id, + inventory=inventory, + usage=usage, + recall=recall, ), - candidates=candidates, - memory=MemoryInventoryStatistics(entries=_memory_inventory(memory_entries)), ), - usage=_usage_statistics(resolved_period, usage_rows), - recall=_recall_statistics(resolved_period, self._token_estimator, recall_rows), ) async def record( diff --git a/src/powercontext/builtin/scope/application.py b/src/powercontext/builtin/scope/application.py index 6c68451bd..bfdd658fc 100644 --- a/src/powercontext/builtin/scope/application.py +++ b/src/powercontext/builtin/scope/application.py @@ -22,6 +22,9 @@ from collections import deque from collections.abc import Callable, Sequence +from sqlalchemy.exc import IntegrityError +from sqlalchemy.ext.asyncio import AsyncConnection + from powercontext.builtin.persistence.database import AsyncDatabase from powercontext.builtin.scope.errors import ( ScopeBindingNotFoundError, @@ -91,20 +94,39 @@ async def create(self, draft: ScopeDraft, /) -> ScopeDescriptor: async def _create(self, draft: ScopeDraft) -> ScopeDescriptor: digest = _draft_digest(draft) - async with self._database.transaction() as connection: - existing = await self._repository.creation(connection, draft.idempotency_key) - if existing is not None: - existing_digest, scope_id = existing - if existing_digest != digest: - raise ScopeIdempotencyConflictError(draft.idempotency_key) - return await self._required(connection, scope_id) - await self._validate_relationships( - connection, - scope_id=None, - parent_scope_id=draft.parent_scope_id, - context_references=draft.context_references, - ) - return await self._repository.add(connection, self._id_factory(), draft, digest) + try: + async with self._database.transaction() as connection: + existing = await self._repository.creation(connection, draft.idempotency_key) + if existing is not None: + return await self._resolve_creation(connection, draft.idempotency_key, digest, existing) + await self._validate_relationships( + connection, + scope_id=None, + parent_scope_id=draft.parent_scope_id, + context_references=draft.context_references, + ) + return await self._repository.add(connection, self._id_factory(), draft, digest) + except IntegrityError: + # The transaction must roll back before reading the request that won + # the unique-key race. An unrelated integrity failure remains visible. + async with self._database.transaction() as connection: + existing = await self._repository.creation(connection, draft.idempotency_key) + if existing is None: + raise + return await self._resolve_creation(connection, draft.idempotency_key, digest, existing) + + async def _resolve_creation( + self, + connection: AsyncConnection, + idempotency_key: str, + request_digest: str, + creation: tuple[str, str], + /, + ) -> ScopeDescriptor: + existing_digest, scope_id = creation + if existing_digest != request_digest: + raise ScopeIdempotencyConflictError(idempotency_key) + return await self._required(connection, scope_id) async def get(self, scope_id: str, /) -> ScopeDescriptor: async with self._database.transaction() as connection: @@ -192,7 +214,7 @@ async def resolve_selection(self, selection: ScopeSelection, /) -> tuple[ScopeDe scopes = await self._repository.list(connection) return _subtree(scopes, root_scope_id) - async def _required(self, connection, scope_id: str) -> ScopeDescriptor: + async def _required(self, connection: AsyncConnection, scope_id: str) -> ScopeDescriptor: scope = await self._repository.get(connection, scope_id) if scope is None: raise ScopeNotFoundError(scope_id) @@ -200,7 +222,7 @@ async def _required(self, connection, scope_id: str) -> ScopeDescriptor: async def _validate_relationships( self, - connection, + connection: AsyncConnection, *, scope_id: str | None, parent_scope_id: str | None, diff --git a/src/powercontext/builtin/scope/repository.py b/src/powercontext/builtin/scope/repository.py index 765610ed4..360b7fcbb 100644 --- a/src/powercontext/builtin/scope/repository.py +++ b/src/powercontext/builtin/scope/repository.py @@ -20,6 +20,7 @@ from hashlib import sha256 from sqlalchemy import delete, insert, select, union, update +from sqlalchemy.exc import IntegrityError from sqlalchemy.ext.asyncio import AsyncConnection from powercontext.builtin.persistence.tables import ( @@ -243,13 +244,22 @@ async def default_scope_id(self, connection: AsyncConnection, /) -> str | None: return None if value is None else str(value) async def set_default(self, connection: AsyncConnection, scope_id: str, /) -> None: - result = await connection.execute( + statement = ( update(SCOPE_SETTINGS_TABLE) .where(SCOPE_SETTINGS_TABLE.c.name == _DEFAULT_SETTING) .values(scope_id=scope_id) ) + result = await connection.execute(statement) if result.rowcount == 0: - await connection.execute(insert(SCOPE_SETTINGS_TABLE).values(name=_DEFAULT_SETTING, scope_id=scope_id)) + try: + async with connection.begin_nested(): + await connection.execute( + insert(SCOPE_SETTINGS_TABLE).values(name=_DEFAULT_SETTING, scope_id=scope_id) + ) + except IntegrityError: + await connection.execute(statement) + if await self.default_scope_id(connection) != scope_id: + raise async def binding(self, connection: AsyncConnection, key: ScopeBindingKey, /) -> ScopeBinding | None: value = ( @@ -270,7 +280,7 @@ async def set_binding( scope_id: str, /, ) -> ScopeBinding: - result = await connection.execute( + statement = ( update(SCOPE_BINDINGS_TABLE) .where( SCOPE_BINDINGS_TABLE.c.integration == key.integration, @@ -279,15 +289,22 @@ async def set_binding( ) .values(scope_id=scope_id) ) + result = await connection.execute(statement) if result.rowcount == 0: - await connection.execute( - insert(SCOPE_BINDINGS_TABLE).values( - integration=key.integration, - kind=key.kind, - external_id=key.external_id, - scope_id=scope_id, - ) - ) + try: + async with connection.begin_nested(): + await connection.execute( + insert(SCOPE_BINDINGS_TABLE).values( + integration=key.integration, + kind=key.kind, + external_id=key.external_id, + scope_id=scope_id, + ) + ) + except IntegrityError: + await connection.execute(statement) + if await self.binding(connection, key) != ScopeBinding(key=key, scope_id=scope_id): + raise return ScopeBinding(key=key, scope_id=scope_id) async def clear_binding(self, connection: AsyncConnection, key: ScopeBindingKey, /) -> bool: diff --git a/src/powercontext/builtin/statistics/__init__.py b/src/powercontext/builtin/statistics/__init__.py index f5663f380..351882285 100644 --- a/src/powercontext/builtin/statistics/__init__.py +++ b/src/powercontext/builtin/statistics/__init__.py @@ -34,6 +34,7 @@ RecallTokenStatistics, RecallTokenValue, ResolvedUsagePeriod, + ScopeStatistics, SourceInventoryStatistics, Statistics, StatisticsPeriod, @@ -60,6 +61,7 @@ "RecallTokenStatistics", "RecallTokenValue", "ResolvedUsagePeriod", + "ScopeStatistics", "SourceInventoryStatistics", "Statistics", "StatisticsPeriod", diff --git a/src/powercontext/builtin/statistics/aggregation.py b/src/powercontext/builtin/statistics/aggregation.py new file mode 100644 index 000000000..c32cd5fd8 --- /dev/null +++ b/src/powercontext/builtin/statistics/aggregation.py @@ -0,0 +1,260 @@ +# Copyright (c) 2026 OceanBase. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +"""Additive Statistics projection over a frozen Scope selection.""" + +from __future__ import annotations + +from collections import defaultdict +from collections.abc import Callable, Iterable +from datetime import datetime + +from powercontext.builtin.scope.models import ScopeSelection +from powercontext.builtin.statistics.models import ( + ArtifactInventoryStatistics, + CandidateFamilyCount, + CandidateInventoryStatistics, + FamilyCount, + InventoryStatistics, + MemoryEntryInventoryStatistics, + MemoryInventoryStatistics, + MemoryKindCount, + ModelUsageDay, + ModelUsagePurpose, + ModelUsagePurposeBreakdown, + ModelUsageStatistics, + ModelUsageValue, + RecallTokenDay, + RecallTokenStatistics, + RecallTokenValue, + ScopeStatistics, + SourceInventoryStatistics, + Statistics, + UsageStatistics, +) + + +def aggregate_statistics( + selection: ScopeSelection, + scope_ids: tuple[str, ...], + snapshots: tuple[Statistics, ...], + as_of: datetime, +) -> Statistics: + """Aggregate values that are already bounded to the same reporting period.""" + + if len(scope_ids) != len(snapshots): + raise ValueError("every selected Scope must have one Statistics snapshot") # noqa: TRY003 + if not snapshots: + raise ValueError("Statistics selection must resolve at least one Scope") # noqa: TRY003 + period = snapshots[0].usage.period + if any(snapshot.usage.period != period or snapshot.recall.period != period for snapshot in snapshots): + raise ValueError("Statistics snapshots must use the same period") # noqa: TRY003 + + return Statistics( + selection=selection, + scope_ids=scope_ids, + as_of=as_of, + inventory=_inventory(snapshots), + usage=_usage(snapshots), + recall=_recall(snapshots), + by_scope=tuple( + ScopeStatistics( + scope_id=scope_id, + inventory=snapshot.inventory, + usage=snapshot.usage, + recall=snapshot.recall, + ) + for scope_id, snapshot in zip(scope_ids, snapshots, strict=True) + ), + ) + + +def _inventory(snapshots: tuple[Statistics, ...]) -> InventoryStatistics: + family_counts: dict[str, int] = defaultdict(int) + candidate_counts: dict[str, list[int]] = defaultdict(lambda: [0, 0, 0]) + kind_counts: dict[str, list[int]] = defaultdict(lambda: [0, 0]) + for snapshot in snapshots: + for item in snapshot.inventory.artifacts.by_family: + family_counts[item.family] += item.total + for item in snapshot.inventory.candidates.by_family: + values = candidate_counts[item.family] + values[0] += item.pending + values[1] += item.approved + values[2] += item.rejected + for item in snapshot.inventory.memory.entries.by_kind: + values = kind_counts[item.kind] + values[0] += item.active + values[1] += item.inactive + candidates = tuple( + CandidateFamilyCount( + family=family, + total=sum(values), + pending=values[0], + approved=values[1], + rejected=values[2], + ) + for family, values in sorted(candidate_counts.items()) + ) + kinds = tuple( + MemoryKindCount(kind=kind, total=sum(values), active=values[0], inactive=values[1]) + for kind, values in sorted(kind_counts.items()) + ) + return InventoryStatistics( + sources=SourceInventoryStatistics( + total=sum(snapshot.inventory.sources.total for snapshot in snapshots), + memory_processed=sum(snapshot.inventory.sources.memory_processed for snapshot in snapshots), + memory_pending=sum(snapshot.inventory.sources.memory_pending for snapshot in snapshots), + ), + artifacts=ArtifactInventoryStatistics( + total=sum(family_counts.values()), + by_family=tuple(FamilyCount(family=family, total=total) for family, total in sorted(family_counts.items())), + ), + candidates=CandidateInventoryStatistics( + total=sum(item.total for item in candidates), + pending=sum(item.pending for item in candidates), + approved=sum(item.approved for item in candidates), + rejected=sum(item.rejected for item in candidates), + by_family=candidates, + ), + memory=MemoryInventoryStatistics( + entries=MemoryEntryInventoryStatistics( + total=sum(item.total for item in kinds), + active=sum(item.active for item in kinds), + inactive=sum(item.inactive for item in kinds), + by_kind=kinds, + ) + ), + ) + + +def _usage(snapshots: tuple[Statistics, ...]) -> UsageStatistics: + period = snapshots[0].usage.period + purposes = tuple( + purpose + for purpose in ModelUsagePurpose + if any(any(item.purpose is purpose for item in snapshot.usage.by_purpose) for snapshot in snapshots) + ) + return UsageStatistics( + period=period, + totals=_model_usage(snapshot.usage.totals for snapshot in snapshots), + by_purpose=tuple( + ModelUsagePurposeBreakdown( + purpose=purpose, + generation=_usage_value( + _purpose(snapshot.usage.by_purpose, purpose).generation for snapshot in snapshots + ), + embedding=_usage_value( + _purpose(snapshot.usage.by_purpose, purpose).embedding for snapshot in snapshots + ), + ) + for purpose in purposes + ), + daily=tuple( + ModelUsageDay( + date=day.date, + generation=_usage_value(snapshot.usage.daily[index].generation for snapshot in snapshots), + embedding=_usage_value(snapshot.usage.daily[index].embedding for snapshot in snapshots), + by_purpose=tuple( + ModelUsagePurposeBreakdown( + purpose=purpose, + generation=_usage_value( + _purpose(snapshot.usage.daily[index].by_purpose, purpose).generation + for snapshot in snapshots + ), + embedding=_usage_value( + _purpose(snapshot.usage.daily[index].by_purpose, purpose).embedding + for snapshot in snapshots + ), + ) + for purpose in ModelUsagePurpose + if any( + any(item.purpose is purpose for item in snapshot.usage.daily[index].by_purpose) + for snapshot in snapshots + ) + ), + ) + for index, day in enumerate(snapshots[0].usage.daily) + ), + ) + + +def _recall(snapshots: tuple[Statistics, ...]) -> RecallTokenStatistics: + first = snapshots[0].recall + if any(snapshot.recall.estimator != first.estimator for snapshot in snapshots): + raise ValueError("Statistics snapshots must use the same recall estimator") # noqa: TRY003 + return RecallTokenStatistics( + period=first.period, + estimator=first.estimator, + totals=_recall_value(snapshot.recall.totals for snapshot in snapshots), + daily=tuple( + RecallTokenDay( + date=day.date, + **_recall_value(snapshot.recall.daily[index] for snapshot in snapshots).model_dump(), + ) + for index, day in enumerate(first.daily) + ), + ) + + +def _model_usage(values: Iterable[ModelUsageStatistics]) -> ModelUsageStatistics: + items = tuple(values) + return ModelUsageStatistics( + generation=_usage_value(item.generation for item in items), + embedding=_usage_value(item.embedding for item in items), + ) + + +def _usage_value(values: Iterable[ModelUsageValue]) -> ModelUsageValue: + items = tuple(values) + return ModelUsageValue( + requests=sum(item.requests for item in items), + input_tokens=_optional_sum(items, lambda item: item.input_tokens), + output_tokens=_optional_sum(items, lambda item: item.output_tokens), + ) + + +def _optional_sum(values: tuple[ModelUsageValue, ...], getter: Callable[[ModelUsageValue], int | None]) -> int | None: + selected = tuple(getter(value) for value in values) + return None if any(value is None for value in selected) else sum(value for value in selected if value is not None) + + +def _purpose( + values: tuple[ModelUsagePurposeBreakdown, ...], + purpose: ModelUsagePurpose, +) -> ModelUsagePurposeBreakdown: + return next( + (value for value in values if value.purpose is purpose), + ModelUsagePurposeBreakdown( + purpose=purpose, + generation=ModelUsageValue(requests=0, input_tokens=0, output_tokens=0), + embedding=ModelUsageValue(requests=0, input_tokens=0, output_tokens=0), + ), + ) + + +def _recall_value(values: Iterable[RecallTokenValue]) -> RecallTokenValue: + items = tuple(values) + baseline = sum(item.baseline_tokens for item in items) + recalled = sum(item.recalled_tokens for item in items) + return RecallTokenValue( + preparations=sum(item.preparations for item in items), + ready_preparations=sum(item.ready_preparations for item in items), + comparable_preparations=sum(item.comparable_preparations for item in items), + baseline_tokens=baseline, + recalled_tokens=recalled, + token_reduction=baseline - recalled, + ) + + +__all__ = ["aggregate_statistics"] diff --git a/src/powercontext/builtin/statistics/models.py b/src/powercontext/builtin/statistics/models.py index 428c457a0..eb8e7276d 100644 --- a/src/powercontext/builtin/statistics/models.py +++ b/src/powercontext/builtin/statistics/models.py @@ -23,6 +23,7 @@ from pydantic import BaseModel, Field, model_validator from powercontext.builtin.inference import TokenEstimatorProfile +from powercontext.builtin.scope.models import ScopeSelection class StatisticsPeriod(StrEnum): @@ -228,14 +229,31 @@ class RecallTokenStatistics(BaseModel): daily: tuple[RecallTokenDay, ...] -class Statistics(BaseModel): - """Current inventory and bounded model usage for one scope.""" +class ScopeStatistics(BaseModel): + """Statistics retained for one Scope inside a resolved selection.""" scope_id: str + inventory: InventoryStatistics + usage: UsageStatistics + recall: RecallTokenStatistics + + +class Statistics(BaseModel): + """Current inventory and bounded model usage for one frozen Scope selection.""" + + selection: ScopeSelection + scope_ids: tuple[str, ...] as_of: datetime inventory: InventoryStatistics usage: UsageStatistics recall: RecallTokenStatistics + by_scope: tuple[ScopeStatistics, ...] + + @model_validator(mode="after") + def validate_scope_details(self) -> Statistics: + if tuple(item.scope_id for item in self.by_scope) != self.scope_ids: + raise ValueError("by_scope must contain one ordered entry for every resolved Scope") # noqa: TRY003 + return self __all__ = [ @@ -258,6 +276,7 @@ class Statistics(BaseModel): "RecallTokenStatistics", "RecallTokenValue", "ResolvedUsagePeriod", + "ScopeStatistics", "SourceInventoryStatistics", "Statistics", "StatisticsPeriod", diff --git a/src/powercontext/cli/config.py b/src/powercontext/cli/config.py index 166b84edb..752baa7a2 100644 --- a/src/powercontext/cli/config.py +++ b/src/powercontext/cli/config.py @@ -17,7 +17,6 @@ from __future__ import annotations import asyncio -import json import os import re import shlex @@ -70,8 +69,6 @@ class GeneratedConfiguration: """Canonical state rendered into one managed environment block.""" config_version: int - scope_id: str - display_name: str generation: ModelSelection embedding: ModelSelection embedding_profile_id: str @@ -193,7 +190,7 @@ class ApiProtocol: "POWERCONTEXT_OPENCODE_CAPTURE_PROMPTS": "true", "POWERCONTEXT_PI_CAPTURE_PROMPTS": "true", } -_SCOPE_NAMES = ( +_EXPLICIT_SCOPE_NAMES = ( "POWERCONTEXT_CODEX_SCOPE_ID", "POWERCONTEXT_CLAUDE_SCOPE_ID", "POWERCONTEXT_DSH_SCOPE_ID", @@ -208,11 +205,10 @@ class ApiProtocol: } _ALL_FIXED_MANAGED_NAMES = ( set(_BASE_ENVIRONMENT) - | set(_SCOPE_NAMES) + | set(_EXPLICIT_SCOPE_NAMES) | _KNOWN_PROVIDER_NAMES | _OPTIONAL_MANAGED_NAMES | { - "POWERCONTEXT_SERVER_DASHBOARD_SCOPES", "POWERCONTEXT_SERVER_DATABASE_KIND", "POWERCONTEXT_SERVER_RUNTIME_SCHEDULE_SECONDS", "POWERCONTEXT_SERVER_INFERENCE_GENERATION_MODEL", @@ -313,7 +309,7 @@ def _print_summary(configuration: GeneratedConfiguration) -> None: "provider default", ) typer.secho("\nConfiguration", bold=True, fg=typer.colors.CYAN) - typer.echo(f" Scope {configuration.scope_id}") + typer.echo(" Scope Server default; integrations may bind a Session or workspace") typer.echo(f" Generation {configuration.generation.model.partition(':')[2]} ({generation_url})") typer.echo(f" Embedding {configuration.embedding.model.partition(':')[2]} ({embedding_url})") typer.echo(f" Database {configuration.database_kind}") @@ -327,8 +323,6 @@ def collect_configuration( typer.secho("\nPowerContext configuration", bold=True, fg=typer.colors.CYAN) typer.echo("Press Enter to accept a default. Provider details are derived from the API protocol.\n") - scope_id = typer.prompt("Scope ID", default="project:quickstart").strip() - display_name = typer.prompt("Dashboard display name", default="Quick Start").strip() generation, generation_credentials = _collect_connection("generation") generation_protocol = _PROTOCOL_BY_ID.get(generation.protocol_id or "") can_reuse = generation_protocol is not None and generation_protocol.embedding_adapter is not None @@ -355,8 +349,6 @@ def collect_configuration( schedule = 60 return GeneratedConfiguration( config_version=CONFIG_VERSION, - scope_id=scope_id, - display_name=display_name, generation=generation, embedding=embedding, embedding_profile_id=profile, @@ -374,11 +366,6 @@ def render_environment(configuration: GeneratedConfiguration) -> dict[str, str]: values = dict(_BASE_ENVIRONMENT) values.update({ - "POWERCONTEXT_SERVER_DASHBOARD_SCOPES": json.dumps( - [{"scope_id": configuration.scope_id, "display_name": configuration.display_name}], - separators=(",", ":"), - ensure_ascii=False, - ), "POWERCONTEXT_SERVER_DATABASE_KIND": configuration.database_kind, "POWERCONTEXT_SERVER_RUNTIME_SCHEDULE_SECONDS": str(configuration.schedule_seconds), "POWERCONTEXT_SERVER_INFERENCE_GENERATION_MODEL": configuration.generation.model, @@ -386,7 +373,6 @@ def render_environment(configuration: GeneratedConfiguration) -> dict[str, str]: "POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_PROFILE_ID": configuration.embedding_profile_id, "POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_DIMENSION": str(configuration.embedding_dimension), }) - values.update(dict.fromkeys(_SCOPE_NAMES, configuration.scope_id)) if configuration.database_url is not None: values["POWERCONTEXT_SERVER_DATABASE_URL"] = configuration.database_url if configuration.database_path is not None: @@ -446,11 +432,8 @@ def configuration_from_document(content: str) -> GeneratedConfiguration: metadata = _managed_metadata(content) generation_model = _required(values, "POWERCONTEXT_SERVER_INFERENCE_GENERATION_MODEL") embedding_model = _required(values, "POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_MODEL") - scope_id, display_name = _scope(values) return GeneratedConfiguration( config_version=_parse_integer(str(metadata.get("config-version", CONFIG_VERSION)), "config-version"), - scope_id=scope_id, - display_name=display_name, generation=ModelSelection( generation_model, _provider_variables("generation", generation_model, metadata, values) ), @@ -472,16 +455,10 @@ def configuration_from_document(content: str) -> GeneratedConfiguration: def validate_configuration(configuration: GeneratedConfiguration) -> None: - """Validate model, environment, database, Scope, and runtime contracts.""" + """Validate model, environment, database, and runtime contracts.""" if configuration.config_version != CONFIG_VERSION: raise ConfigError(f"unsupported config version: {configuration.config_version}") # noqa: TRY003 - if not configuration.scope_id.strip() or not configuration.display_name.strip(): - raise ConfigError("Scope ID and Dashboard display name are required") # noqa: TRY003 - if len(configuration.scope_id) > 255: - raise ConfigError("Scope ID must contain at most 255 characters") # noqa: TRY003 - if len(configuration.display_name) > 80: - raise ConfigError("Dashboard display name must contain at most 80 characters") # noqa: TRY003 if configuration.embedding_dimension < 1 or configuration.schedule_seconds < 1: raise ConfigError("Embedding dimension and Source interval must be positive") # noqa: TRY003 _validate_model_selection("Generation", configuration.generation) @@ -837,17 +814,6 @@ def _environment_names(selection: ModelSelection) -> str: return ",".join(variable.name for variable in selection.environment) -def _scope(values: Mapping[str, str]) -> tuple[str, str]: - raw = _required(values, "POWERCONTEXT_SERVER_DASHBOARD_SCOPES") - try: - first = json.loads(raw)[0] - return str(first["scope_id"]), str(first["display_name"]) - except (IndexError, KeyError, TypeError, json.JSONDecodeError) as error: - raise ConfigError( # noqa: TRY003 - "Dashboard scopes must contain one scope_id and display_name" - ) from error - - def _required(values: Mapping[str, str], name: str) -> str: value = values.get(name) if value is None or not value.strip(): diff --git a/src/powercontext/cli/hosts.py b/src/powercontext/cli/hosts.py index 6e7cc0d4c..bace9c09f 100644 --- a/src/powercontext/cli/hosts.py +++ b/src/powercontext/cli/hosts.py @@ -186,7 +186,6 @@ def run_setup_select( source: str, ref: str, server_url: str | None, - scope_mode: str, capture_prompts: bool, json_output: bool, ) -> None: @@ -204,7 +203,6 @@ def run_setup_select( source=source, ref=ref, server_url=server_url, - scope_mode=scope_mode, capture_prompts=capture_prompts, ) write_setup_select_report(report, json_output=json_output) @@ -231,7 +229,6 @@ def setup_selected_hosts( source: str, ref: str, server_url: str | None, - scope_mode: str, capture_prompts: bool, ) -> SetupSelectReport: """Install selected hosts and isolate failures from sibling hosts.""" @@ -250,7 +247,6 @@ def setup_selected_hosts( source=source, ref=ref, server_url=server_url, - scope_mode=scope_mode, capture_prompts=capture_prompts, ) verify_host(host.name) @@ -267,7 +263,6 @@ def install_host( source: str, ref: str, server_url: str | None, - scope_mode: str, capture_prompts: bool, ) -> object: """Call the existing installer for one first-class host.""" @@ -297,7 +292,6 @@ def install_host( source=source, ref=ref, server_url=server_url if server_url is not None else DEFAULT_OPENCLAW_SERVER_URL, - scope_mode=scope_mode, ) if name == "opencode": from powercontext.cli.opencode import install_opencode_plugin diff --git a/src/powercontext/cli/openclaw.py b/src/powercontext/cli/openclaw.py index 7ba2943d6..c148344d8 100644 --- a/src/powercontext/cli/openclaw.py +++ b/src/powercontext/cli/openclaw.py @@ -48,16 +48,12 @@ def install_openclaw_plugin( source: str, ref: str, server_url: str, - scope_mode: str, ) -> OpenClawSetupResult: """Build, install, and configure the OpenClaw plugin from one source/ref.""" executable = openclaw_executable() require_supported_openclaw(executable) normalized_url = normalize_server_url(server_url) - if scope_mode not in {"agent", "project"}: - raise SetupError.invalid_openclaw_scope() - data_dir = powercontext_data_dir() try: data_dir.mkdir(parents=True, exist_ok=True) @@ -70,13 +66,11 @@ def install_openclaw_plugin( configure_openclaw( executable=executable, server_url=normalized_url, - scope_mode=scope_mode, ) return OpenClawSetupResult( plugin=OPENCLAW_PLUGIN_NAME, plugin_path=str(plugin_dir), server_url=normalized_url, - scope_mode=scope_mode, data_dir=str(data_dir), ) @@ -233,7 +227,7 @@ def normalize_server_url(value: str) -> str: return urlunsplit((parsed.scheme, parsed.netloc, parsed.path.rstrip("/"), "", "")) -def configure_openclaw(*, executable: str, server_url: str, scope_mode: str) -> None: +def configure_openclaw(*, executable: str, server_url: str) -> None: """Write plugin, memory-slot, and coding-tool allowlist configuration.""" settings = [ @@ -241,7 +235,6 @@ def configure_openclaw(*, executable: str, server_url: str, scope_mode: str) -> {"path": "plugins.entries.memory-powercontext.config.endpoint", "value": server_url}, {"path": "plugins.entries.memory-powercontext.config.autoRecall", "value": True}, {"path": "plugins.entries.memory-powercontext.config.autoCapture", "value": True}, - {"path": "plugins.entries.memory-powercontext.config.scopeMode", "value": scope_mode}, {"path": "plugins.entries.memory-powercontext.hooks.allowConversationAccess", "value": True}, {"path": "plugins.slots.memory", "value": OPENCLAW_PLUGIN_NAME}, ] diff --git a/src/powercontext/cli/system.py b/src/powercontext/cli/system.py index 7ad47ab0e..80e9d0525 100644 --- a/src/powercontext/cli/system.py +++ b/src/powercontext/cli/system.py @@ -43,7 +43,6 @@ DEFAULT_MARKETPLACE_REF = "master" DEFAULT_CLAUDE_CODE_SERVER_URL = "http://127.0.0.1:8000" DEFAULT_OPENCLAW_SERVER_URL = "http://127.0.0.1:8000" -DEFAULT_OPENCLAW_SCOPE_MODE = "agent" PLUGIN_NAME = "powercontext" CLAUDE_MARKETPLACE_NAME = "powercontext" _GITHUB_REPOSITORY = re.compile(r"^[^/\s]+/[^/\s]+$") @@ -105,10 +104,6 @@ def invalid_openclaw_source(cls, source: str) -> SetupError: def unsupported_openclaw_version(cls, version_text: str) -> SetupError: return cls(f"OpenClaw {version_text or 'version unknown'} is unsupported; upgrade to >= 2026.8.1-beta.2") - @classmethod - def invalid_openclaw_scope(cls) -> SetupError: - return cls("OpenClaw scope must be agent or project") - @classmethod def openclaw_server_url_scheme(cls) -> SetupError: return cls("OpenClaw PowerContext Server URL must use HTTP or HTTPS") @@ -347,7 +342,6 @@ class OpenClawSetupResult: plugin: str plugin_path: str server_url: str - scope_mode: str data_dir: str @@ -522,10 +516,6 @@ def setup_openclaw( str, typer.Option(help="PowerContext Server base URL configured for the plugin."), ] = DEFAULT_OPENCLAW_SERVER_URL, - scope_mode: Annotated[ - str, - typer.Option("--scope-mode", help="Memory scope mode: agent or project."), - ] = DEFAULT_OPENCLAW_SCOPE_MODE, json_output: Annotated[ bool, typer.Option("--json", help="Write the result as JSON."), @@ -540,7 +530,6 @@ def setup_openclaw( source=source, ref=ref, server_url=server_url, - scope_mode=scope_mode, ) except SetupError as error: typer.echo(str(error), err=True) @@ -553,7 +542,6 @@ def setup_openclaw( typer.echo(f"Plugin: {result.plugin}") typer.echo(f"Plugin path: {result.plugin_path}") typer.echo(f"Server: {result.server_url}") - typer.echo(f"Scope: {result.scope_mode}") typer.echo(f"Data directory: {result.data_dir}") typer.echo("Next: start a new OpenClaw session.") @@ -696,10 +684,6 @@ def setup_select( str | None, typer.Option(help="PowerContext Server base URL override for Claude Code and OpenClaw."), ] = None, - scope_mode: Annotated[ - str, - typer.Option("--scope-mode", help="OpenClaw memory scope mode: agent or project."), - ] = DEFAULT_OPENCLAW_SCOPE_MODE, capture_prompts: Annotated[ bool, typer.Option(help="Capture Claude Code user prompts as ordinary Source evidence."), @@ -718,7 +702,6 @@ def setup_select( source=source, ref=ref, server_url=server_url, - scope_mode=scope_mode, capture_prompts=capture_prompts, json_output=json_output, ) diff --git a/src/powercontext/cli/workbuddy.py b/src/powercontext/cli/workbuddy.py index c2d0b296c..d4d0b6187 100644 --- a/src/powercontext/cli/workbuddy.py +++ b/src/powercontext/cli/workbuddy.py @@ -52,15 +52,15 @@ WORKBUDDY_SKILL_NAME = "project-context" WORKBUDDY_SKILL_MANIFEST = ".powercontext.json" WORKBUDDY_PYTHON_PLACEHOLDER = "${POWERCONTEXT_PYTHON}" -WORKBUDDY_PROJECT_SCOPE_PLACEHOLDER = "${POWERCONTEXT_PROJECT_SCOPE_SCRIPT}" +WORKBUDDY_SCOPE_BINDING_PLACEHOLDER = "${POWERCONTEXT_SCOPE_BINDING_SCRIPT}" WORKBUDDY_HOOK_DRIVER = "workbuddy_powercontext_hook.py" -WORKBUDDY_SCOPE_RESOLVER = "powercontext_project_scope.py" +WORKBUDDY_SCOPE_RESOLVER = "powercontext_scope_binding.py" WORKBUDDY_HOOK_MODULES = ( "workbuddy_powercontext_hook.py", "workbuddy_settings.py", "prepared_context.py", ) -WORKBUDDY_SCRIPT_MODULES = ("__init__.py", "project_scope.py") +WORKBUDDY_SCRIPT_MODULES = ("__init__.py", "workspace_scope.py") WORKBUDDY_SERVER_URL_ENV = "POWERCONTEXT_WORKBUDDY_SERVER_URL" WORKBUDDY_AUTHORIZATION_ENV = "POWERCONTEXT_WORKBUDDY_AUTHORIZATION" WORKBUDDY_MCP_URL = f"${{{WORKBUDDY_SERVER_URL_ENV}:-http://127.0.0.1:8000}}/mcp" @@ -220,7 +220,7 @@ def _install_hook_files(plugin_dir: Path, hooks_dir: Path) -> None: source_hooks = plugin_dir / WORKBUDDY_HOOKS_DIRNAME for name in WORKBUDDY_HOOK_MODULES: shutil.copy2(source_hooks / name, hooks_dir / name) - shutil.copy2(plugin_dir / "scripts" / "project_scope.py", hooks_dir / WORKBUDDY_SCOPE_RESOLVER) + shutil.copy2(plugin_dir / "scripts" / "workspace_scope.py", hooks_dir / WORKBUDDY_SCOPE_RESOLVER) except OSError as error: raise SetupError.workbuddy_hooks_write(hooks_dir, error) from error @@ -330,7 +330,7 @@ def _install_workbuddy_skill(plugin_dir: Path, skills_dir: Path, hooks_dir: Path content = skill_markdown.read_text(encoding="utf-8") content = content.replace(WORKBUDDY_PYTHON_PLACEHOLDER, _shell_argument(_python_executable())) content = content.replace( - WORKBUDDY_PROJECT_SCOPE_PLACEHOLDER, + WORKBUDDY_SCOPE_BINDING_PLACEHOLDER, _shell_argument((hooks_dir / WORKBUDDY_SCOPE_RESOLVER).as_posix()), ) skill_markdown.write_text(content, encoding="utf-8") @@ -438,7 +438,7 @@ def _skill_diagnostic(skill_file: Path) -> Diagnostic: content = skill_file.read_text(encoding="utf-8") except OSError: return Diagnostic(status=DiagnosticStatus.FAILED, detail=f"cannot read {skill_file}") - if WORKBUDDY_PROJECT_SCOPE_PLACEHOLDER in content or WORKBUDDY_PYTHON_PLACEHOLDER in content: + if WORKBUDDY_SCOPE_BINDING_PLACEHOLDER in content or WORKBUDDY_PYTHON_PLACEHOLDER in content: return Diagnostic( status=DiagnosticStatus.FAILED, detail="PowerContext WorkBuddy skill still contains an unresolved command placeholder", diff --git a/src/powercontext/client/cli.py b/src/powercontext/client/cli.py index 811f4e25b..5cea0bba8 100644 --- a/src/powercontext/client/cli.py +++ b/src/powercontext/client/cli.py @@ -31,6 +31,7 @@ from powercontext.client.projections import SkillExportTarget, export_skill from powercontext.client.settings import ClientSettings from powercontext.http import ( + AllScopeSelection, ApproveArtifactCandidateRequest, ArtifactCandidate, ArtifactCandidatePage, @@ -38,6 +39,7 @@ CandidateFamily, CandidateStatus, Capabilities, + ExactScopeSelection, ExperienceProposal, ExternalSkillImportMode, ExternalSkillResolution, @@ -61,12 +63,15 @@ ScanExternalSkillsRequest, ScanExternalSkillsResponse, ScopedStats, + ScopeId, + ScopeSelection, SkillArtifact, SkillGenerationOrigin, SkillProposal, SkillValidationItem, SourceReference, StatsPeriod, + SubtreeScopeSelection, ) HELP_OPTION_NAMES = ("-h", "--help") @@ -157,12 +162,23 @@ def capabilities(context: typer.Context) -> None: def stats( context: typer.Context, - scope_id: Annotated[str, typer.Option(help="Application scope to inspect.")], + scope_id: Annotated[list[str] | None, typer.Option(help="Exact application scope to include.")] = None, + root_scope_id: Annotated[str | None, typer.Option(help="Organization subtree root to include.")] = None, period: Annotated[StatsPeriod, typer.Option(help="Bounded UTC statistics period.")] = StatsPeriod.FIELD_30D, ) -> None: - """Show current inventory and bounded usage for one scope.""" - - request = GetStatsRequest(scope_id=scope_id, period=period) + """Show current inventory and bounded usage for a Scope selection.""" + + if scope_id and root_scope_id is not None: + raise typer.BadParameter("--scope-id and --root-scope-id are mutually exclusive") # noqa: TRY003 + if root_scope_id is not None: + selection = ScopeSelection(root=SubtreeScopeSelection(mode="subtree", root_scope_id=root_scope_id)) + elif scope_id: + selection = ScopeSelection( + root=ExactScopeSelection(mode="exact", scope_ids=[ScopeId(value) for value in scope_id]) + ) + else: + selection = ScopeSelection(root=AllScopeSelection(mode="all")) + request = GetStatsRequest(selection=selection, period=period) asyncio.run(_execute(context, lambda client: client.get_stats(request))) @@ -762,7 +778,7 @@ def _print_human_response(response: _ClientResponse) -> None: def _print_stats(response: ScopedStats) -> None: inventory = response.inventory - typer.echo(f"Scope: {response.scope_id}") + typer.echo(f"Selection: {response.selection.root.mode} ({len(response.scope_ids)} Scopes)") typer.echo(f"As of: {response.as_of.isoformat()}") typer.echo( "Sources: " diff --git a/src/powercontext/client/client.py b/src/powercontext/client/client.py index 2c1618f2f..2413b7dbb 100644 --- a/src/powercontext/client/client.py +++ b/src/powercontext/client/client.py @@ -17,8 +17,10 @@ from __future__ import annotations import asyncio +from collections.abc import Mapping from types import TracebackType from typing import Self, TypeVar +from urllib.parse import quote import httpx from pydantic import TypeAdapter, ValidationError @@ -31,16 +33,17 @@ ApproveArtifactCandidateRequest, ArtifactCandidate, ArtifactCandidatePage, - AttachHandoffReportWorkspaceRequest, + ArtifactPublication, Capabilities, CaptureContentSourceRequest, CaptureContentSourceResponse, + ClearScopeBindingRequest, + ClearScopeBindingResponse, CommitHandoffRequest, CommittedHandoff, ContinueHandoffRequest, - CreateHandoffReportProjectRequest, + CreateScopeRequest, CreateWorkContractRequest, - DetachHandoffReportWorkspaceRequest, ErrorResponse, ExperienceArtifact, ExternalSkillResolution, @@ -52,9 +55,7 @@ GenerateSkillRequest, GetArtifactCandidateRequest, GetExperienceRequest, - GetHandoffReportProjectRequest, GetHandoffReportRequest, - GetHandoffReportWorkspaceRequest, GetMemoryEntryRequest, GetSkillRequest, GetStatsRequest, @@ -62,20 +63,13 @@ HandoffActivation, HandoffCurrentWorkRequest, HandoffDraft, - HandoffReportActivityPage, HandoffReportResponse, - HandoffReportWorkspaceBinding, HandoffResolution, HealthResponse, ImportExternalSkillRequest, - KnownHandoffScopePage, ListArtifactCandidatesRequest, ListExternalSkillsRequest, ListExternalSkillsResponse, - ListHandoffReportActivitiesRequest, - ListHandoffReportKnownScopesRequest, - ListHandoffReportProjectsRequest, - ListHandoffReportWorkstreamsRequest, ListMemoryChangesRequest, ListMemoryChangesResponse, ListMemoryEntriesRequest, @@ -87,89 +81,84 @@ PreparedHandoff, PreparedWorkHandoff, PrepareHandoffRequest, - ProjectDescriptor, - ProjectPage, ProposeExperienceRequest, ProposeSkillRequest, - PurgeHandoffReportActivitiesRequest, - PurgeHandoffReportActivitiesResponse, + PublishArtifactRequest, ReadinessResponse, - RecordHandoffReportActivityRequest, RecordTaskOutcomeRequest, - RegisterHandoffReportWorkstreamRequest, RejectArtifactCandidateRequest, RememberMemoryRequest, ResolveExternalSkillRequest, + ResolveScopeBindingRequest, + ResolveScopeSelectionRequest, RetireMemoryEntryRequest, ReviseArtifactCandidateRequest, ReviseMemoryEntryRequest, ScanExternalSkillsRequest, ScanExternalSkillsResponse, + ScopeBinding, + ScopeDescriptor, ScopedStats, + ScopePage, SearchMemoryRequest, SearchMemoryResponse, + SetDefaultScopeRequest, + SetScopeBindingRequest, SkillArtifact, - StoredHandoffReportActivity, - UpdateHandoffReportProjectRequest, - UpdateHandoffReportWorkstreamRequest, + UpdateScopeRequest, WorkSourceReceipt, - WorkstreamDescriptor, - WorkstreamPage, ) from powercontext.http._generated.operations import ( ACKNOWLEDGE_HANDOFF, ACTIVATE_HANDOFF, APPROVE_ARTIFACT_CANDIDATE, - ATTACH_HANDOFF_REPORT_WORKSPACE, CAPTURE_CONTENT_SOURCE, + CLEAR_SCOPE_BINDING, COMMIT_HANDOFF, CONTINUE_HANDOFF, - CREATE_HANDOFF_REPORT_PROJECT, + CREATE_SCOPE, CREATE_WORK_CONTRACT, - DETACH_HANDOFF_REPORT_WORKSPACE, FINALIZE_HANDOFF, FLUSH_MEMORY, GENERATE_EXPERIENCE, GENERATE_SKILL, GET_ARTIFACT_CANDIDATE, GET_CAPABILITIES, + GET_DEFAULT_SCOPE, GET_EXPERIENCE, GET_HANDOFF_REPORT, - GET_HANDOFF_REPORT_PROJECT, - GET_HANDOFF_REPORT_WORKSPACE, GET_LIVENESS, GET_MEMORY_ENTRY, GET_READINESS, + GET_SCOPE, GET_SKILL, GET_STATS, HANDOFF_CURRENT_WORK, IMPORT_EXTERNAL_SKILL, LIST_ARTIFACT_CANDIDATES, LIST_EXTERNAL_SKILLS, - LIST_HANDOFF_REPORT_ACTIVITIES, - LIST_HANDOFF_REPORT_KNOWN_SCOPES, - LIST_HANDOFF_REPORT_PROJECTS, - LIST_HANDOFF_REPORT_WORKSTREAMS, LIST_MEMORY_CHANGES, LIST_MEMORY_ENTRIES, + LIST_SCOPES, PREPARE_CONTEXT, PREPARE_HANDOFF, PROPOSE_EXPERIENCE, PROPOSE_SKILL, - PURGE_HANDOFF_REPORT_ACTIVITIES, - RECORD_HANDOFF_REPORT_ACTIVITY, + PUBLISH_ARTIFACT, RECORD_TASK_OUTCOME, - REGISTER_HANDOFF_REPORT_WORKSTREAM, REJECT_ARTIFACT_CANDIDATE, REMEMBER_MEMORY, RESOLVE_EXTERNAL_SKILL, + RESOLVE_SCOPE_BINDING, + RESOLVE_SCOPE_SELECTION, RETIRE_MEMORY_ENTRY, REVISE_ARTIFACT_CANDIDATE, REVISE_MEMORY_ENTRY, SCAN_EXTERNAL_SKILLS, SEARCH_MEMORY, - UPDATE_HANDOFF_REPORT_PROJECT, - UPDATE_HANDOFF_REPORT_WORKSTREAM, + SET_DEFAULT_SCOPE, + SET_SCOPE_BINDING, + UPDATE_SCOPE, Operation, ) from powercontext.transport import is_plaintext_non_loopback @@ -246,122 +235,65 @@ async def get_capabilities(self) -> Capabilities: return await self._request(GET_CAPABILITIES) - async def get_stats(self, request: GetStatsRequest) -> ScopedStats: - """Read current inventory and bounded usage for one scope.""" + async def list_scopes(self) -> ScopePage: + """List durable Scope descriptors.""" - return await self._request(GET_STATS, request) + return await self._request(LIST_SCOPES) - async def create_handoff_report_project( - self, - request: CreateHandoffReportProjectRequest, - ) -> ProjectDescriptor: - """Create one explicit Report Project.""" + async def create_scope(self, request: CreateScopeRequest) -> ScopeDescriptor: + """Create one independent Scope boundary.""" - return await self._request(CREATE_HANDOFF_REPORT_PROJECT, request) + return await self._request(CREATE_SCOPE, request) - async def get_handoff_report_project( - self, - request: GetHandoffReportProjectRequest, - ) -> ProjectDescriptor: - """Read one current Report Project descriptor.""" + async def get_scope(self, scope_id: str) -> ScopeDescriptor: + """Read one exact Scope descriptor.""" - return await self._request(GET_HANDOFF_REPORT_PROJECT, request) + return await self._request(GET_SCOPE, path_parameters={"scope_id": scope_id}) - async def update_handoff_report_project( - self, - request: UpdateHandoffReportProjectRequest, - ) -> ProjectDescriptor: - """CAS-update one Report Project descriptor.""" + async def update_scope(self, scope_id: str, request: UpdateScopeRequest) -> ScopeDescriptor: + """Replace mutable Scope metadata and relationships.""" - return await self._request(UPDATE_HANDOFF_REPORT_PROJECT, request) + return await self._request(UPDATE_SCOPE, request, path_parameters={"scope_id": scope_id}) - async def list_handoff_report_projects( - self, - request: ListHandoffReportProjectsRequest, - ) -> ProjectPage: - """List Report Projects with cursor pagination.""" + async def get_default_scope(self) -> ScopeDescriptor: + """Read the host's default Scope target.""" - return await self._request(LIST_HANDOFF_REPORT_PROJECTS, request) + return await self._request(GET_DEFAULT_SCOPE) - async def list_handoff_report_known_scopes( - self, - request: ListHandoffReportKnownScopesRequest, - ) -> KnownHandoffScopePage: - """List scopes that contain a committed Handoff.""" + async def set_default_scope(self, request: SetDefaultScopeRequest) -> ScopeDescriptor: + """Change the host's default Scope target.""" - return await self._request(LIST_HANDOFF_REPORT_KNOWN_SCOPES, request) + return await self._request(SET_DEFAULT_SCOPE, request) - async def register_handoff_report_workstream( - self, - request: RegisterHandoffReportWorkstreamRequest, - ) -> WorkstreamDescriptor: - """Register one existing scope as a Report Workstream.""" + async def resolve_scope_selection(self, request: ResolveScopeSelectionRequest) -> ScopePage: + """Resolve all, exact, or subtree into exact Scope descriptors.""" - return await self._request(REGISTER_HANDOFF_REPORT_WORKSTREAM, request) + return await self._request(RESOLVE_SCOPE_SELECTION, request) - async def list_handoff_report_workstreams( - self, - request: ListHandoffReportWorkstreamsRequest, - ) -> WorkstreamPage: - """List Workstreams belonging to one Report Project.""" + async def resolve_scope_binding(self, request: ResolveScopeBindingRequest) -> ScopeDescriptor: + """Resolve explicit and external host bindings to one Scope.""" - return await self._request(LIST_HANDOFF_REPORT_WORKSTREAMS, request) + return await self._request(RESOLVE_SCOPE_BINDING, request) - async def update_handoff_report_workstream( - self, - request: UpdateHandoffReportWorkstreamRequest, - ) -> WorkstreamDescriptor: - """CAS-update one Report Workstream descriptor.""" + async def set_scope_binding(self, request: SetScopeBindingRequest) -> ScopeBinding: + """Bind one external integration identity to a Scope.""" - return await self._request(UPDATE_HANDOFF_REPORT_WORKSTREAM, request) + return await self._request(SET_SCOPE_BINDING, request) - async def record_handoff_report_activity( - self, - request: RecordHandoffReportActivityRequest, - ) -> StoredHandoffReportActivity: - """Record one explicit Report-owned Activity observation.""" + async def clear_scope_binding(self, request: ClearScopeBindingRequest) -> ClearScopeBindingResponse: + """Clear one external integration binding.""" - return await self._request(RECORD_HANDOFF_REPORT_ACTIVITY, request) + return await self._request(CLEAR_SCOPE_BINDING, request) - async def list_handoff_report_activities( - self, - request: ListHandoffReportActivitiesRequest, - ) -> HandoffReportActivityPage: - """List one frozen cursor page of Report-owned Activities.""" - - return await self._request(LIST_HANDOFF_REPORT_ACTIVITIES, request) + async def publish_artifact(self, request: PublishArtifactRequest) -> ArtifactPublication: + """Deliver one exact Artifact revision into another Scope.""" - async def purge_handoff_report_activities( - self, - request: PurgeHandoffReportActivitiesRequest, - ) -> PurgeHandoffReportActivitiesResponse: - """Purge Report-owned Activities before an observation boundary.""" + return await self._request(PUBLISH_ARTIFACT, request) - return await self._request(PURGE_HANDOFF_REPORT_ACTIVITIES, request) - - async def get_handoff_report_workspace( - self, - request: GetHandoffReportWorkspaceRequest, - ) -> HandoffReportWorkspaceBinding: - """Read one confirmed Workspace-to-Project binding.""" - - return await self._request(GET_HANDOFF_REPORT_WORKSPACE, request) - - async def attach_handoff_report_workspace( - self, - request: AttachHandoffReportWorkspaceRequest, - ) -> HandoffReportWorkspaceBinding: - """Attach a Workspace to an exact Report Project using CAS.""" - - return await self._request(ATTACH_HANDOFF_REPORT_WORKSPACE, request) - - async def detach_handoff_report_workspace( - self, - request: DetachHandoffReportWorkspaceRequest, - ) -> HandoffReportWorkspaceBinding: - """Detach a Workspace binding using its exact version.""" + async def get_stats(self, request: GetStatsRequest) -> ScopedStats: + """Read current inventory and bounded usage for one scope.""" - return await self._request(DETACH_HANDOFF_REPORT_WORKSPACE, request) + return await self._request(GET_STATS, request) async def get_handoff_report(self, request: GetHandoffReportRequest) -> HandoffReportResponse | str: """Generate the current canonical Handoff Report projection.""" @@ -592,7 +524,10 @@ async def _request( self, operation: Operation[_RequestT, _ResponseT], request: _RequestT | None = None, + *, + path_parameters: Mapping[str, str] | None = None, ) -> _ResponseT: + operation_path = _bind_operation_path(operation, path_parameters) json_payload = None query_parameters = None if request is not None: @@ -615,7 +550,7 @@ async def _request( span.inject(headers) response = await self._http_client.request( operation.method, - f"{self._base_url}{operation.path}", + f"{self._base_url}{operation_path}", json=json_payload, headers=headers, params=query_parameters, @@ -625,7 +560,7 @@ async def _request( raise except httpx.HTTPError as exc: span.finish("failure", error=exc) - raise TransportError(operation.path) from exc + raise TransportError(operation_path) from exc except BaseException as error: span.finish("failure", error=error) raise @@ -649,11 +584,38 @@ async def _request( return TypeAdapter(operation.response_type).validate_json(response.content) except ValidationError as exc: raise InvalidResponseError( - operation.path, + operation_path, request_id=request_id, ) from exc +def _bind_operation_path( + operation: Operation[_RequestT, _ResponseT], + path_parameters: Mapping[str, str] | None, +) -> str: + values = {} if path_parameters is None else dict(path_parameters) + expected = set(operation.path_parameters) + provided = set(values) + if provided != expected: + missing = sorted(expected - provided) + unexpected = sorted(provided - expected) + message = f"{operation.operation_id} path parameters do not match" + if missing: + message += f"; missing: {', '.join(missing)}" + if unexpected: + message += f"; unexpected: {', '.join(unexpected)}" + raise TypeError(message) + + path = operation.path + for name in operation.path_parameters: + value = values[name] + if not isinstance(value, str): + message = f"{operation.operation_id} path parameter {name} must be a string" + raise TypeError(message) + path = path.replace(f"{{{name}}}", quote(value, safe="")) + return path + + def _decode_error(content: bytes) -> ErrorResponse | None: try: return ErrorResponse.model_validate_json(content) diff --git a/src/powercontext/http/__init__.py b/src/powercontext/http/__init__.py index 56c05bf89..0ad898141 100644 --- a/src/powercontext/http/__init__.py +++ b/src/powercontext/http/__init__.py @@ -17,12 +17,16 @@ from powercontext.http._generated.models import ( AcknowledgeHandoffRequest, ActivateHandoffRequest, + AgentKind, + AllScopeSelection, ApproveArtifactCandidateRequest, + ArtifactAddress, ArtifactCandidate, ArtifactCandidatePage, ArtifactInventoryStatistics, + ArtifactPublication, ArtifactReference, - AttachHandoffReportWorkspaceRequest, + AuthorizationNote, CandidateFamily, CandidateFamilyCount, CandidateInventoryStatistics, @@ -31,17 +35,22 @@ CaptureContentSourceRequest, CaptureContentSourceResponse, CaptureStatus, + ClearScopeBindingRequest, + ClearScopeBindingResponse, CommitHandoffRequest, CommittedHandoff, + CompletionCriterion, + ContextReference, ContinueHandoffRequest, - CreateHandoffReportProjectRequest, + CreateScopeRequest, CreateWorkContractRequest, CurrentWorkHandoff, - DetachHandoffReportWorkspaceRequest, EntryChange, EntryChangeOperation, ErrorDetail, ErrorResponse, + ExactScopeSelection, + Exclusion, ExperienceArtifact, ExperienceProposal, ExternalSkillImportMode, @@ -60,13 +69,12 @@ GenerateSkillRequest, GetArtifactCandidateRequest, GetExperienceRequest, - GetHandoffReportProjectRequest, GetHandoffReportRequest, - GetHandoffReportWorkspaceRequest, GetMemoryEntryRequest, GetSkillRequest, GetStatsRequest, HandoffAcknowledgement, + HandoffAcknowledgementSelection, HandoffActivation, HandoffActivationStatus, HandoffArtifactCitation, @@ -81,15 +89,7 @@ HandoffMemoryCitation, HandoffOmission, HandoffReceiptStatus, - HandoffReportActivity, - HandoffReportActivityAgent, - HandoffReportActivityPage, - HandoffReportActivityVcsContext, - HandoffReportExternalReference, - HandoffReportPeriodRequest, - HandoffReportRepositoryRef, HandoffReportResponse, - HandoffReportWorkspaceBinding, HandoffResolution, HandoffResolutionStatus, HandoffSchema, @@ -98,20 +98,19 @@ HandoffStatement, HealthResponse, ImportExternalSkillRequest, + InScopeItem, InventoryStatistics, - KnownHandoffScope, - KnownHandoffScopePage, + Kind, + Kind1, + Kind2, ListArtifactCandidatesRequest, ListExternalSkillsRequest, ListExternalSkillsResponse, - ListHandoffReportActivitiesRequest, - ListHandoffReportKnownScopesRequest, - ListHandoffReportProjectsRequest, - ListHandoffReportWorkstreamsRequest, ListMemoryChangesRequest, ListMemoryChangesResponse, ListMemoryEntriesRequest, ListMemoryEntriesResponse, + LiveStateCheckStatus, MemoryCitation, MemoryEntry, MemoryEntryInventoryStatistics, @@ -127,6 +126,8 @@ ModelUsagePurposeBreakdown, ModelUsageStatistics, ModelUsageValue, + Omission, + OpenQuestion, PrepareContextRequest, PreparedContext, PreparedContextSchema, @@ -135,38 +136,47 @@ PreparedHandoffSchema, PreparedWorkHandoff, PrepareHandoffRequest, - ProjectDescriptor, - ProjectPage, ProposeExperienceRequest, ProposeSkillRequest, - PurgeHandoffReportActivitiesRequest, - PurgeHandoffReportActivitiesResponse, + Provider, + PublishArtifactRequest, ReadinessResponse, ReadinessStatus, RecallTokenDay, RecallTokenStatistics, RecallTokenValue, - RecordHandoffReportActivityRequest, + ReceiverChecks, + ReceiverReadinessCheckStatus, RecordTaskOutcomeRequest, - RegisterHandoffReportWorkstreamRequest, RejectArtifactCandidateRequest, + RemainingWorkItem, RememberMemoryRequest, - ReportActivitySource, - ReportCatalogState, ReportFormat, - ReportLocale, - ReportTimeBasis, ResolvedUsagePeriod, ResolveExternalSkillRequest, + ResolveScopeBindingRequest, + ResolveScopeSelectionRequest, RetireMemoryEntryRequest, ReviseArtifactCandidateRequest, ReviseMemoryEntryRequest, ScanExternalSkillsRequest, ScanExternalSkillsResponse, + Schema, + Schema1, + Schema2, + ScopeBinding, + ScopeBindingKey, + ScopeDescriptor, ScopedStats, + ScopeExternalReference, + ScopeId, + ScopePage, + ScopeSelection, SearchMemoryHit, SearchMemoryRequest, SearchMemoryResponse, + SetDefaultScopeRequest, + SetScopeBindingRequest, SkillArtifact, SkillGenerationOrigin, SkillProposal, @@ -174,34 +184,38 @@ SourceInventoryStatistics, SourceReference, StatsPeriod, - StoredHandoffReportActivity, + SubtreeScopeSelection, TaskCheck, TaskCheckStatus, TaskOutcome, TaskOutcomeStatus, + Timezone, TokenEstimatorProfile, - UpdateHandoffReportProjectRequest, - UpdateHandoffReportWorkstreamRequest, + Trust, + Trust2, + Trust3, + UpdateScopeRequest, UsageStatistics, WorkClaim, WorkClaimBasis, WorkContract, WorkSourceKind, WorkSourceReceipt, - WorkstreamDescriptor, - WorkstreamKind, - WorkstreamPage, ) __all__ = [ "AcknowledgeHandoffRequest", "ActivateHandoffRequest", + "AgentKind", + "AllScopeSelection", "ApproveArtifactCandidateRequest", + "ArtifactAddress", "ArtifactCandidate", "ArtifactCandidatePage", "ArtifactInventoryStatistics", + "ArtifactPublication", "ArtifactReference", - "AttachHandoffReportWorkspaceRequest", + "AuthorizationNote", "CandidateFamily", "CandidateFamilyCount", "CandidateInventoryStatistics", @@ -210,17 +224,22 @@ "CaptureContentSourceRequest", "CaptureContentSourceResponse", "CaptureStatus", + "ClearScopeBindingRequest", + "ClearScopeBindingResponse", "CommitHandoffRequest", "CommittedHandoff", + "CompletionCriterion", + "ContextReference", "ContinueHandoffRequest", - "CreateHandoffReportProjectRequest", + "CreateScopeRequest", "CreateWorkContractRequest", "CurrentWorkHandoff", - "DetachHandoffReportWorkspaceRequest", "EntryChange", "EntryChangeOperation", "ErrorDetail", "ErrorResponse", + "ExactScopeSelection", + "Exclusion", "ExperienceArtifact", "ExperienceProposal", "ExternalSkillImportMode", @@ -239,13 +258,12 @@ "GeneratedCandidateStatus", "GetArtifactCandidateRequest", "GetExperienceRequest", - "GetHandoffReportProjectRequest", "GetHandoffReportRequest", - "GetHandoffReportWorkspaceRequest", "GetMemoryEntryRequest", "GetSkillRequest", "GetStatsRequest", "HandoffAcknowledgement", + "HandoffAcknowledgementSelection", "HandoffActivation", "HandoffActivationStatus", "HandoffArtifactCitation", @@ -260,15 +278,7 @@ "HandoffMemoryCitation", "HandoffOmission", "HandoffReceiptStatus", - "HandoffReportActivity", - "HandoffReportActivityAgent", - "HandoffReportActivityPage", - "HandoffReportActivityVcsContext", - "HandoffReportExternalReference", - "HandoffReportPeriodRequest", - "HandoffReportRepositoryRef", "HandoffReportResponse", - "HandoffReportWorkspaceBinding", "HandoffResolution", "HandoffResolutionStatus", "HandoffSchema", @@ -277,20 +287,19 @@ "HandoffStatement", "HealthResponse", "ImportExternalSkillRequest", + "InScopeItem", "InventoryStatistics", - "KnownHandoffScope", - "KnownHandoffScopePage", + "Kind", + "Kind1", + "Kind2", "ListArtifactCandidatesRequest", "ListExternalSkillsRequest", "ListExternalSkillsResponse", - "ListHandoffReportActivitiesRequest", - "ListHandoffReportKnownScopesRequest", - "ListHandoffReportProjectsRequest", - "ListHandoffReportWorkstreamsRequest", "ListMemoryChangesRequest", "ListMemoryChangesResponse", "ListMemoryEntriesRequest", "ListMemoryEntriesResponse", + "LiveStateCheckStatus", "MemoryCitation", "MemoryEntry", "MemoryEntryInventoryStatistics", @@ -306,6 +315,8 @@ "ModelUsagePurposeBreakdown", "ModelUsageStatistics", "ModelUsageValue", + "Omission", + "OpenQuestion", "PrepareContextRequest", "PrepareHandoffRequest", "PreparedContext", @@ -314,38 +325,47 @@ "PreparedHandoff", "PreparedHandoffSchema", "PreparedWorkHandoff", - "ProjectDescriptor", - "ProjectPage", "ProposeExperienceRequest", "ProposeSkillRequest", - "PurgeHandoffReportActivitiesRequest", - "PurgeHandoffReportActivitiesResponse", + "Provider", + "PublishArtifactRequest", "ReadinessResponse", "ReadinessStatus", "RecallTokenDay", "RecallTokenStatistics", "RecallTokenValue", - "RecordHandoffReportActivityRequest", + "ReceiverChecks", + "ReceiverReadinessCheckStatus", "RecordTaskOutcomeRequest", - "RegisterHandoffReportWorkstreamRequest", "RejectArtifactCandidateRequest", + "RemainingWorkItem", "RememberMemoryRequest", - "ReportActivitySource", - "ReportCatalogState", "ReportFormat", - "ReportLocale", - "ReportTimeBasis", "ResolveExternalSkillRequest", + "ResolveScopeBindingRequest", + "ResolveScopeSelectionRequest", "ResolvedUsagePeriod", "RetireMemoryEntryRequest", "ReviseArtifactCandidateRequest", "ReviseMemoryEntryRequest", "ScanExternalSkillsRequest", "ScanExternalSkillsResponse", + "Schema", + "Schema1", + "Schema2", + "ScopeBinding", + "ScopeBindingKey", + "ScopeDescriptor", + "ScopeExternalReference", + "ScopeId", + "ScopePage", + "ScopeSelection", "ScopedStats", "SearchMemoryHit", "SearchMemoryRequest", "SearchMemoryResponse", + "SetDefaultScopeRequest", + "SetScopeBindingRequest", "SkillArtifact", "SkillGenerationOrigin", "SkillProposal", @@ -353,21 +373,21 @@ "SourceInventoryStatistics", "SourceReference", "StatsPeriod", - "StoredHandoffReportActivity", + "SubtreeScopeSelection", "TaskCheck", "TaskCheckStatus", "TaskOutcome", "TaskOutcomeStatus", + "Timezone", "TokenEstimatorProfile", - "UpdateHandoffReportProjectRequest", - "UpdateHandoffReportWorkstreamRequest", + "Trust", + "Trust2", + "Trust3", + "UpdateScopeRequest", "UsageStatistics", "WorkClaim", "WorkClaimBasis", "WorkContract", "WorkSourceKind", "WorkSourceReceipt", - "WorkstreamDescriptor", - "WorkstreamKind", - "WorkstreamPage", ] diff --git a/src/powercontext/http/_generated/models.py b/src/powercontext/http/_generated/models.py index ad2a598c1..443c919c4 100644 --- a/src/powercontext/http/_generated/models.py +++ b/src/powercontext/http/_generated/models.py @@ -30,6 +30,188 @@ class ArtifactReference(BaseModel): revision: Annotated[StrictInt, Field(ge=1)] +class ArtifactAddress(BaseModel): + model_config = ConfigDict( + extra="forbid", + ) + scope_id: Annotated[StrictStr, Field(max_length=256, min_length=1, pattern=".*\\S.*")] + artifact: ArtifactReference + + +class PublishArtifactRequest(BaseModel): + model_config = ConfigDict( + extra="forbid", + ) + source: ArtifactAddress + target_scope_id: Annotated[StrictStr, Field(max_length=256, min_length=1, pattern=".*\\S.*")] + idempotency_key: Annotated[StrictStr, Field(max_length=256, min_length=1, pattern=".*\\S.*")] + + +class ArtifactPublication(BaseModel): + model_config = ConfigDict( + extra="forbid", + ) + source: ArtifactAddress + target: ArtifactAddress + content_digest: Annotated[StrictStr, Field(pattern="^[0-9a-f]{64}$")] + + +class ScopeExternalReference(BaseModel): + model_config = ConfigDict( + extra="forbid", + ) + kind: Annotated[StrictStr, Field(max_length=128, min_length=1, pattern=".*\\S.*")] + value: Annotated[StrictStr, Field(max_length=2000, min_length=1, pattern=".*\\S.*")] + + +class ContextReference(RootModel[StrictStr]): + root: Annotated[StrictStr, Field(max_length=256, min_length=1, pattern=".*\\S.*")] + + +class ScopeDescriptor(BaseModel): + model_config = ConfigDict( + extra="forbid", + ) + scope_id: Annotated[StrictStr, Field(max_length=256, min_length=1, pattern=".*\\S.*")] + title: Annotated[StrictStr, Field(max_length=256, min_length=1, pattern=".*\\S.*")] + summary: Annotated[StrictStr, Field(max_length=2000, min_length=1, pattern=".*\\S.*")] + parent_scope_id: Annotated[StrictStr | None, Field(max_length=256, min_length=1, pattern=".*\\S.*")] = None + context_references: list[ContextReference] + external_references: list[ScopeExternalReference] + version: Annotated[StrictInt, Field(ge=1)] + + +class ScopePage(BaseModel): + model_config = ConfigDict( + extra="forbid", + ) + items: list[ScopeDescriptor] + + +class CreateScopeRequest(BaseModel): + model_config = ConfigDict( + extra="forbid", + ) + title: Annotated[StrictStr, Field(max_length=256, min_length=1, pattern=".*\\S.*")] + summary: Annotated[StrictStr, Field(max_length=2000, min_length=1, pattern=".*\\S.*")] + parent_scope_id: Annotated[StrictStr | None, Field(max_length=256, min_length=1, pattern=".*\\S.*")] = None + context_references: Annotated[list[ContextReference], Field(validate_default=True)] = [] + external_references: Annotated[list[ScopeExternalReference], Field(validate_default=True)] = [] + idempotency_key: Annotated[StrictStr, Field(max_length=256, min_length=1, pattern=".*\\S.*")] + + +class UpdateScopeRequest(BaseModel): + model_config = ConfigDict( + extra="forbid", + ) + expected_version: Annotated[StrictInt, Field(ge=1)] + title: Annotated[StrictStr, Field(max_length=256, min_length=1, pattern=".*\\S.*")] + summary: Annotated[StrictStr, Field(max_length=2000, min_length=1, pattern=".*\\S.*")] + parent_scope_id: Annotated[StrictStr | None, Field(max_length=256, min_length=1, pattern=".*\\S.*")] = None + context_references: Annotated[list[ContextReference], Field(validate_default=True)] = [] + external_references: Annotated[list[ScopeExternalReference], Field(validate_default=True)] = [] + + +class SetDefaultScopeRequest(BaseModel): + model_config = ConfigDict( + extra="forbid", + ) + scope_id: Annotated[StrictStr, Field(max_length=256, min_length=1, pattern=".*\\S.*")] + + +class Mode(StrEnum): + ALL = "all" + + +class AllScopeSelection(BaseModel): + model_config = ConfigDict( + extra="forbid", + ) + mode: Literal["all"] + + +class Mode1(StrEnum): + EXACT = "exact" + + +class ScopeId(RootModel[StrictStr]): + root: Annotated[StrictStr, Field(max_length=256, min_length=1, pattern=".*\\S.*")] + + +class ExactScopeSelection(BaseModel): + model_config = ConfigDict( + extra="forbid", + ) + mode: Literal["exact"] + scope_ids: Annotated[list[ScopeId], Field(min_length=1)] + + +class Mode2(StrEnum): + SUBTREE = "subtree" + + +class SubtreeScopeSelection(BaseModel): + model_config = ConfigDict( + extra="forbid", + ) + mode: Literal["subtree"] + root_scope_id: Annotated[StrictStr, Field(max_length=256, min_length=1, pattern=".*\\S.*")] + + +class ScopeSelection(RootModel[AllScopeSelection | ExactScopeSelection | SubtreeScopeSelection]): + root: Annotated[AllScopeSelection | ExactScopeSelection | SubtreeScopeSelection, Field(discriminator="mode")] + + +class ResolveScopeSelectionRequest(BaseModel): + model_config = ConfigDict( + extra="forbid", + ) + selection: ScopeSelection + + +class ScopeBindingKey(BaseModel): + model_config = ConfigDict( + extra="forbid", + ) + integration: Annotated[StrictStr, Field(max_length=128, min_length=1, pattern=".*\\S.*")] + kind: Annotated[StrictStr, Field(max_length=64, min_length=1, pattern=".*\\S.*")] + external_id: Annotated[StrictStr, Field(max_length=256, min_length=1, pattern=".*\\S.*")] + + +class ScopeBinding(BaseModel): + model_config = ConfigDict( + extra="forbid", + ) + key: ScopeBindingKey + scope_id: Annotated[StrictStr, Field(max_length=256, min_length=1, pattern=".*\\S.*")] + + +class SetScopeBindingRequest(RootModel[ScopeBinding]): + root: ScopeBinding + + +class ClearScopeBindingRequest(BaseModel): + model_config = ConfigDict( + extra="forbid", + ) + key: ScopeBindingKey + + +class ClearScopeBindingResponse(BaseModel): + model_config = ConfigDict( + extra="forbid", + ) + cleared: StrictBool + + +class ResolveScopeBindingRequest(BaseModel): + model_config = ConfigDict( + extra="forbid", + ) + explicit_scope_id: Annotated[StrictStr | None, Field(max_length=256, min_length=1, pattern=".*\\S.*")] = None + binding_keys: Annotated[list[ScopeBindingKey], Field(validate_default=True)] = [] + + class ApproveArtifactCandidateRequest(BaseModel): model_config = ConfigDict( extra="forbid", @@ -380,254 +562,11 @@ class GetSkillRequest(BaseModel): artifact: ArtifactReference -class ListHandoffReportProjectsRequest(BaseModel): - model_config = ConfigDict( - extra="forbid", - ) - cursor: StrictStr | None = None - limit: Annotated[StrictInt, Field(ge=1, le=100)] = 50 - include_archived: StrictBool = False - - -class GetHandoffReportProjectRequest(BaseModel): - model_config = ConfigDict( - extra="forbid", - ) - project_id: Annotated[StrictStr, Field(max_length=256, min_length=1)] - - -class Label(RootModel[StrictStr]): - root: Annotated[StrictStr, Field(max_length=128, min_length=1)] - - -class ListHandoffReportWorkstreamsRequest(BaseModel): - model_config = ConfigDict( - extra="forbid", - ) - project_id: Annotated[StrictStr, Field(max_length=256, min_length=1)] - cursor: StrictStr | None = None - limit: Annotated[StrictInt, Field(ge=1, le=100)] = 50 - include_archived: StrictBool = False - - -class ListHandoffReportKnownScopesRequest(BaseModel): - model_config = ConfigDict( - extra="forbid", - ) - cursor: StrictStr | None = None - limit: Annotated[StrictInt, Field(ge=1, le=100)] = 50 - - -class KnownHandoffScope(BaseModel): - model_config = ConfigDict( - extra="forbid", - ) - scope_id: Annotated[StrictStr, Field(max_length=256, min_length=1)] - - -class KnownHandoffScopePage(BaseModel): - model_config = ConfigDict( - extra="forbid", - ) - items: list[KnownHandoffScope] - next_cursor: StrictStr | None = None - - -class HandoffReportPeriodRequest(BaseModel): - model_config = ConfigDict( - extra="forbid", - ) - start: AwareDatetime - end: AwareDatetime - timezone: Annotated[StrictStr | None, Field(max_length=256, min_length=1)] = None - compare_to_previous_period: StrictBool = False - - -class ReportActivitySource(StrEnum): - HANDOFF_OBSERVATION = "handoff_observation" - GIT_COMMIT = "git_commit" - GIT_WORKTREE = "git_worktree" - CODING_SESSION = "coding_session" - OTHER = "other" - - -class ReportTimeBasis(StrEnum): - SOURCE_REPORTED = "source_reported" - HOST_OBSERVED = "host_observed" - FIRST_SEEN = "first_seen" - CURRENT_ONLY = "current_only" - UNKNOWN = "unknown" - - -class HandoffReportActivityAgent(BaseModel): - model_config = ConfigDict( - extra="forbid", - ) - provider: Annotated[StrictStr | None, Field(max_length=64, min_length=1)] = None - label: Annotated[StrictStr | None, Field(max_length=128, min_length=1)] = None - - -class HandoffReportActivityVcsContext(BaseModel): - model_config = ConfigDict( - extra="forbid", - ) - branch: Annotated[StrictStr | None, Field(max_length=256, min_length=1)] = None - head_revision: Annotated[StrictStr | None, Field(max_length=256, min_length=1)] = None - - -class Schema3(StrEnum): - POWERCONTEXT_HANDOFF_REPORT_ACTIVITY_V1 = "powercontext.handoff-report-activity.v1" - - -class Trust4(StrEnum): - UNTRUSTED_OBSERVATION = "untrusted_observation" - - -class ListHandoffReportActivitiesRequest(BaseModel): - model_config = ConfigDict( - extra="forbid", - ) - project_id: Annotated[StrictStr, Field(max_length=256, min_length=1)] - period_start: AwareDatetime | None = None - period_end: AwareDatetime | None = None - sources: Annotated[list[ReportActivitySource] | None, Field(max_length=5)] = None - after_cursor: Annotated[StrictInt, Field(ge=0)] = 0 - through_cursor: Annotated[StrictInt | None, Field(ge=0)] = None - limit: Annotated[StrictInt, Field(ge=1, le=100)] = 50 - - -class PurgeHandoffReportActivitiesRequest(BaseModel): - model_config = ConfigDict( - extra="forbid", - ) - project_id: Annotated[StrictStr, Field(max_length=256, min_length=1)] - observed_before: AwareDatetime - - -class PurgeHandoffReportActivitiesResponse(BaseModel): - model_config = ConfigDict( - extra="forbid", - ) - deleted_count: Annotated[StrictInt, Field(ge=0)] - - -class Provider1(StrEnum): - GITHUB = "github" - GITLAB = "gitlab" - LOCAL = "local" - OTHER = "other" - - -class HandoffReportRepositoryRef(BaseModel): - model_config = ConfigDict( - extra="forbid", - ) - provider: Provider1 - repository_id: Annotated[StrictStr | None, Field(max_length=256, min_length=1)] - normalized_remote: Annotated[StrictStr | None, Field(max_length=2048, min_length=1)] - subpath: Annotated[StrictStr | None, Field(max_length=1024, min_length=1)] - - -class Schema4(StrEnum): - POWERCONTEXT_WORKSPACE_BINDING_V1 = "powercontext.workspace-binding.v1" - - -class State(StrEnum): - CONFIRMED = "confirmed" - DETACHED = "detached" - - -class HandoffReportWorkspaceBinding(BaseModel): - model_config = ConfigDict( - extra="forbid", - ) - schema_: Annotated[Schema4, Field(alias="schema")] - workspace_instance_id: Annotated[StrictStr, Field(max_length=256, min_length=1)] - project_id: Annotated[StrictStr, Field(max_length=256, min_length=1)] - repository_ref: HandoffReportRepositoryRef - state: State - confirmed_at: AwareDatetime - version: Annotated[StrictInt, Field(ge=1)] - - -class GetHandoffReportWorkspaceRequest(BaseModel): - model_config = ConfigDict( - extra="forbid", - ) - workspace_instance_id: Annotated[StrictStr, Field(max_length=256, min_length=1)] - - -class AttachHandoffReportWorkspaceRequest(BaseModel): - model_config = ConfigDict( - extra="forbid", - ) - workspace_instance_id: Annotated[StrictStr, Field(max_length=256, min_length=1)] - project_id: Annotated[StrictStr, Field(max_length=256, min_length=1)] - repository_ref: HandoffReportRepositoryRef - expected_version: Annotated[StrictInt | None, Field(ge=1)] - - -class DetachHandoffReportWorkspaceRequest(BaseModel): - model_config = ConfigDict( - extra="forbid", - ) - workspace_instance_id: Annotated[StrictStr, Field(max_length=256, min_length=1)] - expected_version: Annotated[StrictInt, Field(ge=1)] - - -class Schema5(StrEnum): - POWERCONTEXT_PROJECT_V1 = "powercontext.project.v1" - - -class Schema6(StrEnum): - POWERCONTEXT_WORKSTREAM_V1 = "powercontext.workstream.v1" - - -class Kind3(StrEnum): - ISSUE = "issue" - TASK = "task" - PULL_REQUEST = "pull_request" - BRANCH = "branch" - FEATURE = "feature" - RELEASE = "release" - PROGRAM = "program" - OTHER = "other" - - -class HandoffReportExternalReference(BaseModel): - model_config = ConfigDict( - extra="forbid", - ) - kind: Kind3 - provider: Annotated[StrictStr, Field(max_length=64, min_length=1)] - external_id: Annotated[StrictStr, Field(max_length=256, min_length=1)] - url: Annotated[StrictStr | None, Field(max_length=2048)] - - -class ReportLocale(StrEnum): - ZH_CN = "zh-CN" - EN = "en" - - class ReportFormat(StrEnum): JSON = "json" MARKDOWN = "markdown" -class ReportCatalogState(StrEnum): - INCLUDED = "included" - ARCHIVED = "archived" - - -class WorkstreamKind(StrEnum): - FEATURE = "feature" - BUG = "bug" - REFACTOR = "refactor" - OPERATIONS = "operations" - RESEARCH = "research" - OTHER = "other" - - class HealthResponse(BaseModel): model_config = ConfigDict( extra="forbid", @@ -988,22 +927,34 @@ class RecallTokenStatistics(BaseModel): daily: Annotated[list[RecallTokenDay], Field(max_length=30)] -class ScopedStats(BaseModel): +class ScopeStats(BaseModel): model_config = ConfigDict( extra="forbid", ) scope_id: StrictStr + inventory: InventoryStatistics + usage: UsageStatistics + recall: RecallTokenStatistics + + +class ScopedStats(BaseModel): + model_config = ConfigDict( + extra="forbid", + ) + selection: ScopeSelection + scope_ids: list[StrictStr] as_of: AwareDatetime inventory: InventoryStatistics usage: UsageStatistics recall: RecallTokenStatistics + by_scope: list[ScopeStats] class GetStatsRequest(BaseModel): model_config = ConfigDict( extra="forbid", ) - scope_id: Annotated[StrictStr, Field(max_length=256, min_length=1, pattern=".*\\S.*")] + selection: ScopeSelection period: StatsPeriod = StatsPeriod.FIELD_30D @@ -1153,51 +1104,13 @@ class GetMemoryEntryRequest(BaseModel): citation: MemoryCitation -class CreateHandoffReportProjectRequest(BaseModel): - model_config = ConfigDict( - extra="forbid", - ) - project_key: Annotated[StrictStr, Field(max_length=64, min_length=1)] - title: Annotated[StrictStr, Field(max_length=256, min_length=1)] - description: Annotated[StrictStr | None, Field(max_length=2000)] = None - default_locale: ReportLocale = ReportLocale.ZH_CN - timezone: Annotated[StrictStr, Field(max_length=256, min_length=1)] = "UTC" - - -class RegisterHandoffReportWorkstreamRequest(BaseModel): - model_config = ConfigDict( - extra="forbid", - ) - project_id: Annotated[StrictStr, Field(max_length=256, min_length=1)] - scope_id: Annotated[StrictStr, Field(max_length=256, min_length=1)] - key: Annotated[StrictStr | None, Field(max_length=64, min_length=1)] = None - title: Annotated[StrictStr, Field(max_length=256, min_length=1)] - kind: WorkstreamKind - catalog_state: ReportCatalogState = ReportCatalogState.INCLUDED - external_refs: Annotated[list[HandoffReportExternalReference], Field(max_length=32, validate_default=True)] = [] - labels: Annotated[list[Label], Field(max_length=32, validate_default=True)] = [] - - class GetHandoffReportRequest(BaseModel): model_config = ConfigDict( extra="forbid", ) - scope_id: Annotated[StrictStr, Field(max_length=256, min_length=1)] - project_id: Annotated[ - StrictStr | None, - Field( - deprecated=True, - description="Retained for wire compatibility and ignored when generating a scope report.", - max_length=256, - min_length=1, - ), - ] = None - locale: ReportLocale | None = None - include_evidence_checks: StrictBool = True - format: ReportFormat = ReportFormat.MARKDOWN - include_archived: StrictBool = False + selection: ScopeSelection + format: ReportFormat = ReportFormat.JSON download: StrictBool = False - period: HandoffReportPeriodRequest | None = None class HandoffReportResponse(BaseModel): @@ -1211,112 +1124,6 @@ class HandoffReportResponse(BaseModel): report_digest: Annotated[StrictStr, Field(pattern="^sha256:[0-9a-f]{64}$")] -class RecordHandoffReportActivityRequest(BaseModel): - model_config = ConfigDict( - extra="forbid", - ) - project_id: Annotated[StrictStr, Field(max_length=256, min_length=1)] - scope_id: Annotated[StrictStr | None, Field(max_length=256, min_length=1)] = None - source: ReportActivitySource - source_event_id: Annotated[StrictStr, Field(max_length=256, min_length=1)] - source_ref: HandoffReportExternalReference | None = None - occurred_at: AwareDatetime | None = None - time_basis: ReportTimeBasis - title: Annotated[StrictStr | None, Field(max_length=256, min_length=1)] = None - summary: Annotated[StrictStr | None, Field(max_length=2000, min_length=1)] = None - agent: HandoffReportActivityAgent | None = None - session_id: Annotated[StrictStr | None, Field(max_length=256, min_length=1)] = None - vcs_context: HandoffReportActivityVcsContext | None = None - evidence_refs: Annotated[list[HandoffReportExternalReference], Field(max_length=32, validate_default=True)] = [] - - -class HandoffReportActivity(BaseModel): - model_config = ConfigDict( - extra="forbid", - ) - schema_: Annotated[Schema3, Field(alias="schema")] - event_id: Annotated[StrictStr, Field(max_length=256, min_length=1)] - project_id: Annotated[StrictStr, Field(max_length=256, min_length=1)] - scope_id: Annotated[StrictStr | None, Field(max_length=256, min_length=1)] - source: ReportActivitySource - source_event_id: Annotated[StrictStr, Field(max_length=256, min_length=1)] - source_ref: Annotated[HandoffReportExternalReference | None, Field(...)] - occurred_at: Annotated[AwareDatetime | None, Field(...)] - observed_at: AwareDatetime - time_basis: ReportTimeBasis - title: Annotated[StrictStr | None, Field(max_length=256, min_length=1)] - summary: Annotated[StrictStr | None, Field(max_length=2000, min_length=1)] - agent: Annotated[HandoffReportActivityAgent | None, Field(...)] - session_id: Annotated[StrictStr | None, Field(max_length=256, min_length=1)] - vcs_context: Annotated[HandoffReportActivityVcsContext | None, Field(...)] - evidence_refs: Annotated[list[HandoffReportExternalReference], Field(max_length=32)] - trust: Trust4 - - -class StoredHandoffReportActivity(BaseModel): - model_config = ConfigDict( - extra="forbid", - ) - cursor: Annotated[StrictInt, Field(ge=1)] - event: HandoffReportActivity - - -class HandoffReportActivityPage(BaseModel): - model_config = ConfigDict( - extra="forbid", - ) - items: Annotated[list[HandoffReportActivity], Field(max_length=100)] - next_cursor: Annotated[StrictInt | None, Field(ge=1)] - high_watermark: Annotated[StrictInt, Field(ge=0)] - - -class ProjectDescriptor(BaseModel): - model_config = ConfigDict( - extra="forbid", - ) - schema_: Annotated[Schema5, Field(alias="schema")] - project_id: Annotated[StrictStr, Field(max_length=256, min_length=1)] - project_key: Annotated[StrictStr, Field(max_length=64, min_length=1)] - title: Annotated[StrictStr, Field(max_length=256, min_length=1)] - description: Annotated[StrictStr | None, Field(max_length=2000)] - default_locale: ReportLocale - timezone: Annotated[StrictStr, Field(max_length=256, min_length=1)] - catalog_state: ReportCatalogState - version: Annotated[StrictInt, Field(ge=1)] - - -class ProjectPage(BaseModel): - model_config = ConfigDict( - extra="forbid", - ) - items: Annotated[list[ProjectDescriptor], Field(max_length=100)] - next_cursor: Annotated[StrictStr | None, Field(...)] - - -class WorkstreamDescriptor(BaseModel): - model_config = ConfigDict( - extra="forbid", - ) - schema_: Annotated[Schema6, Field(alias="schema")] - scope_id: Annotated[StrictStr, Field(max_length=256, min_length=1)] - project_id: Annotated[StrictStr, Field(max_length=256, min_length=1)] - key: Annotated[StrictStr | None, Field(max_length=64)] - title: Annotated[StrictStr, Field(max_length=256, min_length=1)] - kind: WorkstreamKind - catalog_state: ReportCatalogState - external_refs: Annotated[list[HandoffReportExternalReference], Field(max_length=32)] - labels: Annotated[list[Label], Field(max_length=32)] - version: Annotated[StrictInt, Field(ge=1)] - - -class WorkstreamPage(BaseModel): - model_config = ConfigDict( - extra="forbid", - ) - items: Annotated[list[WorkstreamDescriptor], Field(max_length=100)] - next_cursor: Annotated[StrictStr | None, Field(...)] - - class ListArtifactCandidatesRequest(BaseModel): model_config = ConfigDict( extra="forbid", @@ -1652,22 +1459,6 @@ class SkillArtifact(BaseModel): artifact_refs: list[ArtifactReference] -class UpdateHandoffReportProjectRequest(BaseModel): - model_config = ConfigDict( - extra="forbid", - ) - project: ProjectDescriptor - expected_version: Annotated[StrictInt, Field(ge=1)] - - -class UpdateHandoffReportWorkstreamRequest(BaseModel): - model_config = ConfigDict( - extra="forbid", - ) - workstream: WorkstreamDescriptor - expected_version: Annotated[StrictInt, Field(ge=1)] - - class ListMemoryChangesResponse(BaseModel): model_config = ConfigDict( extra="forbid", diff --git a/src/powercontext/http/_generated/operations.py b/src/powercontext/http/_generated/operations.py index 2044f5352..3f7c1b235 100644 --- a/src/powercontext/http/_generated/operations.py +++ b/src/powercontext/http/_generated/operations.py @@ -12,16 +12,17 @@ ApproveArtifactCandidateRequest, ArtifactCandidate, ArtifactCandidatePage, - AttachHandoffReportWorkspaceRequest, + ArtifactPublication, Capabilities, CaptureContentSourceRequest, CaptureContentSourceResponse, + ClearScopeBindingRequest, + ClearScopeBindingResponse, CommitHandoffRequest, CommittedHandoff, ContinueHandoffRequest, - CreateHandoffReportProjectRequest, + CreateScopeRequest, CreateWorkContractRequest, - DetachHandoffReportWorkspaceRequest, ExperienceArtifact, ExternalSkillResolution, FinalizeHandoffRequest, @@ -32,9 +33,7 @@ GenerateSkillRequest, GetArtifactCandidateRequest, GetExperienceRequest, - GetHandoffReportProjectRequest, GetHandoffReportRequest, - GetHandoffReportWorkspaceRequest, GetMemoryEntryRequest, GetSkillRequest, GetStatsRequest, @@ -42,20 +41,13 @@ HandoffActivation, HandoffCurrentWorkRequest, HandoffDraft, - HandoffReportActivityPage, HandoffReportResponse, - HandoffReportWorkspaceBinding, HandoffResolution, HealthResponse, ImportExternalSkillRequest, - KnownHandoffScopePage, ListArtifactCandidatesRequest, ListExternalSkillsRequest, ListExternalSkillsResponse, - ListHandoffReportActivitiesRequest, - ListHandoffReportKnownScopesRequest, - ListHandoffReportProjectsRequest, - ListHandoffReportWorkstreamsRequest, ListMemoryChangesRequest, ListMemoryChangesResponse, ListMemoryEntriesRequest, @@ -67,34 +59,32 @@ PreparedHandoff, PreparedWorkHandoff, PrepareHandoffRequest, - ProjectDescriptor, - ProjectPage, ProposeExperienceRequest, ProposeSkillRequest, - PurgeHandoffReportActivitiesRequest, - PurgeHandoffReportActivitiesResponse, + PublishArtifactRequest, ReadinessResponse, - RecordHandoffReportActivityRequest, RecordTaskOutcomeRequest, - RegisterHandoffReportWorkstreamRequest, RejectArtifactCandidateRequest, RememberMemoryRequest, ResolveExternalSkillRequest, + ResolveScopeBindingRequest, + ResolveScopeSelectionRequest, RetireMemoryEntryRequest, ReviseArtifactCandidateRequest, ReviseMemoryEntryRequest, ScanExternalSkillsRequest, ScanExternalSkillsResponse, + ScopeBinding, + ScopeDescriptor, ScopedStats, + ScopePage, SearchMemoryRequest, SearchMemoryResponse, + SetDefaultScopeRequest, + SetScopeBindingRequest, SkillArtifact, - StoredHandoffReportActivity, - UpdateHandoffReportProjectRequest, - UpdateHandoffReportWorkstreamRequest, + UpdateScopeRequest, WorkSourceReceipt, - WorkstreamDescriptor, - WorkstreamPage, ) OPENAPI_VERSION = "3.0.3" @@ -112,10 +102,12 @@ class Operation(BaseModel, Generic[RequestT, ResponseT]): operation_id: str request_type: type[RequestT] | None request_location: Literal["body", "query"] | None + path_parameters: tuple[str, ...] response_type: type[ResponseT] success_status: int summary: str tags: tuple[str, ...] + scope_mode: Literal["none", "current", "selection"] responses: dict[int | str, dict[str, JsonValue]] @@ -125,10 +117,12 @@ class Operation(BaseModel, Generic[RequestT, ResponseT]): operation_id="get_liveness", request_type=None, request_location=None, + path_parameters=(), response_type=HealthResponse, success_status=200, summary="Get process liveness", tags=("health",), + scope_mode="none", responses={ 200: { "description": "The API process is alive.", @@ -143,10 +137,12 @@ class Operation(BaseModel, Generic[RequestT, ResponseT]): operation_id="get_readiness", request_type=None, request_location=None, + path_parameters=(), response_type=ReadinessResponse, success_status=200, summary="Get deployment readiness", tags=("health",), + scope_mode="none", responses={ 200: { "description": "Required Server bindings are ready; optional capabilities may be degraded.", @@ -165,10 +161,12 @@ class Operation(BaseModel, Generic[RequestT, ResponseT]): operation_id="get_capabilities", request_type=None, request_location=None, + path_parameters=(), response_type=Capabilities, success_status=200, summary="Get runtime capabilities", tags=("capabilities",), + scope_mode="none", responses={ 200: { "description": "Behavior enabled by the assembled runtime.", @@ -178,16 +176,236 @@ class Operation(BaseModel, Generic[RequestT, ResponseT]): }, ) +LIST_SCOPES = Operation[None, ScopePage]( + method="GET", + path="/v1/scopes", + operation_id="list_scopes", + request_type=None, + request_location=None, + path_parameters=(), + response_type=ScopePage, + success_status=200, + summary="List observable Scopes", + tags=("scopes",), + scope_mode="none", + responses={ + 200: {"description": "Durable Scope metadata in deterministic identity order."}, + 401: {"$ref": "#/components/responses/Unauthorized"}, + 503: {"$ref": "#/components/responses/Unavailable"}, + }, +) + +CREATE_SCOPE = Operation[CreateScopeRequest, ScopeDescriptor]( + method="POST", + path="/v1/scopes", + operation_id="create_scope", + request_type=CreateScopeRequest, + request_location="body", + path_parameters=(), + response_type=ScopeDescriptor, + success_status=201, + summary="Create an independent Scope boundary", + tags=("scopes",), + scope_mode="none", + responses={ + 201: {"description": "The durable Scope descriptor."}, + 404: {"$ref": "#/components/responses/NotFound"}, + 409: {"$ref": "#/components/responses/Conflict"}, + 401: {"$ref": "#/components/responses/Unauthorized"}, + 422: {"$ref": "#/components/responses/InvalidRequest"}, + }, +) + +PUBLISH_ARTIFACT = Operation[PublishArtifactRequest, ArtifactPublication]( + method="POST", + path="/v1/artifact-publications", + operation_id="publish_artifact", + request_type=PublishArtifactRequest, + request_location="body", + path_parameters=(), + response_type=ArtifactPublication, + success_status=201, + summary="Publish one exact Artifact revision into another Scope", + tags=("scopes",), + scope_mode="none", + responses={ + 201: {"description": "Independent target Artifact and its exact source provenance."}, + 404: {"$ref": "#/components/responses/NotFound"}, + 409: {"$ref": "#/components/responses/Conflict"}, + 401: {"$ref": "#/components/responses/Unauthorized"}, + 422: {"$ref": "#/components/responses/InvalidRequest"}, + }, +) + +GET_SCOPE = Operation[None, ScopeDescriptor]( + method="GET", + path="/v1/scopes/{scope_id}", + operation_id="get_scope", + request_type=None, + request_location=None, + path_parameters=("scope_id",), + response_type=ScopeDescriptor, + success_status=200, + summary="Get one Scope descriptor", + tags=("scopes",), + scope_mode="none", + responses={ + 200: {"description": "The exact Scope descriptor."}, + 404: {"$ref": "#/components/responses/NotFound"}, + 401: {"$ref": "#/components/responses/Unauthorized"}, + }, +) + +UPDATE_SCOPE = Operation[UpdateScopeRequest, ScopeDescriptor]( + method="PUT", + path="/v1/scopes/{scope_id}", + operation_id="update_scope", + request_type=UpdateScopeRequest, + request_location="body", + path_parameters=("scope_id",), + response_type=ScopeDescriptor, + success_status=200, + summary="Replace mutable Scope metadata and relationships", + tags=("scopes",), + scope_mode="none", + responses={ + 200: {"description": "The updated Scope descriptor."}, + 404: {"$ref": "#/components/responses/NotFound"}, + 409: {"$ref": "#/components/responses/Conflict"}, + 401: {"$ref": "#/components/responses/Unauthorized"}, + 422: {"$ref": "#/components/responses/InvalidRequest"}, + }, +) + +GET_DEFAULT_SCOPE = Operation[None, ScopeDescriptor]( + method="GET", + path="/v1/scopes/default", + operation_id="get_default_scope", + request_type=None, + request_location=None, + path_parameters=(), + response_type=ScopeDescriptor, + success_status=200, + summary="Get the default Scope binding target", + tags=("scopes",), + scope_mode="none", + responses={ + 200: {"description": "The ordinary Scope selected by the host default pointer."}, + 404: {"$ref": "#/components/responses/NotFound"}, + 401: {"$ref": "#/components/responses/Unauthorized"}, + }, +) + +SET_DEFAULT_SCOPE = Operation[SetDefaultScopeRequest, ScopeDescriptor]( + method="PUT", + path="/v1/scopes/default", + operation_id="set_default_scope", + request_type=SetDefaultScopeRequest, + request_location="body", + path_parameters=(), + response_type=ScopeDescriptor, + success_status=200, + summary="Change the default Scope binding target", + tags=("scopes",), + scope_mode="none", + responses={ + 200: {"description": "The selected ordinary Scope."}, + 404: {"$ref": "#/components/responses/NotFound"}, + 401: {"$ref": "#/components/responses/Unauthorized"}, + }, +) + +RESOLVE_SCOPE_SELECTION = Operation[ResolveScopeSelectionRequest, ScopePage]( + method="POST", + path="/v1/scopes/selection/resolve", + operation_id="resolve_scope_selection", + request_type=ResolveScopeSelectionRequest, + request_location="body", + path_parameters=(), + response_type=ScopePage, + success_status=200, + summary="Resolve an observation selection to a frozen Scope set", + tags=("scopes",), + scope_mode="none", + responses={ + 200: {"description": "The selected Scope descriptors in deterministic order."}, + 404: {"$ref": "#/components/responses/NotFound"}, + 401: {"$ref": "#/components/responses/Unauthorized"}, + 422: {"$ref": "#/components/responses/InvalidRequest"}, + }, +) + +RESOLVE_SCOPE_BINDING = Operation[ResolveScopeBindingRequest, ScopeDescriptor]( + method="POST", + path="/v1/scope-bindings/resolve", + operation_id="resolve_scope_binding", + request_type=ResolveScopeBindingRequest, + request_location="body", + path_parameters=(), + response_type=ScopeDescriptor, + success_status=200, + summary="Resolve an explicit durable or default Scope binding", + tags=("scope-bindings",), + scope_mode="none", + responses={ + 200: {"description": "The resolved Scope descriptor."}, + 404: {"$ref": "#/components/responses/NotFound"}, + 401: {"$ref": "#/components/responses/Unauthorized"}, + 422: {"$ref": "#/components/responses/InvalidRequest"}, + }, +) + +SET_SCOPE_BINDING = Operation[SetScopeBindingRequest, ScopeBinding]( + method="PUT", + path="/v1/scope-bindings", + operation_id="set_scope_binding", + request_type=SetScopeBindingRequest, + request_location="body", + path_parameters=(), + response_type=ScopeBinding, + success_status=200, + summary="Persist an external identity to Scope binding", + tags=("scope-bindings",), + scope_mode="none", + responses={ + 200: {"description": "The durable external binding."}, + 404: {"$ref": "#/components/responses/NotFound"}, + 401: {"$ref": "#/components/responses/Unauthorized"}, + 422: {"$ref": "#/components/responses/InvalidRequest"}, + }, +) + +CLEAR_SCOPE_BINDING = Operation[ClearScopeBindingRequest, ClearScopeBindingResponse]( + method="POST", + path="/v1/scope-bindings/clear", + operation_id="clear_scope_binding", + request_type=ClearScopeBindingRequest, + request_location="body", + path_parameters=(), + response_type=ClearScopeBindingResponse, + success_status=200, + summary="Remove one durable external Scope binding", + tags=("scope-bindings",), + scope_mode="none", + responses={ + 200: {"description": "Whether a durable binding was removed."}, + 401: {"$ref": "#/components/responses/Unauthorized"}, + 422: {"$ref": "#/components/responses/InvalidRequest"}, + }, +) + CAPTURE_CONTENT_SOURCE = Operation[CaptureContentSourceRequest, CaptureContentSourceResponse]( method="POST", path="/v1/sources/content", operation_id="capture_content_source", request_type=CaptureContentSourceRequest, request_location="body", + path_parameters=(), response_type=CaptureContentSourceResponse, success_status=202, summary="Capture durable ContentSource evidence", tags=("sources",), + scope_mode="current", responses={ 202: { "description": "The Source is durably stored for later processing.", @@ -207,10 +425,12 @@ class Operation(BaseModel, Generic[RequestT, ResponseT]): operation_id="prepare_context", request_type=PrepareContextRequest, request_location="body", + path_parameters=(), response_type=PreparedContext, success_status=200, summary="Prepare bounded context for an Agent turn", tags=("context",), + scope_mode="current", responses={ 200: { "description": "Final context ready for direct injection, or a normal empty result.", @@ -229,10 +449,12 @@ class Operation(BaseModel, Generic[RequestT, ResponseT]): operation_id="create_work_contract", request_type=CreateWorkContractRequest, request_location="body", + path_parameters=(), response_type=WorkSourceReceipt, success_status=202, summary="Create a grounded Work Contract", tags=("work",), + scope_mode="current", responses={ 202: { "description": "The Work Contract is durably captured as exact Source evidence.", @@ -253,10 +475,12 @@ class Operation(BaseModel, Generic[RequestT, ResponseT]): operation_id="handoff_current_work", request_type=HandoffCurrentWorkRequest, request_location="body", + path_parameters=(), response_type=PreparedWorkHandoff, success_status=200, summary="Hand off current work in one high-level operation", tags=("work",), + scope_mode="current", responses={ 200: { "description": "The captured boundary and Prepared Handoff ready for explicit transfer.", @@ -277,10 +501,12 @@ class Operation(BaseModel, Generic[RequestT, ResponseT]): operation_id="acknowledge_handoff", request_type=AcknowledgeHandoffRequest, request_location="body", + path_parameters=(), response_type=HandoffAcknowledgement, success_status=200, summary="Resolve and acknowledge a Handoff", tags=("work",), + scope_mode="current", responses={ 200: { "description": "The resolved Handoff and durable receiver acknowledgement.", @@ -301,10 +527,12 @@ class Operation(BaseModel, Generic[RequestT, ResponseT]): operation_id="record_task_outcome", request_type=RecordTaskOutcomeRequest, request_location="body", + path_parameters=(), response_type=WorkSourceReceipt, success_status=202, summary="Record a completion-aware Task Outcome", tags=("work",), + scope_mode="current", responses={ 202: { "description": "The Task Outcome is durably captured for Handoff evidence and reviewed " @@ -326,10 +554,12 @@ class Operation(BaseModel, Generic[RequestT, ResponseT]): operation_id="activate_handoff", request_type=ActivateHandoffRequest, request_location="body", + path_parameters=(), response_type=HandoffActivation, success_status=200, summary="Activate Handoff generation at a Source boundary", tags=("handoff",), + scope_mode="current", responses={ 200: { "description": "A generated inspectable Draft, or an ignored boundary that was already consumed.", @@ -349,10 +579,12 @@ class Operation(BaseModel, Generic[RequestT, ResponseT]): operation_id="prepare_handoff", request_type=PrepareHandoffRequest, request_location="body", + path_parameters=(), response_type=HandoffDraft, success_status=200, summary="Generate an inspectable Handoff Draft", tags=("handoff",), + scope_mode="current", responses={ 200: { "description": "An uncommitted Draft generated from the selected exact evidence.", @@ -372,10 +604,12 @@ class Operation(BaseModel, Generic[RequestT, ResponseT]): operation_id="finalize_handoff", request_type=FinalizeHandoffRequest, request_location="body", + path_parameters=(), response_type=PreparedHandoff, success_status=200, summary="Finalize an inspected Handoff Draft", tags=("handoff",), + scope_mode="current", responses={ 200: { "description": "A temporary Handoff ready for direct transfer or explicit commit.", @@ -395,10 +629,12 @@ class Operation(BaseModel, Generic[RequestT, ResponseT]): operation_id="commit_handoff", request_type=CommitHandoffRequest, request_location="body", + path_parameters=(), response_type=CommittedHandoff, success_status=200, summary="Commit an explicit Handoff milestone", tags=("handoff",), + scope_mode="current", responses={ 200: { "description": "The committed immutable Handoff Revision.", @@ -419,10 +655,12 @@ class Operation(BaseModel, Generic[RequestT, ResponseT]): operation_id="continue_handoff", request_type=ContinueHandoffRequest, request_location="body", + path_parameters=(), response_type=HandoffResolution, success_status=200, summary="Resolve a Handoff as untrusted historical input", tags=("handoff",), + scope_mode="current", responses={ 200: { "description": "Resolved content and per-statement evidence availability.", @@ -442,10 +680,12 @@ class Operation(BaseModel, Generic[RequestT, ResponseT]): operation_id="flush_memory", request_type=FlushMemoryRequest, request_location="body", + path_parameters=(), response_type=FlushMemoryResponse, success_status=200, summary="Process the pending Source window into Memory", tags=("memory",), + scope_mode="current", responses={ 200: { "description": "The activation completed or found no pending Sources.", @@ -464,10 +704,12 @@ class Operation(BaseModel, Generic[RequestT, ResponseT]): operation_id="remember_memory", request_type=RememberMemoryRequest, request_location="body", + path_parameters=(), response_type=MemoryMutationResponse, success_status=200, summary="Remember explicit Memory content", tags=("memory",), + scope_mode="current", responses={ 200: { "description": "The explicit Memory mutation completed.", @@ -487,10 +729,12 @@ class Operation(BaseModel, Generic[RequestT, ResponseT]): operation_id="search_memory", request_type=SearchMemoryRequest, request_location="body", + path_parameters=(), response_type=SearchMemoryResponse, success_status=200, summary="Search active Memory entries", tags=("memory",), + scope_mode="current", responses={ 200: { "description": "Matching Memory entries, or an empty result when the scope has no Memory.", @@ -510,10 +754,12 @@ class Operation(BaseModel, Generic[RequestT, ResponseT]): operation_id="list_memory_entries", request_type=ListMemoryEntriesRequest, request_location="body", + path_parameters=(), response_type=ListMemoryEntriesResponse, success_status=200, summary="List Memory entries", tags=("memory",), + scope_mode="current", responses={ 200: { "description": "The selected entries from the current Memory head.", @@ -533,10 +779,12 @@ class Operation(BaseModel, Generic[RequestT, ResponseT]): operation_id="get_memory_entry", request_type=GetMemoryEntryRequest, request_location="body", + path_parameters=(), response_type=MemoryEntry, success_status=200, summary="Get an exact Memory entry version", tags=("memory",), + scope_mode="current", responses={ 200: { "description": "The exact Memory entry version.", @@ -556,10 +804,12 @@ class Operation(BaseModel, Generic[RequestT, ResponseT]): operation_id="revise_memory_entry", request_type=ReviseMemoryEntryRequest, request_location="body", + path_parameters=(), response_type=MemoryMutationResponse, success_status=200, summary="Revise an exact Memory entry", tags=("memory",), + scope_mode="current", responses={ 200: { "description": "The Memory entry revision completed.", @@ -580,10 +830,12 @@ class Operation(BaseModel, Generic[RequestT, ResponseT]): operation_id="retire_memory_entry", request_type=RetireMemoryEntryRequest, request_location="body", + path_parameters=(), response_type=MemoryMutationResponse, success_status=200, summary="Retire an exact Memory entry", tags=("memory",), + scope_mode="current", responses={ 200: { "description": "The Memory entry retirement completed.", @@ -604,10 +856,12 @@ class Operation(BaseModel, Generic[RequestT, ResponseT]): operation_id="list_memory_changes", request_type=ListMemoryChangesRequest, request_location="body", + path_parameters=(), response_type=ListMemoryChangesResponse, success_status=200, summary="List Memory Revision changes", tags=("memory",), + scope_mode="current", responses={ 200: { "description": "Compact changes through the selected Memory Revision.", @@ -627,10 +881,12 @@ class Operation(BaseModel, Generic[RequestT, ResponseT]): operation_id="propose_experience", request_type=ProposeExperienceRequest, request_location="body", + path_parameters=(), response_type=ArtifactCandidate, success_status=201, summary="Propose Experience content", tags=("experience",), + scope_mode="current", responses={ 201: { "description": "The pending Experience Candidate.", @@ -650,10 +906,12 @@ class Operation(BaseModel, Generic[RequestT, ResponseT]): operation_id="generate_experience", request_type=GenerateExperienceRequest, request_location="body", + path_parameters=(), response_type=GeneratedCandidateResponse, success_status=200, summary="Generate an Experience Candidate", tags=("experience",), + scope_mode="current", responses={ 200: { "description": "A pending Candidate or an explicit semantic no-op.", @@ -673,10 +931,12 @@ class Operation(BaseModel, Generic[RequestT, ResponseT]): operation_id="get_experience", request_type=GetExperienceRequest, request_location="body", + path_parameters=(), response_type=ExperienceArtifact, success_status=200, summary="Get an exact Experience Revision", tags=("experience",), + scope_mode="current", responses={ 200: { "description": "The exact approved Experience Revision.", @@ -696,10 +956,12 @@ class Operation(BaseModel, Generic[RequestT, ResponseT]): operation_id="propose_skill", request_type=ProposeSkillRequest, request_location="body", + path_parameters=(), response_type=ArtifactCandidate, success_status=201, summary="Propose managed Skill content", tags=("skill",), + scope_mode="current", responses={ 201: { "description": "The pending managed Skill Candidate.", @@ -719,10 +981,12 @@ class Operation(BaseModel, Generic[RequestT, ResponseT]): operation_id="generate_skill", request_type=GenerateSkillRequest, request_location="body", + path_parameters=(), response_type=GeneratedCandidateResponse, success_status=200, summary="Generate a managed Skill Candidate", tags=("skill",), + scope_mode="current", responses={ 200: { "description": "A pending Candidate or an explicit semantic no-op.", @@ -742,10 +1006,12 @@ class Operation(BaseModel, Generic[RequestT, ResponseT]): operation_id="get_skill", request_type=GetSkillRequest, request_location="body", + path_parameters=(), response_type=SkillArtifact, success_status=200, summary="Get an exact managed Skill Revision", tags=("skill",), + scope_mode="current", responses={ 200: { "description": "The exact approved managed Skill Revision.", @@ -765,10 +1031,12 @@ class Operation(BaseModel, Generic[RequestT, ResponseT]): operation_id="scan_external_skills", request_type=ScanExternalSkillsRequest, request_location="body", + path_parameters=(), response_type=ScanExternalSkillsResponse, success_status=200, summary="Scan configured external Skill roots", tags=("skill",), + scope_mode="current", responses={ 200: { "description": "The rebuildable provider snapshot.", @@ -787,10 +1055,12 @@ class Operation(BaseModel, Generic[RequestT, ResponseT]): operation_id="list_external_skills", request_type=ListExternalSkillsRequest, request_location="body", + path_parameters=(), response_type=ListExternalSkillsResponse, success_status=200, summary="List external Skills visible on this host", tags=("skill",), + scope_mode="current", responses={ 200: { "description": "External Skills resolved against the current Agent, host, scope, and fingerprint.", @@ -809,10 +1079,12 @@ class Operation(BaseModel, Generic[RequestT, ResponseT]): operation_id="resolve_external_skill", request_type=ResolveExternalSkillRequest, request_location="body", + path_parameters=(), response_type=ExternalSkillResolution, success_status=200, summary="Resolve an exact external Skill fingerprint", tags=("skill",), + scope_mode="current", responses={ 200: { "description": "The live exact-resolution result, which may be unavailable.", @@ -832,10 +1104,12 @@ class Operation(BaseModel, Generic[RequestT, ResponseT]): operation_id="import_external_skill", request_type=ImportExternalSkillRequest, request_location="body", + path_parameters=(), response_type=GeneratedCandidateResponse, success_status=200, summary="Import or fork an external Skill into Review", tags=("skill",), + scope_mode="current", responses={ 200: { "description": "A pending managed Skill Candidate or an explicit semantic no-op.", @@ -856,10 +1130,12 @@ class Operation(BaseModel, Generic[RequestT, ResponseT]): operation_id="list_artifact_candidates", request_type=ListArtifactCandidatesRequest, request_location="body", + path_parameters=(), response_type=ArtifactCandidatePage, success_status=200, summary="List Artifact Candidates", tags=("review",), + scope_mode="current", responses={ 200: { "description": "The selected current Candidate heads.", @@ -878,10 +1154,12 @@ class Operation(BaseModel, Generic[RequestT, ResponseT]): operation_id="get_artifact_candidate", request_type=GetArtifactCandidateRequest, request_location="body", + path_parameters=(), response_type=ArtifactCandidate, success_status=200, summary="Get an Artifact Candidate", tags=("review",), + scope_mode="current", responses={ 200: { "description": "The current Candidate head.", @@ -901,10 +1179,12 @@ class Operation(BaseModel, Generic[RequestT, ResponseT]): operation_id="approve_artifact_candidate", request_type=ApproveArtifactCandidateRequest, request_location="body", + path_parameters=(), response_type=ArtifactCandidate, success_status=200, summary="Approve an Artifact Candidate", tags=("review",), + scope_mode="current", responses={ 200: { "description": "The approved Candidate and exact result Artifact.", @@ -925,10 +1205,12 @@ class Operation(BaseModel, Generic[RequestT, ResponseT]): operation_id="reject_artifact_candidate", request_type=RejectArtifactCandidateRequest, request_location="body", + path_parameters=(), response_type=ArtifactCandidate, success_status=200, summary="Reject an Artifact Candidate", tags=("review",), + scope_mode="current", responses={ 200: { "description": "The rejected Candidate.", @@ -949,10 +1231,12 @@ class Operation(BaseModel, Generic[RequestT, ResponseT]): operation_id="revise_artifact_candidate", request_type=ReviseArtifactCandidateRequest, request_location="body", + path_parameters=(), response_type=ArtifactCandidate, success_status=200, summary="Revise an Artifact Candidate", tags=("review",), + scope_mode="current", responses={ 200: { "description": "The next pending Candidate version.", @@ -968,18 +1252,20 @@ class Operation(BaseModel, Generic[RequestT, ResponseT]): ) GET_STATS = Operation[GetStatsRequest, ScopedStats]( - method="GET", + method="POST", path="/v1/stats", operation_id="get_stats", request_type=GetStatsRequest, - request_location="query", + request_location="body", + path_parameters=(), response_type=ScopedStats, success_status=200, - summary="Get scoped product statistics", + summary="Aggregate product statistics over a Scope selection", tags=("stats",), + scope_mode="selection", responses={ 200: { - "description": "Current inventory, model usage, and recall token estimates for the scope.", + "description": "Current inventory, model usage, and recall token estimates for the frozen Scope set.", "headers": { "X-PowerContext-Request-ID": {"$ref": "#/components/headers/RequestId"}, "Cache-Control": { @@ -995,193 +1281,18 @@ class Operation(BaseModel, Generic[RequestT, ResponseT]): }, ) -CREATE_HANDOFF_REPORT_PROJECT = Operation[CreateHandoffReportProjectRequest, ProjectDescriptor]( - method="POST", - path="/v1/handoff-reports/projects/create", - operation_id="create_handoff_report_project", - request_type=CreateHandoffReportProjectRequest, - request_location="body", - response_type=ProjectDescriptor, - success_status=201, - summary="Create a Handoff Report Project", - tags=("handoff-reports",), - responses={ - 201: { - "description": "The created Report Project.", - "headers": {"X-PowerContext-Request-ID": {"$ref": "#/components/headers/RequestId"}}, - }, - 409: {"$ref": "#/components/responses/Conflict"}, - 401: {"$ref": "#/components/responses/Unauthorized"}, - 422: {"$ref": "#/components/responses/InvalidRequest"}, - 500: {"$ref": "#/components/responses/InternalError"}, - }, -) - -LIST_HANDOFF_REPORT_PROJECTS = Operation[ListHandoffReportProjectsRequest, ProjectPage]( - method="POST", - path="/v1/handoff-reports/projects/list", - operation_id="list_handoff_report_projects", - request_type=ListHandoffReportProjectsRequest, - request_location="body", - response_type=ProjectPage, - success_status=200, - summary="List Handoff Report Projects", - tags=("handoff-reports",), - responses={ - 200: { - "description": "A cursor-paginated page of Report Projects.", - "headers": {"X-PowerContext-Request-ID": {"$ref": "#/components/headers/RequestId"}}, - }, - 401: {"$ref": "#/components/responses/Unauthorized"}, - 422: {"$ref": "#/components/responses/InvalidRequest"}, - 500: {"$ref": "#/components/responses/InternalError"}, - }, -) - -LIST_HANDOFF_REPORT_KNOWN_SCOPES = Operation[ListHandoffReportKnownScopesRequest, KnownHandoffScopePage]( - method="POST", - path="/v1/handoff-reports/scopes/list-known", - operation_id="list_handoff_report_known_scopes", - request_type=ListHandoffReportKnownScopesRequest, - request_location="body", - response_type=KnownHandoffScopePage, - success_status=200, - summary="List scopes that contain a committed Handoff", - tags=("handoff-reports",), - responses={ - 200: { - "description": "A cursor-paginated page of scopes that can be rendered as Handoff Reports.", - "headers": {"X-PowerContext-Request-ID": {"$ref": "#/components/headers/RequestId"}}, - }, - 401: {"$ref": "#/components/responses/Unauthorized"}, - 422: {"$ref": "#/components/responses/InvalidRequest"}, - 500: {"$ref": "#/components/responses/InternalError"}, - }, -) - -GET_HANDOFF_REPORT_PROJECT = Operation[GetHandoffReportProjectRequest, ProjectDescriptor]( - method="POST", - path="/v1/handoff-reports/projects/get", - operation_id="get_handoff_report_project", - request_type=GetHandoffReportProjectRequest, - request_location="body", - response_type=ProjectDescriptor, - success_status=200, - summary="Get a Handoff Report Project", - tags=("handoff-reports",), - responses={ - 200: { - "description": "The exact current Report Project descriptor.", - "headers": {"X-PowerContext-Request-ID": {"$ref": "#/components/headers/RequestId"}}, - }, - 404: {"$ref": "#/components/responses/NotFound"}, - 401: {"$ref": "#/components/responses/Unauthorized"}, - 422: {"$ref": "#/components/responses/InvalidRequest"}, - 500: {"$ref": "#/components/responses/InternalError"}, - }, -) - -UPDATE_HANDOFF_REPORT_PROJECT = Operation[UpdateHandoffReportProjectRequest, ProjectDescriptor]( - method="POST", - path="/v1/handoff-reports/projects/update", - operation_id="update_handoff_report_project", - request_type=UpdateHandoffReportProjectRequest, - request_location="body", - response_type=ProjectDescriptor, - success_status=200, - summary="Update a Handoff Report Project", - tags=("handoff-reports",), - responses={ - 200: { - "description": "The updated Report Project descriptor.", - "headers": {"X-PowerContext-Request-ID": {"$ref": "#/components/headers/RequestId"}}, - }, - 404: {"$ref": "#/components/responses/NotFound"}, - 409: {"$ref": "#/components/responses/Conflict"}, - 401: {"$ref": "#/components/responses/Unauthorized"}, - 422: {"$ref": "#/components/responses/InvalidRequest"}, - 500: {"$ref": "#/components/responses/InternalError"}, - }, -) - -REGISTER_HANDOFF_REPORT_WORKSTREAM = Operation[RegisterHandoffReportWorkstreamRequest, WorkstreamDescriptor]( - method="POST", - path="/v1/handoff-reports/workstreams/register", - operation_id="register_handoff_report_workstream", - request_type=RegisterHandoffReportWorkstreamRequest, - request_location="body", - response_type=WorkstreamDescriptor, - success_status=201, - summary="Register a Handoff Report Workstream", - tags=("handoff-reports",), - responses={ - 201: { - "description": "The registered Report Workstream.", - "headers": {"X-PowerContext-Request-ID": {"$ref": "#/components/headers/RequestId"}}, - }, - 404: {"$ref": "#/components/responses/NotFound"}, - 409: {"$ref": "#/components/responses/Conflict"}, - 401: {"$ref": "#/components/responses/Unauthorized"}, - 422: {"$ref": "#/components/responses/InvalidRequest"}, - 500: {"$ref": "#/components/responses/InternalError"}, - }, -) - -LIST_HANDOFF_REPORT_WORKSTREAMS = Operation[ListHandoffReportWorkstreamsRequest, WorkstreamPage]( - method="POST", - path="/v1/handoff-reports/workstreams/list", - operation_id="list_handoff_report_workstreams", - request_type=ListHandoffReportWorkstreamsRequest, - request_location="body", - response_type=WorkstreamPage, - success_status=200, - summary="List Handoff Report Workstreams", - tags=("handoff-reports",), - responses={ - 200: { - "description": "A cursor-paginated page of Report Workstreams.", - "headers": {"X-PowerContext-Request-ID": {"$ref": "#/components/headers/RequestId"}}, - }, - 404: {"$ref": "#/components/responses/NotFound"}, - 401: {"$ref": "#/components/responses/Unauthorized"}, - 422: {"$ref": "#/components/responses/InvalidRequest"}, - 500: {"$ref": "#/components/responses/InternalError"}, - }, -) - -UPDATE_HANDOFF_REPORT_WORKSTREAM = Operation[UpdateHandoffReportWorkstreamRequest, WorkstreamDescriptor]( - method="POST", - path="/v1/handoff-reports/workstreams/update", - operation_id="update_handoff_report_workstream", - request_type=UpdateHandoffReportWorkstreamRequest, - request_location="body", - response_type=WorkstreamDescriptor, - success_status=200, - summary="Update a Handoff Report Workstream", - tags=("handoff-reports",), - responses={ - 200: { - "description": "The updated Report Workstream descriptor.", - "headers": {"X-PowerContext-Request-ID": {"$ref": "#/components/headers/RequestId"}}, - }, - 404: {"$ref": "#/components/responses/NotFound"}, - 409: {"$ref": "#/components/responses/Conflict"}, - 401: {"$ref": "#/components/responses/Unauthorized"}, - 422: {"$ref": "#/components/responses/InvalidRequest"}, - 500: {"$ref": "#/components/responses/InternalError"}, - }, -) - GET_HANDOFF_REPORT = Operation[GetHandoffReportRequest, HandoffReportResponse]( method="POST", path="/v1/handoff-reports/get", operation_id="get_handoff_report", request_type=GetHandoffReportRequest, request_location="body", + path_parameters=(), response_type=HandoffReportResponse, success_status=200, summary="Generate a Handoff Report", tags=("handoff-reports",), + scope_mode="selection", responses={ 200: { "description": "A canonical JSON report, optionally accompanied by Markdown.", @@ -1213,138 +1324,3 @@ class Operation(BaseModel, Generic[RequestT, ResponseT]): 500: {"$ref": "#/components/responses/InternalError"}, }, ) - -RECORD_HANDOFF_REPORT_ACTIVITY = Operation[RecordHandoffReportActivityRequest, StoredHandoffReportActivity]( - method="POST", - path="/v1/handoff-reports/activities/record", - operation_id="record_handoff_report_activity", - request_type=RecordHandoffReportActivityRequest, - request_location="body", - response_type=StoredHandoffReportActivity, - success_status=201, - summary="Record a Handoff Report Activity", - tags=("handoff-reports",), - responses={ - 201: { - "description": "The idempotently recorded Report Activity.", - "headers": {"X-PowerContext-Request-ID": {"$ref": "#/components/headers/RequestId"}}, - }, - 404: {"$ref": "#/components/responses/NotFound"}, - 409: {"$ref": "#/components/responses/Conflict"}, - 401: {"$ref": "#/components/responses/Unauthorized"}, - 422: {"$ref": "#/components/responses/InvalidRequest"}, - 500: {"$ref": "#/components/responses/InternalError"}, - }, -) - -LIST_HANDOFF_REPORT_ACTIVITIES = Operation[ListHandoffReportActivitiesRequest, HandoffReportActivityPage]( - method="POST", - path="/v1/handoff-reports/activities/list", - operation_id="list_handoff_report_activities", - request_type=ListHandoffReportActivitiesRequest, - request_location="body", - response_type=HandoffReportActivityPage, - success_status=200, - summary="List Handoff Report Activities", - tags=("handoff-reports",), - responses={ - 200: { - "description": "A frozen cursor page of Report Activities.", - "headers": {"X-PowerContext-Request-ID": {"$ref": "#/components/headers/RequestId"}}, - }, - 404: {"$ref": "#/components/responses/NotFound"}, - 401: {"$ref": "#/components/responses/Unauthorized"}, - 422: {"$ref": "#/components/responses/InvalidRequest"}, - 500: {"$ref": "#/components/responses/InternalError"}, - }, -) - -PURGE_HANDOFF_REPORT_ACTIVITIES = Operation[PurgeHandoffReportActivitiesRequest, PurgeHandoffReportActivitiesResponse]( - method="POST", - path="/v1/handoff-reports/activities/purge", - operation_id="purge_handoff_report_activities", - request_type=PurgeHandoffReportActivitiesRequest, - request_location="body", - response_type=PurgeHandoffReportActivitiesResponse, - success_status=200, - summary="Purge Handoff Report Activities", - tags=("handoff-reports",), - responses={ - 200: { - "description": "The number of deleted Report-owned Activity rows.", - "headers": {"X-PowerContext-Request-ID": {"$ref": "#/components/headers/RequestId"}}, - }, - 404: {"$ref": "#/components/responses/NotFound"}, - 401: {"$ref": "#/components/responses/Unauthorized"}, - 422: {"$ref": "#/components/responses/InvalidRequest"}, - 500: {"$ref": "#/components/responses/InternalError"}, - }, -) - -GET_HANDOFF_REPORT_WORKSPACE = Operation[GetHandoffReportWorkspaceRequest, HandoffReportWorkspaceBinding]( - method="POST", - path="/v1/handoff-reports/workspace-bindings/get", - operation_id="get_handoff_report_workspace", - request_type=GetHandoffReportWorkspaceRequest, - request_location="body", - response_type=HandoffReportWorkspaceBinding, - success_status=200, - summary="Get a Handoff Report Workspace Binding", - tags=("handoff-reports",), - responses={ - 200: { - "description": "The confirmed Workspace binding.", - "headers": {"X-PowerContext-Request-ID": {"$ref": "#/components/headers/RequestId"}}, - }, - 404: {"$ref": "#/components/responses/NotFound"}, - 401: {"$ref": "#/components/responses/Unauthorized"}, - 422: {"$ref": "#/components/responses/InvalidRequest"}, - 500: {"$ref": "#/components/responses/InternalError"}, - }, -) - -ATTACH_HANDOFF_REPORT_WORKSPACE = Operation[AttachHandoffReportWorkspaceRequest, HandoffReportWorkspaceBinding]( - method="POST", - path="/v1/handoff-reports/workspace-bindings/attach", - operation_id="attach_handoff_report_workspace", - request_type=AttachHandoffReportWorkspaceRequest, - request_location="body", - response_type=HandoffReportWorkspaceBinding, - success_status=200, - summary="Attach a Handoff Report Workspace Binding", - tags=("handoff-reports",), - responses={ - 200: { - "description": "The confirmed Workspace binding.", - "headers": {"X-PowerContext-Request-ID": {"$ref": "#/components/headers/RequestId"}}, - }, - 404: {"$ref": "#/components/responses/NotFound"}, - 409: {"$ref": "#/components/responses/Conflict"}, - 401: {"$ref": "#/components/responses/Unauthorized"}, - 422: {"$ref": "#/components/responses/InvalidRequest"}, - 500: {"$ref": "#/components/responses/InternalError"}, - }, -) - -DETACH_HANDOFF_REPORT_WORKSPACE = Operation[DetachHandoffReportWorkspaceRequest, HandoffReportWorkspaceBinding]( - method="POST", - path="/v1/handoff-reports/workspace-bindings/detach", - operation_id="detach_handoff_report_workspace", - request_type=DetachHandoffReportWorkspaceRequest, - request_location="body", - response_type=HandoffReportWorkspaceBinding, - success_status=200, - summary="Detach a Handoff Report Workspace Binding", - tags=("handoff-reports",), - responses={ - 200: { - "description": "The detached Workspace binding record.", - "headers": {"X-PowerContext-Request-ID": {"$ref": "#/components/headers/RequestId"}}, - }, - 404: {"$ref": "#/components/responses/NotFound"}, - 409: {"$ref": "#/components/responses/Conflict"}, - 401: {"$ref": "#/components/responses/Unauthorized"}, - 422: {"$ref": "#/components/responses/InvalidRequest"}, - 500: {"$ref": "#/components/responses/InternalError"}, - }, -) diff --git a/src/powercontext/http/_generated/schema.py b/src/powercontext/http/_generated/schema.py index be81ba103..c7137c08d 100644 --- a/src/powercontext/http/_generated/schema.py +++ b/src/powercontext/http/_generated/schema.py @@ -60,6 +60,238 @@ }, } }, + "/v1/scopes": { + "get": { + "tags": ["scopes"], + "summary": "List observable Scopes", + "operationId": "list_scopes", + "responses": { + "200": { + "description": "Durable Scope metadata in deterministic identity order.", + "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ScopePage"}}}, + }, + "401": {"$ref": "#/components/responses/Unauthorized"}, + "503": {"$ref": "#/components/responses/Unavailable"}, + }, + }, + "post": { + "tags": ["scopes"], + "summary": "Create an independent Scope boundary", + "operationId": "create_scope", + "requestBody": { + "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CreateScopeRequest"}}}, + "required": True, + }, + "responses": { + "201": { + "description": "The durable Scope descriptor.", + "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ScopeDescriptor"}}}, + }, + "404": {"$ref": "#/components/responses/NotFound"}, + "409": {"$ref": "#/components/responses/Conflict"}, + "401": {"$ref": "#/components/responses/Unauthorized"}, + "422": {"$ref": "#/components/responses/InvalidRequest"}, + }, + }, + }, + "/v1/artifact-publications": { + "post": { + "tags": ["scopes"], + "summary": "Publish one exact Artifact revision into another Scope", + "operationId": "publish_artifact", + "requestBody": { + "content": { + "application/json": {"schema": {"$ref": "#/components/schemas/PublishArtifactRequest"}} + }, + "required": True, + }, + "responses": { + "201": { + "description": "Independent target Artifact and its exact source provenance.", + "content": { + "application/json": {"schema": {"$ref": "#/components/schemas/ArtifactPublication"}} + }, + }, + "404": {"$ref": "#/components/responses/NotFound"}, + "409": {"$ref": "#/components/responses/Conflict"}, + "401": {"$ref": "#/components/responses/Unauthorized"}, + "422": {"$ref": "#/components/responses/InvalidRequest"}, + }, + } + }, + "/v1/scopes/{scope_id}": { + "get": { + "tags": ["scopes"], + "summary": "Get one Scope descriptor", + "operationId": "get_scope", + "parameters": [ + { + "name": "scope_id", + "in": "path", + "required": True, + "schema": {"type": "string", "minLength": 1, "maxLength": 256, "pattern": ".*\\S.*"}, + } + ], + "responses": { + "200": { + "description": "The exact Scope descriptor.", + "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ScopeDescriptor"}}}, + }, + "404": {"$ref": "#/components/responses/NotFound"}, + "401": {"$ref": "#/components/responses/Unauthorized"}, + }, + }, + "put": { + "tags": ["scopes"], + "summary": "Replace mutable Scope metadata and relationships", + "operationId": "update_scope", + "parameters": [ + { + "name": "scope_id", + "in": "path", + "required": True, + "schema": {"type": "string", "minLength": 1, "maxLength": 256, "pattern": ".*\\S.*"}, + } + ], + "requestBody": { + "required": True, + "content": {"application/json": {"schema": {"$ref": "#/components/schemas/UpdateScopeRequest"}}}, + }, + "responses": { + "200": { + "description": "The updated Scope descriptor.", + "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ScopeDescriptor"}}}, + }, + "404": {"$ref": "#/components/responses/NotFound"}, + "409": {"$ref": "#/components/responses/Conflict"}, + "401": {"$ref": "#/components/responses/Unauthorized"}, + "422": {"$ref": "#/components/responses/InvalidRequest"}, + }, + }, + }, + "/v1/scopes/default": { + "get": { + "tags": ["scopes"], + "summary": "Get the default Scope binding target", + "operationId": "get_default_scope", + "responses": { + "200": { + "description": "The ordinary Scope selected by the host default pointer.", + "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ScopeDescriptor"}}}, + }, + "404": {"$ref": "#/components/responses/NotFound"}, + "401": {"$ref": "#/components/responses/Unauthorized"}, + }, + }, + "put": { + "tags": ["scopes"], + "summary": "Change the default Scope binding target", + "operationId": "set_default_scope", + "requestBody": { + "content": { + "application/json": {"schema": {"$ref": "#/components/schemas/SetDefaultScopeRequest"}} + }, + "required": True, + }, + "responses": { + "200": { + "description": "The selected ordinary Scope.", + "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ScopeDescriptor"}}}, + }, + "404": {"$ref": "#/components/responses/NotFound"}, + "401": {"$ref": "#/components/responses/Unauthorized"}, + }, + }, + }, + "/v1/scopes/selection/resolve": { + "post": { + "tags": ["scopes"], + "summary": "Resolve an observation selection to a frozen Scope set", + "operationId": "resolve_scope_selection", + "requestBody": { + "content": { + "application/json": {"schema": {"$ref": "#/components/schemas/ResolveScopeSelectionRequest"}} + }, + "required": True, + }, + "responses": { + "200": { + "description": "The selected Scope descriptors in deterministic order.", + "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ScopePage"}}}, + }, + "404": {"$ref": "#/components/responses/NotFound"}, + "401": {"$ref": "#/components/responses/Unauthorized"}, + "422": {"$ref": "#/components/responses/InvalidRequest"}, + }, + } + }, + "/v1/scope-bindings/resolve": { + "post": { + "tags": ["scope-bindings"], + "summary": "Resolve an explicit durable or default Scope binding", + "operationId": "resolve_scope_binding", + "requestBody": { + "content": { + "application/json": {"schema": {"$ref": "#/components/schemas/ResolveScopeBindingRequest"}} + }, + "required": True, + }, + "responses": { + "200": { + "description": "The resolved Scope descriptor.", + "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ScopeDescriptor"}}}, + }, + "404": {"$ref": "#/components/responses/NotFound"}, + "401": {"$ref": "#/components/responses/Unauthorized"}, + "422": {"$ref": "#/components/responses/InvalidRequest"}, + }, + } + }, + "/v1/scope-bindings": { + "put": { + "tags": ["scope-bindings"], + "summary": "Persist an external identity to Scope binding", + "operationId": "set_scope_binding", + "requestBody": { + "content": { + "application/json": {"schema": {"$ref": "#/components/schemas/SetScopeBindingRequest"}} + }, + "required": True, + }, + "responses": { + "200": { + "description": "The durable external binding.", + "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ScopeBinding"}}}, + }, + "404": {"$ref": "#/components/responses/NotFound"}, + "401": {"$ref": "#/components/responses/Unauthorized"}, + "422": {"$ref": "#/components/responses/InvalidRequest"}, + }, + } + }, + "/v1/scope-bindings/clear": { + "post": { + "tags": ["scope-bindings"], + "summary": "Remove one durable external Scope binding", + "operationId": "clear_scope_binding", + "requestBody": { + "content": { + "application/json": {"schema": {"$ref": "#/components/schemas/ClearScopeBindingRequest"}} + }, + "required": True, + }, + "responses": { + "200": { + "description": "Whether a durable binding was removed.", + "content": { + "application/json": {"schema": {"$ref": "#/components/schemas/ClearScopeBindingResponse"}} + }, + }, + "401": {"$ref": "#/components/responses/Unauthorized"}, + "422": {"$ref": "#/components/responses/InvalidRequest"}, + }, + } + }, "/v1/sources/content": { "post": { "tags": ["sources"], @@ -88,6 +320,7 @@ "503": {"$ref": "#/components/responses/Unavailable"}, "500": {"$ref": "#/components/responses/InternalError"}, }, + "x-powercontext-scope-mode": "current", } }, "/v1/context/prepare": { @@ -113,6 +346,7 @@ "503": {"$ref": "#/components/responses/Unavailable"}, "500": {"$ref": "#/components/responses/InternalError"}, }, + "x-powercontext-scope-mode": "current", } }, "/v1/work/contracts/create": { @@ -140,6 +374,7 @@ "503": {"$ref": "#/components/responses/Unavailable"}, "500": {"$ref": "#/components/responses/InternalError"}, }, + "x-powercontext-scope-mode": "current", } }, "/v1/work/handoffs/prepare-current": { @@ -173,6 +408,7 @@ "503": {"$ref": "#/components/responses/Unavailable"}, "500": {"$ref": "#/components/responses/InternalError"}, }, + "x-powercontext-scope-mode": "current", } }, "/v1/work/handoffs/acknowledge": { @@ -207,6 +443,7 @@ "503": {"$ref": "#/components/responses/Unavailable"}, "500": {"$ref": "#/components/responses/InternalError"}, }, + "x-powercontext-scope-mode": "current", } }, "/v1/work/outcomes/record": { @@ -246,6 +483,7 @@ "503": {"$ref": "#/components/responses/Unavailable"}, "500": {"$ref": "#/components/responses/InternalError"}, }, + "x-powercontext-scope-mode": "current", } }, "/v1/handoff/activate": { @@ -280,6 +518,7 @@ "503": {"$ref": "#/components/responses/Unavailable"}, "500": {"$ref": "#/components/responses/InternalError"}, }, + "x-powercontext-scope-mode": "current", } }, "/v1/handoff/prepare": { @@ -303,6 +542,7 @@ "503": {"$ref": "#/components/responses/Unavailable"}, "500": {"$ref": "#/components/responses/InternalError"}, }, + "x-powercontext-scope-mode": "current", } }, "/v1/handoff/finalize": { @@ -328,6 +568,7 @@ "503": {"$ref": "#/components/responses/Unavailable"}, "500": {"$ref": "#/components/responses/InternalError"}, }, + "x-powercontext-scope-mode": "current", } }, "/v1/handoff/commit": { @@ -352,6 +593,7 @@ "503": {"$ref": "#/components/responses/Unavailable"}, "500": {"$ref": "#/components/responses/InternalError"}, }, + "x-powercontext-scope-mode": "current", } }, "/v1/handoff/continue": { @@ -377,6 +619,7 @@ "503": {"$ref": "#/components/responses/Unavailable"}, "500": {"$ref": "#/components/responses/InternalError"}, }, + "x-powercontext-scope-mode": "current", } }, "/v1/memory/flush": { @@ -402,6 +645,7 @@ "503": {"$ref": "#/components/responses/Unavailable"}, "500": {"$ref": "#/components/responses/InternalError"}, }, + "x-powercontext-scope-mode": "current", } }, "/v1/memory/remember": { @@ -430,6 +674,7 @@ "503": {"$ref": "#/components/responses/Unavailable"}, "500": {"$ref": "#/components/responses/InternalError"}, }, + "x-powercontext-scope-mode": "current", } }, "/v1/memory/search": { @@ -456,6 +701,7 @@ "503": {"$ref": "#/components/responses/Unavailable"}, "500": {"$ref": "#/components/responses/InternalError"}, }, + "x-powercontext-scope-mode": "current", } }, "/v1/memory/entries/list": { @@ -487,6 +733,7 @@ "503": {"$ref": "#/components/responses/Unavailable"}, "500": {"$ref": "#/components/responses/InternalError"}, }, + "x-powercontext-scope-mode": "current", } }, "/v1/memory/entries/get": { @@ -511,6 +758,7 @@ "503": {"$ref": "#/components/responses/Unavailable"}, "500": {"$ref": "#/components/responses/InternalError"}, }, + "x-powercontext-scope-mode": "current", } }, "/v1/memory/entries/revise": { @@ -540,6 +788,7 @@ "503": {"$ref": "#/components/responses/Unavailable"}, "500": {"$ref": "#/components/responses/InternalError"}, }, + "x-powercontext-scope-mode": "current", } }, "/v1/memory/entries/retire": { @@ -571,6 +820,7 @@ "503": {"$ref": "#/components/responses/Unavailable"}, "500": {"$ref": "#/components/responses/InternalError"}, }, + "x-powercontext-scope-mode": "current", } }, "/v1/memory/changes": { @@ -599,6 +849,7 @@ "503": {"$ref": "#/components/responses/Unavailable"}, "500": {"$ref": "#/components/responses/InternalError"}, }, + "x-powercontext-scope-mode": "current", } }, "/v1/experience/propose": { @@ -625,6 +876,7 @@ "503": {"$ref": "#/components/responses/Unavailable"}, "500": {"$ref": "#/components/responses/InternalError"}, }, + "x-powercontext-scope-mode": "current", } }, "/v1/experience/generate": { @@ -656,6 +908,7 @@ "503": {"$ref": "#/components/responses/Unavailable"}, "500": {"$ref": "#/components/responses/InternalError"}, }, + "x-powercontext-scope-mode": "current", } }, "/v1/experience/get": { @@ -682,6 +935,7 @@ "503": {"$ref": "#/components/responses/Unavailable"}, "500": {"$ref": "#/components/responses/InternalError"}, }, + "x-powercontext-scope-mode": "current", } }, "/v1/skill/propose": { @@ -706,6 +960,7 @@ "503": {"$ref": "#/components/responses/Unavailable"}, "500": {"$ref": "#/components/responses/InternalError"}, }, + "x-powercontext-scope-mode": "current", } }, "/v1/skill/generate": { @@ -734,6 +989,7 @@ "503": {"$ref": "#/components/responses/Unavailable"}, "500": {"$ref": "#/components/responses/InternalError"}, }, + "x-powercontext-scope-mode": "current", } }, "/v1/skill/get": { @@ -758,6 +1014,7 @@ "503": {"$ref": "#/components/responses/Unavailable"}, "500": {"$ref": "#/components/responses/InternalError"}, }, + "x-powercontext-scope-mode": "current", } }, "/v1/external-skills/scan": { @@ -788,6 +1045,7 @@ "503": {"$ref": "#/components/responses/Unavailable"}, "500": {"$ref": "#/components/responses/InternalError"}, }, + "x-powercontext-scope-mode": "current", } }, "/v1/external-skills/list": { @@ -826,6 +1084,7 @@ "503": {"$ref": "#/components/responses/Unavailable"}, "500": {"$ref": "#/components/responses/InternalError"}, }, + "x-powercontext-scope-mode": "current", } }, "/v1/external-skills/resolve": { @@ -857,6 +1116,7 @@ "503": {"$ref": "#/components/responses/Unavailable"}, "500": {"$ref": "#/components/responses/InternalError"}, }, + "x-powercontext-scope-mode": "current", } }, "/v1/external-skills/import": { @@ -889,6 +1149,7 @@ "503": {"$ref": "#/components/responses/Unavailable"}, "500": {"$ref": "#/components/responses/InternalError"}, }, + "x-powercontext-scope-mode": "current", } }, "/v1/artifact-candidates/list": { @@ -916,6 +1177,7 @@ "503": {"$ref": "#/components/responses/Unavailable"}, "500": {"$ref": "#/components/responses/InternalError"}, }, + "x-powercontext-scope-mode": "current", } }, "/v1/artifact-candidates/get": { @@ -942,6 +1204,7 @@ "503": {"$ref": "#/components/responses/Unavailable"}, "500": {"$ref": "#/components/responses/InternalError"}, }, + "x-powercontext-scope-mode": "current", } }, "/v1/artifact-candidates/approve": { @@ -969,6 +1232,7 @@ "503": {"$ref": "#/components/responses/Unavailable"}, "500": {"$ref": "#/components/responses/InternalError"}, }, + "x-powercontext-scope-mode": "current", } }, "/v1/artifact-candidates/reject": { @@ -999,6 +1263,7 @@ "503": {"$ref": "#/components/responses/Unavailable"}, "500": {"$ref": "#/components/responses/InternalError"}, }, + "x-powercontext-scope-mode": "current", } }, "/v1/artifact-candidates/revise": { @@ -1026,30 +1291,24 @@ "503": {"$ref": "#/components/responses/Unavailable"}, "500": {"$ref": "#/components/responses/InternalError"}, }, + "x-powercontext-scope-mode": "current", } }, "/v1/stats": { - "get": { + "post": { "tags": ["stats"], - "summary": "Get scoped product statistics", + "summary": "Aggregate product statistics over a Scope selection", "operationId": "get_stats", - "parameters": [ - { - "name": "scope_id", - "in": "query", - "required": True, - "schema": {"type": "string", "minLength": 1, "maxLength": 256, "pattern": ".*\\S.*"}, - }, - { - "name": "period", - "in": "query", - "required": False, - "schema": {"$ref": "#/components/schemas/StatsPeriod"}, - }, - ], + "requestBody": { + "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GetStatsRequest"}}}, + "required": True, + }, "responses": { "200": { - "description": "Current inventory, model usage, and recall token estimates for the scope.", + "description": "Current inventory, model " + "usage, and recall token " + "estimates for the frozen " + "Scope set.", "headers": { "X-PowerContext-Request-ID": {"$ref": "#/components/headers/RequestId"}, "Cache-Control": { @@ -1064,476 +1323,315 @@ "503": {"$ref": "#/components/responses/Unavailable"}, "500": {"$ref": "#/components/responses/InternalError"}, }, + "x-powercontext-scope-mode": "selection", } }, - "/v1/handoff-reports/projects/create": { - "post": { - "tags": ["handoff-reports"], - "summary": "Create a Handoff Report Project", - "operationId": "create_handoff_report_project", - "requestBody": { - "content": { - "application/json": { - "schema": {"$ref": "#/components/schemas/CreateHandoffReportProjectRequest"} - } - }, - "required": True, - }, - "responses": { - "201": { - "description": "The created Report Project.", - "headers": {"X-PowerContext-Request-ID": {"$ref": "#/components/headers/RequestId"}}, - "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ProjectDescriptor"}}}, - }, - "409": {"$ref": "#/components/responses/Conflict"}, - "401": {"$ref": "#/components/responses/Unauthorized"}, - "422": {"$ref": "#/components/responses/InvalidRequest"}, - "500": {"$ref": "#/components/responses/InternalError"}, - }, - } - }, - "/v1/handoff-reports/projects/list": { - "post": { - "tags": ["handoff-reports"], - "summary": "List Handoff Report Projects", - "operationId": "list_handoff_report_projects", - "requestBody": { - "content": { - "application/json": { - "schema": {"$ref": "#/components/schemas/ListHandoffReportProjectsRequest"} - } - }, - "required": True, - }, - "responses": { - "200": { - "description": "A cursor-paginated page of Report Projects.", - "headers": {"X-PowerContext-Request-ID": {"$ref": "#/components/headers/RequestId"}}, - "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ProjectPage"}}}, - }, - "401": {"$ref": "#/components/responses/Unauthorized"}, - "422": {"$ref": "#/components/responses/InvalidRequest"}, - "500": {"$ref": "#/components/responses/InternalError"}, - }, - } - }, - "/v1/handoff-reports/scopes/list-known": { + "/v1/handoff-reports/get": { "post": { "tags": ["handoff-reports"], - "summary": "List scopes that contain a committed Handoff", - "operationId": "list_handoff_report_known_scopes", + "summary": "Generate a Handoff Report", + "operationId": "get_handoff_report", "requestBody": { "content": { - "application/json": { - "schema": {"$ref": "#/components/schemas/ListHandoffReportKnownScopesRequest"} - } + "application/json": {"schema": {"$ref": "#/components/schemas/GetHandoffReportRequest"}} }, "required": True, }, "responses": { "200": { - "description": "A cursor-paginated page of scopes that can be rendered as Handoff Reports.", - "headers": {"X-PowerContext-Request-ID": {"$ref": "#/components/headers/RequestId"}}, + "description": "A canonical JSON report, optionally accompanied by Markdown.", + "headers": { + "X-PowerContext-Request-ID": {"$ref": "#/components/headers/RequestId"}, + "Cache-Control": { + "description": "Prevent caches from retaining scoped report data.", + "schema": {"type": "string", "enum": ["no-store"]}, + }, + "X-PowerContext-Selection-Digest": { + "description": "Digest of the exact report selection.", + "schema": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"}, + }, + "X-PowerContext-Report-Digest": { + "description": "Digest of the selected output projection.", + "schema": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"}, + }, + "Content-Disposition": { + "description": "Safe attachment filename when download is true.", + "schema": {"type": "string"}, + }, + }, "content": { - "application/json": {"schema": {"$ref": "#/components/schemas/KnownHandoffScopePage"}} + "application/json": {"schema": {"$ref": "#/components/schemas/HandoffReportResponse"}}, + "text/markdown": {"schema": {"type": "string"}}, }, }, + "404": {"$ref": "#/components/responses/NotFound"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "422": {"$ref": "#/components/responses/InvalidRequest"}, + "413": {"$ref": "#/components/responses/ReportTooLarge"}, + "503": {"$ref": "#/components/responses/Unavailable"}, "500": {"$ref": "#/components/responses/InternalError"}, }, + "x-powercontext-scope-mode": "selection", } }, - "/v1/handoff-reports/projects/get": { - "post": { - "tags": ["handoff-reports"], - "summary": "Get a Handoff Report Project", - "operationId": "get_handoff_report_project", - "requestBody": { - "content": { - "application/json": {"schema": {"$ref": "#/components/schemas/GetHandoffReportProjectRequest"}} + }, + "components": { + "schemas": { + "ActivateHandoffRequest": { + "properties": { + "scope_id": {"type": "string", "maxLength": 256, "minLength": 1, "pattern": ".*\\S.*"}, + "boundary_source": {"$ref": "#/components/schemas/SourceReference"}, + "objective": {"type": "string", "maxLength": 8192, "minLength": 1, "pattern": ".*\\S.*"}, + "evidence": { + "items": {"$ref": "#/components/schemas/HandoffCitation"}, + "type": "array", + "maxItems": 32, + "default": [], }, - "required": True, + "max_bytes": {"type": "integer", "maximum": 32768.0, "minimum": 512.0, "default": 8000}, }, - "responses": { - "200": { - "description": "The exact current Report Project descriptor.", - "headers": {"X-PowerContext-Request-ID": {"$ref": "#/components/headers/RequestId"}}, - "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ProjectDescriptor"}}}, - }, - "404": {"$ref": "#/components/responses/NotFound"}, - "401": {"$ref": "#/components/responses/Unauthorized"}, - "422": {"$ref": "#/components/responses/InvalidRequest"}, - "500": {"$ref": "#/components/responses/InternalError"}, - }, - } - }, - "/v1/handoff-reports/projects/update": { - "post": { - "tags": ["handoff-reports"], - "summary": "Update a Handoff Report Project", - "operationId": "update_handoff_report_project", - "requestBody": { - "content": { - "application/json": { - "schema": {"$ref": "#/components/schemas/UpdateHandoffReportProjectRequest"} - } - }, - "required": True, - }, - "responses": { - "200": { - "description": "The updated Report Project descriptor.", - "headers": {"X-PowerContext-Request-ID": {"$ref": "#/components/headers/RequestId"}}, - "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ProjectDescriptor"}}}, - }, - "404": {"$ref": "#/components/responses/NotFound"}, - "409": {"$ref": "#/components/responses/Conflict"}, - "401": {"$ref": "#/components/responses/Unauthorized"}, - "422": {"$ref": "#/components/responses/InvalidRequest"}, - "500": {"$ref": "#/components/responses/InternalError"}, - }, - } - }, - "/v1/handoff-reports/workstreams/register": { - "post": { - "tags": ["handoff-reports"], - "summary": "Register a Handoff Report Workstream", - "operationId": "register_handoff_report_workstream", - "requestBody": { - "content": { - "application/json": { - "schema": {"$ref": "#/components/schemas/RegisterHandoffReportWorkstreamRequest"} - } - }, - "required": True, - }, - "responses": { - "201": { - "description": "The registered Report Workstream.", - "headers": {"X-PowerContext-Request-ID": {"$ref": "#/components/headers/RequestId"}}, - "content": { - "application/json": {"schema": {"$ref": "#/components/schemas/WorkstreamDescriptor"}} - }, - }, - "404": {"$ref": "#/components/responses/NotFound"}, - "409": {"$ref": "#/components/responses/Conflict"}, - "401": {"$ref": "#/components/responses/Unauthorized"}, - "422": {"$ref": "#/components/responses/InvalidRequest"}, - "500": {"$ref": "#/components/responses/InternalError"}, - }, - } - }, - "/v1/handoff-reports/workstreams/list": { - "post": { - "tags": ["handoff-reports"], - "summary": "List Handoff Report Workstreams", - "operationId": "list_handoff_report_workstreams", - "requestBody": { - "content": { - "application/json": { - "schema": {"$ref": "#/components/schemas/ListHandoffReportWorkstreamsRequest"} - } - }, - "required": True, - }, - "responses": { - "200": { - "description": "A cursor-paginated page of Report Workstreams.", - "headers": {"X-PowerContext-Request-ID": {"$ref": "#/components/headers/RequestId"}}, - "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WorkstreamPage"}}}, - }, - "404": {"$ref": "#/components/responses/NotFound"}, - "401": {"$ref": "#/components/responses/Unauthorized"}, - "422": {"$ref": "#/components/responses/InvalidRequest"}, - "500": {"$ref": "#/components/responses/InternalError"}, + "additionalProperties": False, + "type": "object", + "required": ["scope_id", "boundary_source", "objective"], + }, + "ArtifactReference": { + "properties": { + "family": {"type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[\\x21-\\x7E]+$"}, + "artifact_id": {"type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[\\x21-\\x7E]+$"}, + "revision": {"type": "integer", "minimum": 1.0}, }, - } - }, - "/v1/handoff-reports/workstreams/update": { - "post": { - "tags": ["handoff-reports"], - "summary": "Update a Handoff Report Workstream", - "operationId": "update_handoff_report_workstream", - "requestBody": { - "content": { - "application/json": { - "schema": {"$ref": "#/components/schemas/UpdateHandoffReportWorkstreamRequest"} - } - }, - "required": True, + "additionalProperties": False, + "type": "object", + "required": ["family", "artifact_id", "revision"], + }, + "ArtifactAddress": { + "properties": { + "scope_id": {"type": "string", "maxLength": 256, "minLength": 1, "pattern": ".*\\S.*"}, + "artifact": {"$ref": "#/components/schemas/ArtifactReference"}, }, - "responses": { - "200": { - "description": "The updated Report Workstream descriptor.", - "headers": {"X-PowerContext-Request-ID": {"$ref": "#/components/headers/RequestId"}}, - "content": { - "application/json": {"schema": {"$ref": "#/components/schemas/WorkstreamDescriptor"}} - }, - }, - "404": {"$ref": "#/components/responses/NotFound"}, - "409": {"$ref": "#/components/responses/Conflict"}, - "401": {"$ref": "#/components/responses/Unauthorized"}, - "422": {"$ref": "#/components/responses/InvalidRequest"}, - "500": {"$ref": "#/components/responses/InternalError"}, + "additionalProperties": False, + "type": "object", + "required": ["scope_id", "artifact"], + }, + "PublishArtifactRequest": { + "properties": { + "source": {"$ref": "#/components/schemas/ArtifactAddress"}, + "target_scope_id": {"type": "string", "maxLength": 256, "minLength": 1, "pattern": ".*\\S.*"}, + "idempotency_key": {"type": "string", "maxLength": 256, "minLength": 1, "pattern": ".*\\S.*"}, }, - } - }, - "/v1/handoff-reports/get": { - "post": { - "tags": ["handoff-reports"], - "summary": "Generate a Handoff Report", - "operationId": "get_handoff_report", - "requestBody": { - "content": { - "application/json": {"schema": {"$ref": "#/components/schemas/GetHandoffReportRequest"}} - }, - "required": True, + "additionalProperties": False, + "type": "object", + "required": ["source", "target_scope_id", "idempotency_key"], + }, + "ArtifactPublication": { + "properties": { + "source": {"$ref": "#/components/schemas/ArtifactAddress"}, + "target": {"$ref": "#/components/schemas/ArtifactAddress"}, + "content_digest": {"type": "string", "pattern": "^[0-9a-f]{64}$"}, }, - "responses": { - "200": { - "description": "A canonical JSON report, optionally accompanied by Markdown.", - "headers": { - "X-PowerContext-Request-ID": {"$ref": "#/components/headers/RequestId"}, - "Cache-Control": { - "description": "Prevent caches from retaining scoped report data.", - "schema": {"type": "string", "enum": ["no-store"]}, - }, - "X-PowerContext-Selection-Digest": { - "description": "Digest of the exact report selection.", - "schema": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"}, - }, - "X-PowerContext-Report-Digest": { - "description": "Digest of the selected output projection.", - "schema": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"}, - }, - "Content-Disposition": { - "description": "Safe attachment filename when download is true.", - "schema": {"type": "string"}, - }, - }, - "content": { - "application/json": {"schema": {"$ref": "#/components/schemas/HandoffReportResponse"}}, - "text/markdown": {"schema": {"type": "string"}}, - }, - }, - "404": {"$ref": "#/components/responses/NotFound"}, - "401": {"$ref": "#/components/responses/Unauthorized"}, - "422": {"$ref": "#/components/responses/InvalidRequest"}, - "413": {"$ref": "#/components/responses/ReportTooLarge"}, - "503": {"$ref": "#/components/responses/Unavailable"}, - "500": {"$ref": "#/components/responses/InternalError"}, + "additionalProperties": False, + "type": "object", + "required": ["source", "target", "content_digest"], + }, + "ScopeExternalReference": { + "properties": { + "kind": {"type": "string", "maxLength": 128, "minLength": 1, "pattern": ".*\\S.*"}, + "value": {"type": "string", "maxLength": 2000, "minLength": 1, "pattern": ".*\\S.*"}, }, - } - }, - "/v1/handoff-reports/activities/record": { - "post": { - "tags": ["handoff-reports"], - "summary": "Record a Handoff Report Activity", - "operationId": "record_handoff_report_activity", - "requestBody": { - "content": { - "application/json": { - "schema": {"$ref": "#/components/schemas/RecordHandoffReportActivityRequest"} - } + "additionalProperties": False, + "type": "object", + "required": ["kind", "value"], + }, + "ScopeDescriptor": { + "properties": { + "scope_id": {"type": "string", "maxLength": 256, "minLength": 1, "pattern": ".*\\S.*"}, + "title": {"type": "string", "maxLength": 256, "minLength": 1, "pattern": ".*\\S.*"}, + "summary": {"type": "string", "maxLength": 2000, "minLength": 1, "pattern": ".*\\S.*"}, + "parent_scope_id": { + "type": "string", + "maxLength": 256, + "minLength": 1, + "pattern": ".*\\S.*", + "nullable": True, }, - "required": True, - }, - "responses": { - "201": { - "description": "The idempotently recorded Report Activity.", - "headers": {"X-PowerContext-Request-ID": {"$ref": "#/components/headers/RequestId"}}, - "content": { - "application/json": {"schema": {"$ref": "#/components/schemas/StoredHandoffReportActivity"}} - }, + "context_references": { + "items": {"type": "string", "maxLength": 256, "minLength": 1, "pattern": ".*\\S.*"}, + "type": "array", + "uniqueItems": True, }, - "404": {"$ref": "#/components/responses/NotFound"}, - "409": {"$ref": "#/components/responses/Conflict"}, - "401": {"$ref": "#/components/responses/Unauthorized"}, - "422": {"$ref": "#/components/responses/InvalidRequest"}, - "500": {"$ref": "#/components/responses/InternalError"}, - }, - } - }, - "/v1/handoff-reports/activities/list": { - "post": { - "tags": ["handoff-reports"], - "summary": "List Handoff Report Activities", - "operationId": "list_handoff_report_activities", - "requestBody": { - "content": { - "application/json": { - "schema": {"$ref": "#/components/schemas/ListHandoffReportActivitiesRequest"} - } + "external_references": { + "items": {"$ref": "#/components/schemas/ScopeExternalReference"}, + "type": "array", + "uniqueItems": True, }, - "required": True, + "version": {"type": "integer", "minimum": 1.0}, }, - "responses": { - "200": { - "description": "A frozen cursor page of Report Activities.", - "headers": {"X-PowerContext-Request-ID": {"$ref": "#/components/headers/RequestId"}}, - "content": { - "application/json": {"schema": {"$ref": "#/components/schemas/HandoffReportActivityPage"}} - }, + "additionalProperties": False, + "type": "object", + "required": ["scope_id", "title", "summary", "context_references", "external_references", "version"], + }, + "ScopePage": { + "properties": {"items": {"items": {"$ref": "#/components/schemas/ScopeDescriptor"}, "type": "array"}}, + "additionalProperties": False, + "type": "object", + "required": ["items"], + }, + "CreateScopeRequest": { + "properties": { + "title": {"type": "string", "maxLength": 256, "minLength": 1, "pattern": ".*\\S.*"}, + "summary": {"type": "string", "maxLength": 2000, "minLength": 1, "pattern": ".*\\S.*"}, + "parent_scope_id": { + "type": "string", + "maxLength": 256, + "minLength": 1, + "pattern": ".*\\S.*", + "nullable": True, }, - "404": {"$ref": "#/components/responses/NotFound"}, - "401": {"$ref": "#/components/responses/Unauthorized"}, - "422": {"$ref": "#/components/responses/InvalidRequest"}, - "500": {"$ref": "#/components/responses/InternalError"}, - }, - } - }, - "/v1/handoff-reports/activities/purge": { - "post": { - "tags": ["handoff-reports"], - "summary": "Purge Handoff Report Activities", - "operationId": "purge_handoff_report_activities", - "requestBody": { - "content": { - "application/json": { - "schema": {"$ref": "#/components/schemas/PurgeHandoffReportActivitiesRequest"} - } + "context_references": { + "items": {"type": "string", "maxLength": 256, "minLength": 1, "pattern": ".*\\S.*"}, + "type": "array", + "uniqueItems": True, + "default": [], }, - "required": True, - }, - "responses": { - "200": { - "description": "The number of deleted Report-owned Activity rows.", - "headers": {"X-PowerContext-Request-ID": {"$ref": "#/components/headers/RequestId"}}, - "content": { - "application/json": { - "schema": {"$ref": "#/components/schemas/PurgeHandoffReportActivitiesResponse"} - } - }, + "external_references": { + "items": {"$ref": "#/components/schemas/ScopeExternalReference"}, + "type": "array", + "uniqueItems": True, + "default": [], }, - "404": {"$ref": "#/components/responses/NotFound"}, - "401": {"$ref": "#/components/responses/Unauthorized"}, - "422": {"$ref": "#/components/responses/InvalidRequest"}, - "500": {"$ref": "#/components/responses/InternalError"}, + "idempotency_key": {"type": "string", "maxLength": 256, "minLength": 1, "pattern": ".*\\S.*"}, }, - } - }, - "/v1/handoff-reports/workspace-bindings/get": { - "post": { - "tags": ["handoff-reports"], - "summary": "Get a Handoff Report Workspace Binding", - "operationId": "get_handoff_report_workspace", - "requestBody": { - "content": { - "application/json": { - "schema": {"$ref": "#/components/schemas/GetHandoffReportWorkspaceRequest"} - } + "additionalProperties": False, + "type": "object", + "required": ["title", "summary", "idempotency_key"], + }, + "UpdateScopeRequest": { + "properties": { + "expected_version": {"type": "integer", "minimum": 1.0}, + "title": {"type": "string", "maxLength": 256, "minLength": 1, "pattern": ".*\\S.*"}, + "summary": {"type": "string", "maxLength": 2000, "minLength": 1, "pattern": ".*\\S.*"}, + "parent_scope_id": { + "type": "string", + "maxLength": 256, + "minLength": 1, + "pattern": ".*\\S.*", + "nullable": True, }, - "required": True, - }, - "responses": { - "200": { - "description": "The confirmed Workspace binding.", - "headers": {"X-PowerContext-Request-ID": {"$ref": "#/components/headers/RequestId"}}, - "content": { - "application/json": { - "schema": {"$ref": "#/components/schemas/HandoffReportWorkspaceBinding"} - } - }, + "context_references": { + "items": {"type": "string", "maxLength": 256, "minLength": 1, "pattern": ".*\\S.*"}, + "type": "array", + "uniqueItems": True, + "default": [], }, - "404": {"$ref": "#/components/responses/NotFound"}, - "401": {"$ref": "#/components/responses/Unauthorized"}, - "422": {"$ref": "#/components/responses/InvalidRequest"}, - "500": {"$ref": "#/components/responses/InternalError"}, - }, - } - }, - "/v1/handoff-reports/workspace-bindings/attach": { - "post": { - "tags": ["handoff-reports"], - "summary": "Attach a Handoff Report Workspace Binding", - "operationId": "attach_handoff_report_workspace", - "requestBody": { - "content": { - "application/json": { - "schema": {"$ref": "#/components/schemas/AttachHandoffReportWorkspaceRequest"} - } + "external_references": { + "items": {"$ref": "#/components/schemas/ScopeExternalReference"}, + "type": "array", + "uniqueItems": True, + "default": [], }, - "required": True, }, - "responses": { - "200": { - "description": "The confirmed Workspace binding.", - "headers": {"X-PowerContext-Request-ID": {"$ref": "#/components/headers/RequestId"}}, - "content": { - "application/json": { - "schema": {"$ref": "#/components/schemas/HandoffReportWorkspaceBinding"} - } - }, + "additionalProperties": False, + "type": "object", + "required": ["expected_version", "title", "summary"], + }, + "SetDefaultScopeRequest": { + "properties": {"scope_id": {"type": "string", "maxLength": 256, "minLength": 1, "pattern": ".*\\S.*"}}, + "additionalProperties": False, + "type": "object", + "required": ["scope_id"], + }, + "AllScopeSelection": { + "properties": {"mode": {"type": "string", "enum": ["all"]}}, + "additionalProperties": False, + "type": "object", + "required": ["mode"], + }, + "ExactScopeSelection": { + "properties": { + "mode": {"type": "string", "enum": ["exact"]}, + "scope_ids": { + "items": {"type": "string", "maxLength": 256, "minLength": 1, "pattern": ".*\\S.*"}, + "type": "array", + "minItems": 1, + "uniqueItems": True, }, - "404": {"$ref": "#/components/responses/NotFound"}, - "409": {"$ref": "#/components/responses/Conflict"}, - "401": {"$ref": "#/components/responses/Unauthorized"}, - "422": {"$ref": "#/components/responses/InvalidRequest"}, - "500": {"$ref": "#/components/responses/InternalError"}, }, - } - }, - "/v1/handoff-reports/workspace-bindings/detach": { - "post": { - "tags": ["handoff-reports"], - "summary": "Detach a Handoff Report Workspace Binding", - "operationId": "detach_handoff_report_workspace", - "requestBody": { - "content": { - "application/json": { - "schema": {"$ref": "#/components/schemas/DetachHandoffReportWorkspaceRequest"} - } - }, - "required": True, + "additionalProperties": False, + "type": "object", + "required": ["mode", "scope_ids"], + }, + "SubtreeScopeSelection": { + "properties": { + "mode": {"type": "string", "enum": ["subtree"]}, + "root_scope_id": {"type": "string", "maxLength": 256, "minLength": 1, "pattern": ".*\\S.*"}, }, - "responses": { - "200": { - "description": "The detached Workspace binding record.", - "headers": {"X-PowerContext-Request-ID": {"$ref": "#/components/headers/RequestId"}}, - "content": { - "application/json": { - "schema": {"$ref": "#/components/schemas/HandoffReportWorkspaceBinding"} - } - }, - }, - "404": {"$ref": "#/components/responses/NotFound"}, - "409": {"$ref": "#/components/responses/Conflict"}, - "401": {"$ref": "#/components/responses/Unauthorized"}, - "422": {"$ref": "#/components/responses/InvalidRequest"}, - "500": {"$ref": "#/components/responses/InternalError"}, + "additionalProperties": False, + "type": "object", + "required": ["mode", "root_scope_id"], + }, + "ScopeSelection": { + "oneOf": [ + {"$ref": "#/components/schemas/AllScopeSelection"}, + {"$ref": "#/components/schemas/ExactScopeSelection"}, + {"$ref": "#/components/schemas/SubtreeScopeSelection"}, + ], + "discriminator": {"propertyName": "mode"}, + }, + "ResolveScopeSelectionRequest": { + "properties": {"selection": {"$ref": "#/components/schemas/ScopeSelection"}}, + "additionalProperties": False, + "type": "object", + "required": ["selection"], + }, + "ScopeBindingKey": { + "properties": { + "integration": {"type": "string", "maxLength": 128, "minLength": 1, "pattern": ".*\\S.*"}, + "kind": {"type": "string", "maxLength": 64, "minLength": 1, "pattern": ".*\\S.*"}, + "external_id": {"type": "string", "maxLength": 256, "minLength": 1, "pattern": ".*\\S.*"}, }, - } - }, - }, - "components": { - "schemas": { - "ActivateHandoffRequest": { + "additionalProperties": False, + "type": "object", + "required": ["integration", "kind", "external_id"], + }, + "ScopeBinding": { "properties": { + "key": {"$ref": "#/components/schemas/ScopeBindingKey"}, "scope_id": {"type": "string", "maxLength": 256, "minLength": 1, "pattern": ".*\\S.*"}, - "boundary_source": {"$ref": "#/components/schemas/SourceReference"}, - "objective": {"type": "string", "maxLength": 8192, "minLength": 1, "pattern": ".*\\S.*"}, - "evidence": { - "items": {"$ref": "#/components/schemas/HandoffCitation"}, - "type": "array", - "maxItems": 32, - "default": [], - }, - "max_bytes": {"type": "integer", "maximum": 32768.0, "minimum": 512.0, "default": 8000}, }, "additionalProperties": False, "type": "object", - "required": ["scope_id", "boundary_source", "objective"], + "required": ["key", "scope_id"], }, - "ArtifactReference": { + "SetScopeBindingRequest": {"$ref": "#/components/schemas/ScopeBinding"}, + "ClearScopeBindingRequest": { + "properties": {"key": {"$ref": "#/components/schemas/ScopeBindingKey"}}, + "additionalProperties": False, + "type": "object", + "required": ["key"], + }, + "ClearScopeBindingResponse": { + "properties": {"cleared": {"type": "boolean"}}, + "additionalProperties": False, + "type": "object", + "required": ["cleared"], + }, + "ResolveScopeBindingRequest": { "properties": { - "family": {"type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[\\x21-\\x7E]+$"}, - "artifact_id": {"type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[\\x21-\\x7E]+$"}, - "revision": {"type": "integer", "minimum": 1.0}, + "explicit_scope_id": { + "type": "string", + "maxLength": 256, + "minLength": 1, + "pattern": ".*\\S.*", + "nullable": True, + }, + "binding_keys": { + "items": {"$ref": "#/components/schemas/ScopeBindingKey"}, + "type": "array", + "default": [], + }, }, "additionalProperties": False, "type": "object", - "required": ["family", "artifact_id", "revision"], }, "ArtifactCandidate": { "properties": { @@ -1903,26 +2001,39 @@ "type": "object", "required": ["period", "estimator", "totals", "daily"], }, - "ScopedStats": { + "ScopeStats": { "properties": { "scope_id": {"type": "string"}, + "inventory": {"$ref": "#/components/schemas/InventoryStatistics"}, + "usage": {"$ref": "#/components/schemas/UsageStatistics"}, + "recall": {"$ref": "#/components/schemas/RecallTokenStatistics"}, + }, + "additionalProperties": False, + "type": "object", + "required": ["scope_id", "inventory", "usage", "recall"], + }, + "ScopedStats": { + "properties": { + "selection": {"$ref": "#/components/schemas/ScopeSelection"}, + "scope_ids": {"items": {"type": "string"}, "type": "array", "uniqueItems": True}, "as_of": {"type": "string", "format": "date-time"}, "inventory": {"$ref": "#/components/schemas/InventoryStatistics"}, "usage": {"$ref": "#/components/schemas/UsageStatistics"}, "recall": {"$ref": "#/components/schemas/RecallTokenStatistics"}, + "by_scope": {"items": {"$ref": "#/components/schemas/ScopeStats"}, "type": "array"}, }, "additionalProperties": False, "type": "object", - "required": ["scope_id", "as_of", "inventory", "usage", "recall"], + "required": ["selection", "scope_ids", "as_of", "inventory", "usage", "recall", "by_scope"], }, "GetStatsRequest": { "properties": { - "scope_id": {"type": "string", "maxLength": 256, "minLength": 1, "pattern": ".*\\S.*"}, + "selection": {"$ref": "#/components/schemas/ScopeSelection"}, "period": {"$ref": "#/components/schemas/StatsPeriod", "default": "30d"}, }, "additionalProperties": False, "type": "object", - "required": ["scope_id"], + "required": ["selection"], }, "WorkClaimBasis": {"type": "string", "enum": ["declared", "verified"]}, "WorkClaim": { @@ -2677,142 +2788,15 @@ "type": "object", "required": ["scope_id", "artifact"], }, - "CreateHandoffReportProjectRequest": { - "properties": { - "project_key": {"type": "string", "maxLength": 64, "minLength": 1}, - "title": {"type": "string", "maxLength": 256, "minLength": 1}, - "description": {"type": "string", "maxLength": 2000, "nullable": True}, - "default_locale": {"$ref": "#/components/schemas/ReportLocale", "default": "zh-CN"}, - "timezone": {"type": "string", "maxLength": 256, "minLength": 1, "default": "UTC"}, - }, - "additionalProperties": False, - "type": "object", - "required": ["project_key", "title"], - }, - "ListHandoffReportProjectsRequest": { - "properties": { - "cursor": {"type": "string", "nullable": True}, - "limit": {"type": "integer", "maximum": 100.0, "minimum": 1.0, "default": 50}, - "include_archived": {"type": "boolean", "default": False}, - }, - "additionalProperties": False, - "type": "object", - }, - "GetHandoffReportProjectRequest": { - "properties": {"project_id": {"type": "string", "maxLength": 256, "minLength": 1}}, - "additionalProperties": False, - "type": "object", - "required": ["project_id"], - }, - "UpdateHandoffReportProjectRequest": { - "properties": { - "project": {"$ref": "#/components/schemas/ProjectDescriptor"}, - "expected_version": {"type": "integer", "minimum": 1.0}, - }, - "additionalProperties": False, - "type": "object", - "required": ["project", "expected_version"], - }, - "RegisterHandoffReportWorkstreamRequest": { - "properties": { - "project_id": {"type": "string", "maxLength": 256, "minLength": 1}, - "scope_id": {"type": "string", "maxLength": 256, "minLength": 1}, - "key": {"type": "string", "maxLength": 64, "minLength": 1, "nullable": True}, - "title": {"type": "string", "maxLength": 256, "minLength": 1}, - "kind": {"$ref": "#/components/schemas/WorkstreamKind"}, - "catalog_state": {"$ref": "#/components/schemas/ReportCatalogState", "default": "included"}, - "external_refs": { - "items": {"$ref": "#/components/schemas/HandoffReportExternalReference"}, - "type": "array", - "maxItems": 32, - "default": [], - }, - "labels": { - "items": {"type": "string", "maxLength": 128, "minLength": 1}, - "type": "array", - "maxItems": 32, - "default": [], - }, - }, - "additionalProperties": False, - "type": "object", - "required": ["project_id", "scope_id", "title", "kind"], - }, - "ListHandoffReportWorkstreamsRequest": { - "properties": { - "project_id": {"type": "string", "maxLength": 256, "minLength": 1}, - "cursor": {"type": "string", "nullable": True}, - "limit": {"type": "integer", "maximum": 100.0, "minimum": 1.0, "default": 50}, - "include_archived": {"type": "boolean", "default": False}, - }, - "additionalProperties": False, - "type": "object", - "required": ["project_id"], - }, - "UpdateHandoffReportWorkstreamRequest": { - "properties": { - "workstream": {"$ref": "#/components/schemas/WorkstreamDescriptor"}, - "expected_version": {"type": "integer", "minimum": 1.0}, - }, - "additionalProperties": False, - "type": "object", - "required": ["workstream", "expected_version"], - }, "GetHandoffReportRequest": { "properties": { - "scope_id": {"type": "string", "maxLength": 256, "minLength": 1}, - "project_id": { - "type": "string", - "maxLength": 256, - "minLength": 1, - "description": "Retained for wire compatibility and ignored when generating a scope report.", - "deprecated": True, - "nullable": True, - }, - "locale": {"$ref": "#/components/schemas/ReportLocale", "nullable": True}, - "include_evidence_checks": {"type": "boolean", "default": True}, - "format": {"$ref": "#/components/schemas/ReportFormat", "default": "markdown"}, - "include_archived": {"type": "boolean", "default": False}, + "selection": {"$ref": "#/components/schemas/ScopeSelection"}, + "format": {"$ref": "#/components/schemas/ReportFormat", "default": "json"}, "download": {"type": "boolean", "default": False}, - "period": {"$ref": "#/components/schemas/HandoffReportPeriodRequest", "nullable": True}, - }, - "additionalProperties": False, - "type": "object", - "required": ["scope_id"], - }, - "ListHandoffReportKnownScopesRequest": { - "properties": { - "cursor": {"type": "string", "nullable": True}, - "limit": {"type": "integer", "maximum": 100.0, "minimum": 1.0, "default": 50}, - }, - "additionalProperties": False, - "type": "object", - }, - "KnownHandoffScope": { - "properties": {"scope_id": {"type": "string", "maxLength": 256, "minLength": 1}}, - "additionalProperties": False, - "type": "object", - "required": ["scope_id"], - }, - "KnownHandoffScopePage": { - "properties": { - "items": {"items": {"$ref": "#/components/schemas/KnownHandoffScope"}, "type": "array"}, - "next_cursor": {"type": "string", "nullable": True}, - }, - "additionalProperties": False, - "type": "object", - "required": ["items"], - }, - "HandoffReportPeriodRequest": { - "properties": { - "start": {"type": "string", "format": "date-time"}, - "end": {"type": "string", "format": "date-time"}, - "timezone": {"type": "string", "maxLength": 256, "minLength": 1, "nullable": True}, - "compare_to_previous_period": {"type": "boolean", "default": False}, }, "additionalProperties": False, "type": "object", - "required": ["start", "end"], + "required": ["selection"], }, "HandoffReportResponse": { "properties": { @@ -2826,326 +2810,7 @@ "type": "object", "required": ["format", "report", "markdown", "selection_digest", "report_digest"], }, - "ReportActivitySource": { - "type": "string", - "enum": ["handoff_observation", "git_commit", "git_worktree", "coding_session", "other"], - }, - "ReportTimeBasis": { - "type": "string", - "enum": ["source_reported", "host_observed", "first_seen", "current_only", "unknown"], - }, - "HandoffReportActivityAgent": { - "properties": { - "provider": {"type": "string", "maxLength": 64, "minLength": 1, "nullable": True}, - "label": {"type": "string", "maxLength": 128, "minLength": 1, "nullable": True}, - }, - "additionalProperties": False, - "type": "object", - }, - "HandoffReportActivityVcsContext": { - "properties": { - "branch": {"type": "string", "maxLength": 256, "minLength": 1, "nullable": True}, - "head_revision": {"type": "string", "maxLength": 256, "minLength": 1, "nullable": True}, - }, - "additionalProperties": False, - "type": "object", - }, - "RecordHandoffReportActivityRequest": { - "properties": { - "project_id": {"type": "string", "maxLength": 256, "minLength": 1}, - "scope_id": {"type": "string", "maxLength": 256, "minLength": 1, "nullable": True}, - "source": {"$ref": "#/components/schemas/ReportActivitySource"}, - "source_event_id": {"type": "string", "maxLength": 256, "minLength": 1}, - "source_ref": {"$ref": "#/components/schemas/HandoffReportExternalReference", "nullable": True}, - "occurred_at": {"type": "string", "format": "date-time", "nullable": True}, - "time_basis": {"$ref": "#/components/schemas/ReportTimeBasis"}, - "title": {"type": "string", "maxLength": 256, "minLength": 1, "nullable": True}, - "summary": {"type": "string", "maxLength": 2000, "minLength": 1, "nullable": True}, - "agent": {"$ref": "#/components/schemas/HandoffReportActivityAgent", "nullable": True}, - "session_id": {"type": "string", "maxLength": 256, "minLength": 1, "nullable": True}, - "vcs_context": {"$ref": "#/components/schemas/HandoffReportActivityVcsContext", "nullable": True}, - "evidence_refs": { - "items": {"$ref": "#/components/schemas/HandoffReportExternalReference"}, - "type": "array", - "maxItems": 32, - "default": [], - }, - }, - "additionalProperties": False, - "type": "object", - "required": ["project_id", "source", "source_event_id", "time_basis"], - }, - "HandoffReportActivity": { - "properties": { - "schema": {"type": "string", "enum": ["powercontext.handoff-report-activity.v1"]}, - "event_id": {"type": "string", "maxLength": 256, "minLength": 1}, - "project_id": {"type": "string", "maxLength": 256, "minLength": 1}, - "scope_id": {"type": "string", "maxLength": 256, "minLength": 1, "nullable": True}, - "source": {"$ref": "#/components/schemas/ReportActivitySource"}, - "source_event_id": {"type": "string", "maxLength": 256, "minLength": 1}, - "source_ref": {"$ref": "#/components/schemas/HandoffReportExternalReference", "nullable": True}, - "occurred_at": {"type": "string", "format": "date-time", "nullable": True}, - "observed_at": {"type": "string", "format": "date-time"}, - "time_basis": {"$ref": "#/components/schemas/ReportTimeBasis"}, - "title": {"type": "string", "maxLength": 256, "minLength": 1, "nullable": True}, - "summary": {"type": "string", "maxLength": 2000, "minLength": 1, "nullable": True}, - "agent": {"$ref": "#/components/schemas/HandoffReportActivityAgent", "nullable": True}, - "session_id": {"type": "string", "maxLength": 256, "minLength": 1, "nullable": True}, - "vcs_context": {"$ref": "#/components/schemas/HandoffReportActivityVcsContext", "nullable": True}, - "evidence_refs": { - "items": {"$ref": "#/components/schemas/HandoffReportExternalReference"}, - "type": "array", - "maxItems": 32, - }, - "trust": {"type": "string", "enum": ["untrusted_observation"]}, - }, - "additionalProperties": False, - "type": "object", - "required": [ - "schema", - "event_id", - "project_id", - "scope_id", - "source", - "source_event_id", - "source_ref", - "occurred_at", - "observed_at", - "time_basis", - "title", - "summary", - "agent", - "session_id", - "vcs_context", - "evidence_refs", - "trust", - ], - }, - "StoredHandoffReportActivity": { - "properties": { - "cursor": {"type": "integer", "minimum": 1.0}, - "event": {"$ref": "#/components/schemas/HandoffReportActivity"}, - }, - "additionalProperties": False, - "type": "object", - "required": ["cursor", "event"], - }, - "ListHandoffReportActivitiesRequest": { - "properties": { - "project_id": {"type": "string", "maxLength": 256, "minLength": 1}, - "period_start": {"type": "string", "format": "date-time", "nullable": True}, - "period_end": {"type": "string", "format": "date-time", "nullable": True}, - "sources": { - "items": {"$ref": "#/components/schemas/ReportActivitySource"}, - "type": "array", - "maxItems": 5, - "nullable": True, - }, - "after_cursor": {"type": "integer", "minimum": 0.0, "default": 0}, - "through_cursor": {"type": "integer", "minimum": 0.0, "nullable": True}, - "limit": {"type": "integer", "maximum": 100.0, "minimum": 1.0, "default": 50}, - }, - "additionalProperties": False, - "type": "object", - "required": ["project_id"], - }, - "HandoffReportActivityPage": { - "properties": { - "items": { - "items": {"$ref": "#/components/schemas/HandoffReportActivity"}, - "type": "array", - "maxItems": 100, - }, - "next_cursor": {"type": "integer", "minimum": 1.0, "nullable": True}, - "high_watermark": {"type": "integer", "minimum": 0.0}, - }, - "additionalProperties": False, - "type": "object", - "required": ["items", "next_cursor", "high_watermark"], - }, - "PurgeHandoffReportActivitiesRequest": { - "properties": { - "project_id": {"type": "string", "maxLength": 256, "minLength": 1}, - "observed_before": {"type": "string", "format": "date-time"}, - }, - "additionalProperties": False, - "type": "object", - "required": ["project_id", "observed_before"], - }, - "PurgeHandoffReportActivitiesResponse": { - "properties": {"deleted_count": {"type": "integer", "minimum": 0.0}}, - "additionalProperties": False, - "type": "object", - "required": ["deleted_count"], - }, - "HandoffReportRepositoryRef": { - "properties": { - "provider": {"type": "string", "enum": ["github", "gitlab", "local", "other"]}, - "repository_id": {"type": "string", "maxLength": 256, "minLength": 1, "nullable": True}, - "normalized_remote": {"type": "string", "maxLength": 2048, "minLength": 1, "nullable": True}, - "subpath": {"type": "string", "maxLength": 1024, "minLength": 1, "nullable": True}, - }, - "additionalProperties": False, - "type": "object", - "required": ["provider", "repository_id", "normalized_remote", "subpath"], - }, - "HandoffReportWorkspaceBinding": { - "properties": { - "schema": {"type": "string", "enum": ["powercontext.workspace-binding.v1"]}, - "workspace_instance_id": {"type": "string", "maxLength": 256, "minLength": 1}, - "project_id": {"type": "string", "maxLength": 256, "minLength": 1}, - "repository_ref": {"$ref": "#/components/schemas/HandoffReportRepositoryRef"}, - "state": {"type": "string", "enum": ["confirmed", "detached"]}, - "confirmed_at": {"type": "string", "format": "date-time"}, - "version": {"type": "integer", "minimum": 1.0}, - }, - "additionalProperties": False, - "type": "object", - "required": [ - "schema", - "workspace_instance_id", - "project_id", - "repository_ref", - "state", - "confirmed_at", - "version", - ], - }, - "GetHandoffReportWorkspaceRequest": { - "properties": {"workspace_instance_id": {"type": "string", "maxLength": 256, "minLength": 1}}, - "additionalProperties": False, - "type": "object", - "required": ["workspace_instance_id"], - }, - "AttachHandoffReportWorkspaceRequest": { - "properties": { - "workspace_instance_id": {"type": "string", "maxLength": 256, "minLength": 1}, - "project_id": {"type": "string", "maxLength": 256, "minLength": 1}, - "repository_ref": {"$ref": "#/components/schemas/HandoffReportRepositoryRef"}, - "expected_version": {"type": "integer", "minimum": 1.0, "nullable": True}, - }, - "additionalProperties": False, - "type": "object", - "required": ["workspace_instance_id", "project_id", "repository_ref", "expected_version"], - }, - "DetachHandoffReportWorkspaceRequest": { - "properties": { - "workspace_instance_id": {"type": "string", "maxLength": 256, "minLength": 1}, - "expected_version": {"type": "integer", "minimum": 1.0}, - }, - "additionalProperties": False, - "type": "object", - "required": ["workspace_instance_id", "expected_version"], - }, - "ProjectDescriptor": { - "properties": { - "schema": {"type": "string", "enum": ["powercontext.project.v1"]}, - "project_id": {"type": "string", "maxLength": 256, "minLength": 1}, - "project_key": {"type": "string", "maxLength": 64, "minLength": 1}, - "title": {"type": "string", "maxLength": 256, "minLength": 1}, - "description": {"type": "string", "maxLength": 2000, "nullable": True}, - "default_locale": {"$ref": "#/components/schemas/ReportLocale"}, - "timezone": {"type": "string", "maxLength": 256, "minLength": 1}, - "catalog_state": {"$ref": "#/components/schemas/ReportCatalogState"}, - "version": {"type": "integer", "minimum": 1.0}, - }, - "additionalProperties": False, - "type": "object", - "required": [ - "schema", - "project_id", - "project_key", - "title", - "description", - "default_locale", - "timezone", - "catalog_state", - "version", - ], - }, - "ProjectPage": { - "properties": { - "items": { - "items": {"$ref": "#/components/schemas/ProjectDescriptor"}, - "type": "array", - "maxItems": 100, - }, - "next_cursor": {"type": "string", "nullable": True}, - }, - "additionalProperties": False, - "type": "object", - "required": ["items", "next_cursor"], - }, - "WorkstreamDescriptor": { - "properties": { - "schema": {"type": "string", "enum": ["powercontext.workstream.v1"]}, - "scope_id": {"type": "string", "maxLength": 256, "minLength": 1}, - "project_id": {"type": "string", "maxLength": 256, "minLength": 1}, - "key": {"type": "string", "maxLength": 64, "nullable": True}, - "title": {"type": "string", "maxLength": 256, "minLength": 1}, - "kind": {"$ref": "#/components/schemas/WorkstreamKind"}, - "catalog_state": {"$ref": "#/components/schemas/ReportCatalogState"}, - "external_refs": { - "items": {"$ref": "#/components/schemas/HandoffReportExternalReference"}, - "type": "array", - "maxItems": 32, - }, - "labels": { - "items": {"type": "string", "maxLength": 128, "minLength": 1}, - "type": "array", - "maxItems": 32, - }, - "version": {"type": "integer", "minimum": 1.0}, - }, - "additionalProperties": False, - "type": "object", - "required": [ - "schema", - "scope_id", - "project_id", - "key", - "title", - "kind", - "catalog_state", - "external_refs", - "labels", - "version", - ], - }, - "WorkstreamPage": { - "properties": { - "items": { - "items": {"$ref": "#/components/schemas/WorkstreamDescriptor"}, - "type": "array", - "maxItems": 100, - }, - "next_cursor": {"type": "string", "nullable": True}, - }, - "additionalProperties": False, - "type": "object", - "required": ["items", "next_cursor"], - }, - "HandoffReportExternalReference": { - "properties": { - "kind": { - "type": "string", - "enum": ["issue", "task", "pull_request", "branch", "feature", "release", "program", "other"], - }, - "provider": {"type": "string", "maxLength": 64, "minLength": 1}, - "external_id": {"type": "string", "maxLength": 256, "minLength": 1}, - "url": {"type": "string", "maxLength": 2048, "nullable": True}, - }, - "additionalProperties": False, - "type": "object", - "required": ["kind", "provider", "external_id", "url"], - }, - "ReportLocale": {"type": "string", "enum": ["zh-CN", "en"]}, "ReportFormat": {"type": "string", "enum": ["json", "markdown"]}, - "ReportCatalogState": {"type": "string", "enum": ["included", "archived"]}, - "WorkstreamKind": { - "type": "string", - "enum": ["feature", "bug", "refactor", "operations", "research", "other"], - }, "HealthResponse": { "properties": {"status": {"type": "string"}}, "additionalProperties": False, diff --git a/src/powercontext/server/app.py b/src/powercontext/server/app.py index ebe042b4f..49aac5962 100644 --- a/src/powercontext/server/app.py +++ b/src/powercontext/server/app.py @@ -22,23 +22,23 @@ from collections.abc import Awaitable, Callable, Sequence from contextlib import suppress from copy import deepcopy -from datetime import UTC, datetime from functools import wraps from time import perf_counter from typing import TYPE_CHECKING, Annotated, Any, Protocol, TypeVar, cast -from uuid import uuid4 -from fastapi import Depends, FastAPI, Query, Request, Response, status +from fastapi import Depends, FastAPI, Request, Response, status +from fastapi import Path as PathParameter from fastapi.exceptions import RequestValidationError from fastapi.responses import JSONResponse from opentelemetry.trace import SpanKind +from pydantic import ValidationError as PydanticValidationError from scalar_fastapi import AgentScalarConfig, get_scalar_api_reference from starlette.middleware import Middleware from starlette.middleware.base import RequestResponseEndpoint from starlette.types import Lifespan from powercontext._logging import log_safely -from powercontext.artifacts import ArtifactRef +from powercontext.artifacts import ArtifactAddress, ArtifactRef from powercontext.builtin.artifacts.experience import Experience from powercontext.builtin.artifacts.handoff import ( HandoffEvidenceUnavailableError, @@ -66,37 +66,18 @@ ) from powercontext.builtin.handoff_report import ( HandoffReportApplication, - HandoffReportBusyError, - HandoffReportCatalogArgumentError, HandoffReportError, HandoffReportInconsistentError, HandoffReportTooLargeError, - ProjectConflictError, - ProjectNotFoundError, - ReportPeriodInput, - ScopeAlreadyGroupedError, - WorkspaceBindingConflictError, - WorkspaceBindingNotFoundError, - WorkstreamConflictError, - WorkstreamNotFoundError, ) -from powercontext.builtin.handoff_report.models import ( - ExternalReference as ReportExternalReference, -) -from powercontext.builtin.handoff_report.models import ( - ProjectDescriptor as DomainProjectDescriptor, -) -from powercontext.builtin.handoff_report.models import ReportActivityEvent as DomainReportActivityEvent -from powercontext.builtin.handoff_report.models import RepositoryRef as DomainRepositoryRef -from powercontext.builtin.handoff_report.models import ( - WorkstreamDescriptor as DomainWorkstreamDescriptor, +from powercontext.builtin.inference.errors import InferenceTimeoutError, InferenceUnavailableError +from powercontext.builtin.publication import ( + ArtifactPublicationApplication, + ArtifactPublicationConflictError, ) -from powercontext.builtin.handoff_report.repository import ( - ActivityEventConflictError, - InvalidActivityEventError, - InvalidActivityRepositoryArgumentError, +from powercontext.builtin.publication import ( + ArtifactPublicationRequest as DomainArtifactPublicationRequest, ) -from powercontext.builtin.inference.errors import InferenceTimeoutError, InferenceUnavailableError from powercontext.builtin.review import ( ArtifactTargetConflictError, CandidateConflictError, @@ -193,6 +174,28 @@ from powercontext.builtin.runtime import ( StatisticsPeriod as RuntimeStatisticsPeriod, ) +from powercontext.builtin.scope import ( + ScopeApplication, + ScopeBindingNotFoundError, + ScopeDraft, + ScopeIdempotencyConflictError, + ScopeMutation, + ScopeNotFoundError, + ScopeRelationshipError, + ScopeVersionConflictError, +) +from powercontext.builtin.scope import ( + ScopeBindingKey as DomainScopeBindingKey, +) +from powercontext.builtin.scope import ( + ScopeDescriptor as DomainScopeDescriptor, +) +from powercontext.builtin.scope import ( + ScopeExternalReference as DomainScopeExternalReference, +) +from powercontext.builtin.scope import ( + ScopeSelection as DomainScopeSelection, +) from powercontext.builtin.work import ( AcknowledgeHandoff as RuntimeAcknowledgeHandoff, ) @@ -220,16 +223,16 @@ ApproveArtifactCandidateRequest, ArtifactCandidate, ArtifactCandidatePage, - AttachHandoffReportWorkspaceRequest, Capabilities, CaptureContentSourceRequest, CaptureContentSourceResponse, + ClearScopeBindingRequest, + ClearScopeBindingResponse, CommitHandoffRequest, CommittedHandoff, ContinueHandoffRequest, - CreateHandoffReportProjectRequest, + CreateScopeRequest, CreateWorkContractRequest, - DetachHandoffReportWorkspaceRequest, ErrorDetail, ErrorResponse, ExperienceArtifact, @@ -242,30 +245,19 @@ GenerateSkillRequest, GetArtifactCandidateRequest, GetExperienceRequest, - GetHandoffReportProjectRequest, GetHandoffReportRequest, - GetHandoffReportWorkspaceRequest, GetMemoryEntryRequest, GetSkillRequest, GetStatsRequest, HandoffAcknowledgement, HandoffCurrentWorkRequest, - HandoffReportActivity, - HandoffReportActivityPage, HandoffReportResponse, - HandoffReportWorkspaceBinding, HandoffSelection, HealthResponse, ImportExternalSkillRequest, - KnownHandoffScope, - KnownHandoffScopePage, ListArtifactCandidatesRequest, ListExternalSkillsRequest, ListExternalSkillsResponse, - ListHandoffReportActivitiesRequest, - ListHandoffReportKnownScopesRequest, - ListHandoffReportProjectsRequest, - ListHandoffReportWorkstreamsRequest, ListMemoryChangesRequest, ListMemoryChangesResponse, ListMemoryEntriesRequest, @@ -276,35 +268,38 @@ PreparedContext, PreparedWorkHandoff, PrepareHandoffRequest, - ProjectDescriptor, - ProjectPage, ProposeExperienceRequest, ProposeSkillRequest, - PurgeHandoffReportActivitiesRequest, - PurgeHandoffReportActivitiesResponse, + PublishArtifactRequest, ReadinessResponse, ReadinessStatus, - RecordHandoffReportActivityRequest, RecordTaskOutcomeRequest, - RegisterHandoffReportWorkstreamRequest, RejectArtifactCandidateRequest, RememberMemoryRequest, ResolveExternalSkillRequest, + ResolveScopeBindingRequest, + ResolveScopeSelectionRequest, RetireMemoryEntryRequest, ReviseArtifactCandidateRequest, ReviseMemoryEntryRequest, ScanExternalSkillsRequest, ScanExternalSkillsResponse, + ScopeBinding, + ScopeBindingKey, + ScopeDescriptor, ScopedStats, + ScopePage, + ScopeSelection, SearchMemoryRequest, SearchMemoryResponse, + SetDefaultScopeRequest, + SetScopeBindingRequest, SkillArtifact, - StoredHandoffReportActivity, - UpdateHandoffReportProjectRequest, - UpdateHandoffReportWorkstreamRequest, + UpdateScopeRequest, WorkSourceReceipt, - WorkstreamDescriptor, - WorkstreamPage, +) +from powercontext.http import ( + ArtifactPublication as TransportArtifactPublication, ) from powercontext.http import ( HandoffActivation as TransportHandoffActivation, @@ -325,57 +320,54 @@ API_TITLE, API_VERSION, APPROVE_ARTIFACT_CANDIDATE, - ATTACH_HANDOFF_REPORT_WORKSPACE, CAPTURE_CONTENT_SOURCE, + CLEAR_SCOPE_BINDING, COMMIT_HANDOFF, CONTINUE_HANDOFF, - CREATE_HANDOFF_REPORT_PROJECT, + CREATE_SCOPE, CREATE_WORK_CONTRACT, - DETACH_HANDOFF_REPORT_WORKSPACE, FINALIZE_HANDOFF, FLUSH_MEMORY, GENERATE_EXPERIENCE, GENERATE_SKILL, GET_ARTIFACT_CANDIDATE, GET_CAPABILITIES, + GET_DEFAULT_SCOPE, GET_EXPERIENCE, GET_HANDOFF_REPORT, - GET_HANDOFF_REPORT_PROJECT, - GET_HANDOFF_REPORT_WORKSPACE, GET_LIVENESS, GET_MEMORY_ENTRY, GET_READINESS, + GET_SCOPE, GET_SKILL, GET_STATS, HANDOFF_CURRENT_WORK, IMPORT_EXTERNAL_SKILL, LIST_ARTIFACT_CANDIDATES, LIST_EXTERNAL_SKILLS, - LIST_HANDOFF_REPORT_ACTIVITIES, - LIST_HANDOFF_REPORT_KNOWN_SCOPES, - LIST_HANDOFF_REPORT_PROJECTS, - LIST_HANDOFF_REPORT_WORKSTREAMS, LIST_MEMORY_CHANGES, LIST_MEMORY_ENTRIES, + LIST_SCOPES, OPENAPI_VERSION, PREPARE_CONTEXT, PREPARE_HANDOFF, PROPOSE_EXPERIENCE, PROPOSE_SKILL, - PURGE_HANDOFF_REPORT_ACTIVITIES, - RECORD_HANDOFF_REPORT_ACTIVITY, + PUBLISH_ARTIFACT, RECORD_TASK_OUTCOME, - REGISTER_HANDOFF_REPORT_WORKSTREAM, REJECT_ARTIFACT_CANDIDATE, REMEMBER_MEMORY, RESOLVE_EXTERNAL_SKILL, + RESOLVE_SCOPE_BINDING, + RESOLVE_SCOPE_SELECTION, RETIRE_MEMORY_ENTRY, REVISE_ARTIFACT_CANDIDATE, REVISE_MEMORY_ENTRY, SCAN_EXTERNAL_SKILLS, SEARCH_MEMORY, - UPDATE_HANDOFF_REPORT_PROJECT, - UPDATE_HANDOFF_REPORT_WORKSTREAM, + SET_DEFAULT_SCOPE, + SET_SCOPE_BINDING, + UPDATE_SCOPE, Operation, ) from powercontext.http._generated.schema import OPENAPI_SCHEMA @@ -402,6 +394,7 @@ ReadinessProbe = Callable[[], Awaitable[ReadinessResponse]] _RequestT = TypeVar("_RequestT") _ResponseT = TypeVar("_ResponseT") +_ScopePathId = Annotated[str, PathParameter(min_length=1, max_length=256, pattern=r".*\S.*")] class _ScopedSourceApplication(Protocol): @@ -537,8 +530,17 @@ async def overview(self, *, period: RuntimeStatisticsPeriod) -> RuntimeStatistic class _StatisticsApplication(Protocol): def for_scope(self, scope_id: str, /) -> _ScopedStatisticsApplication: ... + async def overview( + self, + selection: DomainScopeSelection, + *, + period: RuntimeStatisticsPeriod, + ) -> RuntimeStatistics: ... + class ServerApplication(Protocol): + scopes: ScopeApplication | None + publications: ArtifactPublicationApplication | None sources: _SourceApplication context: _ContextApplication experience: _ExperienceApplication @@ -610,7 +612,11 @@ async def attach_request_id(request: Request, call_next: RequestResponseEndpoint return response @app.exception_handler(RequestValidationError) - async def invalid_request(request: Request, error: RequestValidationError) -> JSONResponse: + @app.exception_handler(PydanticValidationError) + async def invalid_request( + request: Request, + error: RequestValidationError | PydanticValidationError, + ) -> JSONResponse: return _error_response( status.HTTP_422_UNPROCESSABLE_CONTENT, code="invalid_request", @@ -639,22 +645,19 @@ async def unexpected_error(request: Request, error: Exception) -> JSONResponse: _add_route(app, GET_LIVENESS, get_liveness) _add_route(app, GET_READINESS, get_readiness) _add_route(app, GET_CAPABILITIES, get_capabilities) + _add_route(app, LIST_SCOPES, list_scopes) + _add_route(app, CREATE_SCOPE, create_scope) + _add_route(app, GET_DEFAULT_SCOPE, get_default_scope) + _add_route(app, SET_DEFAULT_SCOPE, set_default_scope) + _add_route(app, GET_SCOPE, get_scope) + _add_route(app, UPDATE_SCOPE, update_scope) + _add_route(app, RESOLVE_SCOPE_SELECTION, resolve_scope_selection) + _add_route(app, RESOLVE_SCOPE_BINDING, resolve_scope_binding) + _add_route(app, SET_SCOPE_BINDING, set_scope_binding) + _add_route(app, CLEAR_SCOPE_BINDING, clear_scope_binding) + _add_route(app, PUBLISH_ARTIFACT, publish_artifact) _add_route(app, GET_STATS, get_stats) if handoff_report_enabled: - _add_route(app, CREATE_HANDOFF_REPORT_PROJECT, create_handoff_report_project) - _add_route(app, GET_HANDOFF_REPORT_PROJECT, get_handoff_report_project) - _add_route(app, UPDATE_HANDOFF_REPORT_PROJECT, update_handoff_report_project) - _add_route(app, LIST_HANDOFF_REPORT_PROJECTS, list_handoff_report_projects) - _add_route(app, LIST_HANDOFF_REPORT_KNOWN_SCOPES, list_handoff_report_known_scopes) - _add_route(app, REGISTER_HANDOFF_REPORT_WORKSTREAM, register_handoff_report_workstream) - _add_route(app, LIST_HANDOFF_REPORT_WORKSTREAMS, list_handoff_report_workstreams) - _add_route(app, UPDATE_HANDOFF_REPORT_WORKSTREAM, update_handoff_report_workstream) - _add_route(app, RECORD_HANDOFF_REPORT_ACTIVITY, record_handoff_report_activity) - _add_route(app, LIST_HANDOFF_REPORT_ACTIVITIES, list_handoff_report_activities) - _add_route(app, PURGE_HANDOFF_REPORT_ACTIVITIES, purge_handoff_report_activities) - _add_route(app, GET_HANDOFF_REPORT_WORKSPACE, get_handoff_report_workspace) - _add_route(app, ATTACH_HANDOFF_REPORT_WORKSPACE, attach_handoff_report_workspace) - _add_route(app, DETACH_HANDOFF_REPORT_WORKSPACE, detach_handoff_report_workspace) _add_route(app, GET_HANDOFF_REPORT, get_handoff_report) _add_route(app, CAPTURE_CONTENT_SOURCE, capture_content_source) _add_route(app, FLUSH_MEMORY, flush_memory) @@ -748,192 +751,141 @@ async def get_capabilities(request: Request) -> Capabilities: return request.app.state.capabilities -async def get_stats( - request: Annotated[GetStatsRequest, Query()], - response: Response, - application: Annotated[ServerApplication, Depends(_require_application)], -) -> ScopedStats: - response.headers["Cache-Control"] = "no-store" - result = await application.statistics.for_scope(request.scope_id).overview( - period=RuntimeStatisticsPeriod(request.period.value) +async def list_scopes( + scopes: Annotated[ScopeApplication, Depends(_require_scope_application)], +) -> ScopePage: + return ScopePage(items=[_scope_descriptor_response(scope) for scope in await scopes.list()]) + + +async def create_scope( + request: CreateScopeRequest, + scopes: Annotated[ScopeApplication, Depends(_require_scope_application)], +) -> ScopeDescriptor: + created = await scopes.create( + ScopeDraft( + title=request.title, + summary=request.summary, + parent_scope_id=request.parent_scope_id, + context_references=tuple(reference.root for reference in request.context_references), + external_references=tuple( + DomainScopeExternalReference(kind=reference.kind, value=reference.value) + for reference in request.external_references + ), + idempotency_key=request.idempotency_key, + ) ) - return mapping.statistics_response(result) - - -async def create_handoff_report_project( - request: CreateHandoffReportProjectRequest, - report: Annotated[HandoffReportApplication, Depends(_require_handoff_report_application)], -) -> ProjectDescriptor: - result = await report.create_project( - project_key=request.project_key, - title=request.title, - description=request.description, - default_locale=request.default_locale.value, - timezone=request.timezone, + return _scope_descriptor_response(created) + + +async def get_scope( + scope_id: _ScopePathId, + scopes: Annotated[ScopeApplication, Depends(_require_scope_application)], +) -> ScopeDescriptor: + return _scope_descriptor_response(await scopes.get(scope_id)) + + +async def update_scope( + scope_id: _ScopePathId, + request: UpdateScopeRequest, + scopes: Annotated[ScopeApplication, Depends(_require_scope_application)], +) -> ScopeDescriptor: + updated = await scopes.update( + scope_id, + ScopeMutation( + expected_version=request.expected_version, + title=request.title, + summary=request.summary, + parent_scope_id=request.parent_scope_id, + context_references=tuple(reference.root for reference in request.context_references), + external_references=tuple( + DomainScopeExternalReference(kind=reference.kind, value=reference.value) + for reference in request.external_references + ), + ), ) - return _project_descriptor_response(result) + return _scope_descriptor_response(updated) -async def get_handoff_report_project( - request: GetHandoffReportProjectRequest, - report: Annotated[HandoffReportApplication, Depends(_require_handoff_report_application)], -) -> ProjectDescriptor: - return _project_descriptor_response(await report.get_project(request.project_id)) +async def get_default_scope( + scopes: Annotated[ScopeApplication, Depends(_require_scope_application)], +) -> ScopeDescriptor: + current = await scopes.default_scope() + if current is None: + raise ScopeBindingNotFoundError + return _scope_descriptor_response(current) -async def update_handoff_report_project( - request: UpdateHandoffReportProjectRequest, - report: Annotated[HandoffReportApplication, Depends(_require_handoff_report_application)], -) -> ProjectDescriptor: - descriptor = DomainProjectDescriptor.model_validate_json(request.project.model_dump_json(by_alias=True)) - return _project_descriptor_response(await report.update_project(descriptor, request.expected_version)) +async def set_default_scope( + request: SetDefaultScopeRequest, + scopes: Annotated[ScopeApplication, Depends(_require_scope_application)], +) -> ScopeDescriptor: + return _scope_descriptor_response(await scopes.set_default(request.scope_id)) -async def list_handoff_report_projects( - request: ListHandoffReportProjectsRequest, - report: Annotated[HandoffReportApplication, Depends(_require_handoff_report_application)], -) -> ProjectPage: - result = await report.list_projects( - cursor=request.cursor, - limit=request.limit, - include_archived=request.include_archived, - ) - return ProjectPage( - items=[_project_descriptor_response(item) for item in result.items], - next_cursor=result.next_cursor, - ) +async def resolve_scope_selection( + request: ResolveScopeSelectionRequest, + scopes: Annotated[ScopeApplication, Depends(_require_scope_application)], +) -> ScopePage: + selection = _domain_scope_selection(request.selection) + return ScopePage(items=[_scope_descriptor_response(scope) for scope in await scopes.resolve_selection(selection)]) -async def list_handoff_report_known_scopes( - request: ListHandoffReportKnownScopesRequest, - report: Annotated[HandoffReportApplication, Depends(_require_handoff_report_application)], -) -> KnownHandoffScopePage: - result = await report.list_known_scopes(cursor=request.cursor, limit=request.limit) - return KnownHandoffScopePage( - items=[KnownHandoffScope(scope_id=scope_id) for scope_id in result.items], - next_cursor=result.next_cursor, +async def resolve_scope_binding( + request: ResolveScopeBindingRequest, + scopes: Annotated[ScopeApplication, Depends(_require_scope_application)], +) -> ScopeDescriptor: + resolved = await scopes.resolve_binding( + explicit_scope_id=request.explicit_scope_id, + binding_keys=tuple(_domain_binding_key(key) for key in request.binding_keys), ) + return _scope_descriptor_response(resolved) -async def register_handoff_report_workstream( - request: RegisterHandoffReportWorkstreamRequest, - report: Annotated[HandoffReportApplication, Depends(_require_handoff_report_application)], -) -> WorkstreamDescriptor: - values = request.model_dump(mode="json") - result = await report.register_workstream( - project_id=request.project_id, - scope_id=request.scope_id, - title=request.title, - kind=request.kind.value, - key=request.key, - catalog_state=request.catalog_state.value, - external_refs=tuple(ReportExternalReference.model_validate(value) for value in values["external_refs"]), - labels=tuple(str(value) for value in values["labels"]), +async def set_scope_binding( + request: SetScopeBindingRequest, + scopes: Annotated[ScopeApplication, Depends(_require_scope_application)], +) -> ScopeBinding: + binding = await scopes.bind(_domain_binding_key(request.root.key), request.root.scope_id) + return ScopeBinding( + key=_transport_binding_key(binding.key), + scope_id=binding.scope_id, ) - return _workstream_descriptor_response(result) -async def list_handoff_report_workstreams( - request: ListHandoffReportWorkstreamsRequest, - report: Annotated[HandoffReportApplication, Depends(_require_handoff_report_application)], -) -> WorkstreamPage: - result = await report.list_workstreams( - request.project_id, - cursor=request.cursor, - limit=request.limit, - include_archived=request.include_archived, - ) - return WorkstreamPage( - items=[_workstream_descriptor_response(item) for item in result.items], - next_cursor=result.next_cursor, - ) - - -async def update_handoff_report_workstream( - request: UpdateHandoffReportWorkstreamRequest, - report: Annotated[HandoffReportApplication, Depends(_require_handoff_report_application)], -) -> WorkstreamDescriptor: - descriptor = DomainWorkstreamDescriptor.model_validate_json(request.workstream.model_dump_json(by_alias=True)) - return _workstream_descriptor_response(await report.update_workstream(descriptor, request.expected_version)) - - -async def record_handoff_report_activity( - request: RecordHandoffReportActivityRequest, - report: Annotated[HandoffReportApplication, Depends(_require_handoff_report_application)], -) -> StoredHandoffReportActivity: - values = request.model_dump(mode="json") - event = DomainReportActivityEvent.model_validate_json( - json.dumps({ - **values, - "event_id": f"evt_{uuid4().hex}", - "observed_at": datetime.now(UTC).isoformat(), - "trust": "untrusted_observation", - }) - ) - stored = await report.record_activity(event) - return StoredHandoffReportActivity( - cursor=stored.cursor, - event=HandoffReportActivity.model_validate(stored.payload), - ) - - -async def list_handoff_report_activities( - request: ListHandoffReportActivitiesRequest, - report: Annotated[HandoffReportApplication, Depends(_require_handoff_report_application)], -) -> HandoffReportActivityPage: - page = await report.list_activities( - request.project_id, - period_start=request.period_start, - period_end=request.period_end, - sources=None if request.sources is None else tuple(value.value for value in request.sources), - after_cursor=request.after_cursor, - through_cursor=request.through_cursor, - limit=request.limit, - ) - return HandoffReportActivityPage( - items=[ - HandoffReportActivity.model_validate(item.model_dump(mode="json", by_alias=True)) for item in page.items - ], - next_cursor=page.next_cursor, - high_watermark=page.high_watermark, +async def clear_scope_binding( + request: ClearScopeBindingRequest, + scopes: Annotated[ScopeApplication, Depends(_require_scope_application)], +) -> ClearScopeBindingResponse: + return ClearScopeBindingResponse(cleared=await scopes.clear_binding(_domain_binding_key(request.key))) + + +async def publish_artifact( + request: PublishArtifactRequest, + publications: Annotated[ArtifactPublicationApplication, Depends(_require_publication_application)], +) -> TransportArtifactPublication: + result = await publications.publish( + DomainArtifactPublicationRequest( + source=ArtifactAddress( + scope_id=request.source.scope_id, + artifact=ArtifactRef.model_validate(request.source.artifact.model_dump(mode="json")), + ), + target_scope_id=request.target_scope_id, + idempotency_key=request.idempotency_key, + ) ) + return TransportArtifactPublication.model_validate(result.model_dump(mode="json")) -async def purge_handoff_report_activities( - request: PurgeHandoffReportActivitiesRequest, - report: Annotated[HandoffReportApplication, Depends(_require_handoff_report_application)], -) -> PurgeHandoffReportActivitiesResponse: - deleted = await report.purge_activities(request.project_id, request.observed_before) - return PurgeHandoffReportActivitiesResponse(deleted_count=deleted) - - -async def get_handoff_report_workspace( - request: GetHandoffReportWorkspaceRequest, - report: Annotated[HandoffReportApplication, Depends(_require_handoff_report_application)], -) -> HandoffReportWorkspaceBinding: - binding = await report.get_workspace_binding(request.workspace_instance_id) - return HandoffReportWorkspaceBinding.model_validate(binding.model_dump(mode="json", by_alias=True)) - - -async def attach_handoff_report_workspace( - request: AttachHandoffReportWorkspaceRequest, - report: Annotated[HandoffReportApplication, Depends(_require_handoff_report_application)], -) -> HandoffReportWorkspaceBinding: - binding = await report.attach_workspace_binding( - workspace_instance_id=request.workspace_instance_id, - project_id=request.project_id, - repository_ref=DomainRepositoryRef.model_validate(request.repository_ref.model_dump(mode="json")), - expected_version=request.expected_version, +async def get_stats( + request: GetStatsRequest, + response: Response, + application: Annotated[ServerApplication, Depends(_require_application)], +) -> ScopedStats: + response.headers["Cache-Control"] = "no-store" + result = await application.statistics.overview( + _domain_scope_selection(request.selection), period=RuntimeStatisticsPeriod(request.period.value) ) - return HandoffReportWorkspaceBinding.model_validate(binding.model_dump(mode="json", by_alias=True)) - - -async def detach_handoff_report_workspace( - request: DetachHandoffReportWorkspaceRequest, - report: Annotated[HandoffReportApplication, Depends(_require_handoff_report_application)], -) -> HandoffReportWorkspaceBinding: - binding = await report.detach_workspace_binding(request.workspace_instance_id, request.expected_version) - return HandoffReportWorkspaceBinding.model_validate(binding.model_dump(mode="json", by_alias=True)) + return mapping.statistics_response(result) async def get_handoff_report( @@ -941,23 +893,7 @@ async def get_handoff_report( response: Response, report: Annotated[HandoffReportApplication, Depends(_require_handoff_report_application)], ) -> HandoffReportResponse | Response: - result = await report.get_report( - request.scope_id, - locale=None if request.locale is None else request.locale.value, - include_evidence_checks=request.include_evidence_checks, - report_format=request.format.value, - include_archived=request.include_archived, - period=( - None - if request.period is None - else ReportPeriodInput( - start=request.period.start, - end=request.period.end, - timezone=request.period.timezone, - compare_to_previous_period=request.period.compare_to_previous_period, - ) - ), - ) + result = await report.get_report(_domain_scope_selection(request.selection)) selection_digest = cast(str, result.selection_digest) report_digest = cast(str, result.report_digest) response.headers["Cache-Control"] = "no-store" @@ -1007,8 +943,7 @@ def _require_report_size(estimated_bytes: int, report: Any) -> None: return raise HandoffReportTooLargeError( estimated_bytes=estimated_bytes, - selected_workstreams=report.coverage.selected_workstreams, - selected_activities=len(report.activity_selection), + selected_scopes=len(report.scopes), ) @@ -1352,6 +1287,20 @@ def _require_application(request: Request) -> ServerApplication: return application +def _require_scope_application(request: Request) -> ScopeApplication: + application = _require_application(request) + if application.scopes is None: + raise _RuntimeNotReadyError + return application.scopes + + +def _require_publication_application(request: Request) -> ArtifactPublicationApplication: + application = _require_application(request) + if application.publications is None: + raise _RuntimeNotReadyError + return application.publications + + def _require_handoff_report_application(request: Request) -> HandoffReportApplication: application = _require_application(request) if application.handoff_report is None: @@ -1359,12 +1308,28 @@ def _require_handoff_report_application(request: Request) -> HandoffReportApplic return application.handoff_report -def _project_descriptor_response(value: DomainProjectDescriptor) -> ProjectDescriptor: - return ProjectDescriptor.model_validate(value.model_dump(mode="json", by_alias=True)) +def _scope_descriptor_response(value: DomainScopeDescriptor) -> ScopeDescriptor: + return ScopeDescriptor.model_validate(value.model_dump(mode="json")) + + +def _domain_binding_key(value: ScopeBindingKey) -> DomainScopeBindingKey: + return DomainScopeBindingKey( + integration=value.integration, + kind=value.kind, + external_id=value.external_id, + ) + + +def _domain_scope_selection(value: ScopeSelection) -> DomainScopeSelection: + return DomainScopeSelection.model_validate(value.root.model_dump(mode="json")) -def _workstream_descriptor_response(value: DomainWorkstreamDescriptor) -> WorkstreamDescriptor: - return WorkstreamDescriptor.model_validate(value.model_dump(mode="json", by_alias=True)) +def _transport_binding_key(value: DomainScopeBindingKey) -> ScopeBindingKey: + return ScopeBindingKey( + integration=value.integration, + kind=value.kind, + external_id=value.external_id, + ) def _add_route( @@ -1395,6 +1360,7 @@ async def observed_endpoint(*args: Any, **kwargs: Any) -> _ResponseT | Response: started_at = perf_counter() span = _start_application_span(app, operation) try: + await _validate_current_scope(app, operation, args, kwargs) result = await endpoint(*args, **kwargs) except asyncio.CancelledError: _observe_application(app, operation, "cancelled", started_at) @@ -1429,6 +1395,26 @@ async def observed_endpoint(*args: Any, **kwargs: Any) -> _ResponseT | Response: return observed_endpoint +async def _validate_current_scope( + app: FastAPI, + operation: Operation[Any, Any], + args: tuple[Any, ...], + kwargs: dict[str, Any], +) -> None: + if operation.scope_mode != "current" or operation.request_type is None: + return + scopes = getattr(app.state.application, "scopes", None) + if scopes is None: + return + request = next( + (value for value in (*args, *kwargs.values()) if isinstance(value, operation.request_type)), + None, + ) + scope_id = getattr(request, "scope_id", None) + if isinstance(scope_id, str): + await scopes.get(scope_id) + + def _start_application_span(app: FastAPI, operation: Operation[Any, Any]) -> Any | None: if "health" in operation.tags: return None @@ -1506,11 +1492,11 @@ def _error_response( return JSONResponse(status_code=response_status, content=error.model_dump(mode="json")) -def _validation_error_details(error: RequestValidationError) -> list[Any]: +def _validation_error_details(error: RequestValidationError | PydanticValidationError) -> list[Any]: details: list[Any] = [] for item in error.errors(): if isinstance(item, dict): - details.append({key: value for key, value in item.items() if key != "input"}) + details.append({key: value for key, value in item.items() if key not in {"ctx", "input", "url"}}) else: details.append(item) return details @@ -1542,6 +1528,9 @@ def _map_error(error: Exception) -> tuple[int, str, str, dict[str, Any] | None]: "Artifact generation is not configured.", {"family": error.family}, ) + scope_error = _map_scope_error(error) + if scope_error is not None: + return scope_error candidate_error = _map_candidate_error(error) if candidate_error is not None: return candidate_error @@ -1554,6 +1543,40 @@ def _map_error(error: Exception) -> tuple[int, str, str, dict[str, Any] | None]: return _map_domain_error(error) +def _map_scope_error(error: Exception) -> tuple[int, str, str, dict[str, Any] | None] | None: + if isinstance(error, ArtifactPublicationConflictError): + return ( + status.HTTP_409_CONFLICT, + "artifact_publication_conflict", + "The publication key identifies a different source Artifact.", + None, + ) + if isinstance(error, (ScopeNotFoundError, ScopeBindingNotFoundError)): + return status.HTTP_404_NOT_FOUND, "scope_not_found", "The requested Scope was not found.", None + if isinstance(error, ScopeVersionConflictError): + return ( + status.HTTP_409_CONFLICT, + "scope_version_conflict", + "The Scope metadata version is stale.", + {"expected_version": error.expected, "current_version": error.actual}, + ) + if isinstance(error, ScopeIdempotencyConflictError): + return ( + status.HTTP_409_CONFLICT, + "scope_idempotency_conflict", + "The Scope creation key identifies different parameters.", + None, + ) + if isinstance(error, ScopeRelationshipError): + return ( + status.HTTP_422_UNPROCESSABLE_CONTENT, + "invalid_scope_relationship", + "The Scope relationship is invalid.", + {"relationship": error.relationship, "issue": error.issue}, + ) + return None + + def _map_candidate_error(error: Exception) -> tuple[int, str, str, dict[str, Any] | None] | None: if isinstance(error, CandidateNotFoundError): return status.HTTP_404_NOT_FOUND, "candidate_not_found", "The requested Candidate was not found.", None @@ -1584,46 +1607,14 @@ def _map_candidate_error(error: Exception) -> tuple[int, str, str, dict[str, Any def _map_report_error(error: Exception) -> tuple[int, str, str, dict[str, Any] | None] | None: - if isinstance(error, (ProjectNotFoundError, WorkstreamNotFoundError, WorkspaceBindingNotFoundError)): - return status.HTTP_404_NOT_FOUND, error.code, "The requested Handoff Report catalog value was not found.", None - if isinstance( - error, - (ProjectConflictError, WorkstreamConflictError, ScopeAlreadyGroupedError, WorkspaceBindingConflictError), - ): - details = { - name: getattr(error, name) - for name in ("expected_version", "current_version", "project_id", "scope_id", "workspace_instance_id") - if hasattr(error, name) - } - return ( - status.HTTP_409_CONFLICT, - error.code, - "The Handoff Report catalog value is stale or conflicting.", - details, - ) - if isinstance(error, ActivityEventConflictError): - return ( - status.HTTP_409_CONFLICT, - "activity_event_conflict", - "The Activity idempotency key already identifies different content.", - {"source": error.source, "source_event_id": error.source_event_id}, - ) - if isinstance(error, HandoffReportBusyError): - return ( - status.HTTP_409_CONFLICT, - "handoff_report_busy", - "Handoff heads changed while the report was being assembled.", - {"attempts": error.attempts}, - ) if isinstance(error, HandoffReportTooLargeError): return ( status.HTTP_413_CONTENT_TOO_LARGE, "handoff_report_too_large", - "The Handoff Report is too large; narrow the Workstream or Activity selection.", + "The Handoff Report is too large; narrow the Scope selection.", { "estimated_bytes": error.estimated_bytes, - "selected_workstreams": error.selected_workstreams, - "selected_activities": error.selected_activities, + "selected_scopes": error.selected_scopes, }, ) if isinstance(error, HandoffReportInconsistentError): @@ -1633,11 +1624,6 @@ def _map_report_error(error: Exception) -> tuple[int, str, str, dict[str, Any] | "The frozen Handoff selection could not be read consistently.", {"scope_id": error.scope_id}, ) - if isinstance( - error, - (HandoffReportCatalogArgumentError, InvalidActivityEventError, InvalidActivityRepositoryArgumentError), - ): - return status.HTTP_422_UNPROCESSABLE_CONTENT, "invalid_request", "The request is invalid.", None if isinstance(error, HandoffReportError): return status.HTTP_503_SERVICE_UNAVAILABLE, "handoff_report_unavailable", "Handoff Report is unavailable.", None return None diff --git a/src/powercontext/server/factory.py b/src/powercontext/server/factory.py index 563b0ab4c..cec366f2d 100644 --- a/src/powercontext/server/factory.py +++ b/src/powercontext/server/factory.py @@ -183,7 +183,6 @@ def _mount_optional_web_ui(app: FastAPI, settings: ServerSettings) -> None: try: mount_web_ui( app, - scopes={scope.scope_id: scope.display_name for scope in settings.dashboard.scopes}, dashboard_enabled=settings.dashboard.enabled, handoff_report_enabled=settings.handoff_report.enabled, authentication_required=settings.auth.enabled, diff --git a/src/powercontext/server/handoff_picker.py b/src/powercontext/server/handoff_picker.py deleted file mode 100644 index 9cebcbd02..000000000 --- a/src/powercontext/server/handoff_picker.py +++ /dev/null @@ -1,505 +0,0 @@ -# Copyright (c) 2026 OceanBase. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -# ruff: noqa: RUF001 -"""Interactive MCP selection for one Handoff Report Workstream.""" - -from __future__ import annotations - -from collections.abc import Callable, Sequence -from dataclasses import dataclass -from typing import Annotated, Generic, Literal, TypeVar, cast - -import httpx -from fastmcp import Context, FastMCP -from fastmcp.server.elicitation import AcceptedElicitation -from mcp.types import ClientCapabilities, ElicitationCapability, ToolAnnotations -from pydantic import BaseModel, ConfigDict, Field - -from powercontext.client import PowerContextClient -from powercontext.http import ( - ListHandoffReportProjectsRequest, - ListHandoffReportWorkstreamsRequest, - ProjectDescriptor, - WorkstreamDescriptor, -) - -PickerLocale = Literal["zh-CN", "en"] -PickerStatus = Literal["selected", "needs_selection", "empty", "cancelled", "declined"] -PickerStage = Literal["project", "workstream"] - -_MAX_PICKER_CHOICES = 100 -_FORM_ELICITATION_CAPABILITY = ClientCapabilities(elicitation=ElicitationCapability()) -_ChoiceT = TypeVar("_ChoiceT") - - -class HandoffProjectChoice(BaseModel): - """One project that can be used to narrow the Workstream picker.""" - - model_config = ConfigDict(extra="forbid", frozen=True) - - project_id: str - project_key: str - title: str - - -class HandoffWorkstreamChoice(BaseModel): - """One validated Workstream selection returned to an Agent.""" - - model_config = ConfigDict(extra="forbid", frozen=True) - - work_id: str - scope_id: str - project_id: str - project_key: str - title: str - kind: str - catalog_version: int - - -class HandoffWorkstreamSelection(BaseModel): - """Stable result for native and text-fallback selection flows.""" - - model_config = ConfigDict(extra="forbid", frozen=True) - - status: PickerStatus - message: str - stage: PickerStage | None = None - selected: HandoffWorkstreamChoice | None = None - project_choices: list[HandoffProjectChoice] = Field(default_factory=list, max_length=_MAX_PICKER_CHOICES) - workstream_choices: list[HandoffWorkstreamChoice] = Field(default_factory=list, max_length=_MAX_PICKER_CHOICES) - truncated: bool = False - - -def register_handoff_workstream_picker(server: FastMCP, http_client: httpx.AsyncClient) -> None: - """Register the Report-backed Workstream picker on an existing MCP server.""" - - # ``http_client`` is the Server's own in-process ASGI transport; ``http://fastapi`` is only a - # routing label, so vouch for it explicitly rather than have the loopback guard reject it. - picker = _HandoffWorkstreamPicker( - PowerContextClient("http://fastapi", http_client=http_client, trust_transport_security=True) - ) - server.tool( - picker.select, - name="select_handoff_workstream", - title="Select Handoff Workstream", - description=( - "Select one Report Workstream before handoff_current_work or continue_handoff. " - "Uses a native MCP picker when supported and returns validated structured choices otherwise." - ), - annotations=ToolAnnotations( - readOnlyHint=True, - destructiveHint=False, - idempotentHint=True, - openWorldHint=False, - ), - ) - - -class _HandoffWorkstreamPicker: - def __init__(self, client: PowerContextClient) -> None: - self._client = client - - async def select( - self, - ctx: Context, - project_id: Annotated[ - str | None, - Field( - default=None, - min_length=1, - max_length=256, - pattern=r".*\S.*", - description="Exact Report Project ID. Omit it to choose a Project interactively.", - ), - ] = None, - work_id: Annotated[ - str | None, - Field( - default=None, - min_length=1, - max_length=256, - pattern=r".*\S.*", - description="Workstream key or scope ID returned by an earlier picker result.", - ), - ] = None, - query: Annotated[ - str | None, - Field( - default=None, - min_length=1, - max_length=256, - pattern=r".*\S.*", - description="Optional case-insensitive filter over Workstream title, key, scope, kind, and labels.", - ), - ] = None, - include_archived: Annotated[ - bool, - Field(description="Include archived Projects and Workstreams in the choices."), - ] = False, - locale: Annotated[ - PickerLocale, - Field(description="Language used for picker prompts and result messages."), - ] = "zh-CN", - ) -> HandoffWorkstreamSelection: - """Select a catalog Workstream before handing off or continuing work. - - A client with MCP form elicitation gets a native picker. Other clients - receive structured choices and can call this tool again with project_id - and work_id. Selecting a Workstream never creates or commits a Handoff. - """ - - projects, projects_truncated = await _list_projects(self._client, include_archived=include_archived) - if not projects: - return _selection(status="empty", locale=locale, message_key="no_projects") - - project_result = await _choose_project( - ctx, - projects=projects, - project_id=project_id, - locale=locale, - truncated=projects_truncated, - ) - if isinstance(project_result, HandoffWorkstreamSelection): - return project_result - project = project_result - - workstreams, workstreams_truncated = await _list_workstreams( - self._client, - project.project_id, - include_archived=include_archived, - ) - filtered_workstreams = _filter_workstreams(workstreams, query) - choices = [_workstream_choice(item, project) for item in filtered_workstreams] - truncated = projects_truncated or workstreams_truncated - if not choices: - return _selection( - status="empty", - locale=locale, - message_key="no_matching_workstreams" if query else "no_workstreams", - stage="workstream", - truncated=truncated, - ) - - return await _choose_workstream( - ctx, - choices=choices, - work_id=work_id, - locale=locale, - truncated=truncated, - ) - - -@dataclass(frozen=True, slots=True) -class _ElicitedChoice(Generic[_ChoiceT]): - status: Literal["selected", "cancelled", "declined"] - value: _ChoiceT | None - - -async def _elicit_choice( - ctx: Context, - *, - message: str, - response_title: str, - values: Sequence[_ChoiceT], - title: Callable[[_ChoiceT], str], -) -> _ElicitedChoice[_ChoiceT]: - option_values = {f"option-{index + 1}": value for index, value in enumerate(values)} - options = {token: {"title": title(value)} for token, value in option_values.items()} - result = await ctx.elicit( - message, - options, - response_title=response_title, - ) - if not isinstance(result, AcceptedElicitation): - status: Literal["cancelled", "declined"] = "cancelled" if result.action == "cancel" else "declined" - return _ElicitedChoice(status=status, value=None) - selected_token = str(result.data) - return _ElicitedChoice(status="selected", value=option_values[selected_token]) - - -async def _choose_project( - ctx: Context, - *, - projects: Sequence[ProjectDescriptor], - project_id: str | None, - locale: PickerLocale, - truncated: bool, -) -> ProjectDescriptor | HandoffWorkstreamSelection: - project = _project_by_id(projects, project_id) - if project_id is not None and project is None: - return _selection( - status="needs_selection", - locale=locale, - message_key="project_not_found", - stage="project", - project_choices=[_project_choice(item) for item in projects], - truncated=truncated, - ) - if project is not None: - return project - if len(projects) == 1: - return projects[0] - if not _supports_form_elicitation(ctx): - return _selection( - status="needs_selection", - locale=locale, - message_key="choose_project_fallback", - stage="project", - project_choices=[_project_choice(item) for item in projects], - truncated=truncated, - ) - result = await _elicit_choice( - ctx, - message=_copy(locale, "choose_project"), - response_title=_copy(locale, "project_field"), - values=projects, - title=_project_title, - ) - if result.status != "selected": - return _selection( - status=result.status, - locale=locale, - message_key=result.status, - stage="project", - ) - return cast(ProjectDescriptor, result.value) - - -async def _choose_workstream( - ctx: Context, - *, - choices: Sequence[HandoffWorkstreamChoice], - work_id: str | None, - locale: PickerLocale, - truncated: bool, -) -> HandoffWorkstreamSelection: - selected = _workstream_by_id(choices, work_id) - if work_id is not None and selected is None: - return _selection( - status="needs_selection", - locale=locale, - message_key="workstream_not_found", - stage="workstream", - workstream_choices=list(choices), - truncated=truncated, - ) - if selected is None and len(choices) == 1: - selected = choices[0] - if selected is None and not _supports_form_elicitation(ctx): - return _selection( - status="needs_selection", - locale=locale, - message_key="choose_workstream_fallback", - stage="workstream", - workstream_choices=list(choices), - truncated=truncated, - ) - if selected is None: - result = await _elicit_choice( - ctx, - message=_copy(locale, "choose_workstream"), - response_title=_copy(locale, "workstream_field"), - values=choices, - title=_workstream_title, - ) - if result.status != "selected": - return _selection( - status=result.status, - locale=locale, - message_key=result.status, - stage="workstream", - ) - selected = cast(HandoffWorkstreamChoice, result.value) - return _selection( - status="selected", - locale=locale, - message_key="selected", - selected=selected, - truncated=truncated, - ) - - -async def _list_projects( - client: PowerContextClient, - *, - include_archived: bool, -) -> tuple[list[ProjectDescriptor], bool]: - page = await client.list_handoff_report_projects( - ListHandoffReportProjectsRequest( - limit=_MAX_PICKER_CHOICES, - include_archived=include_archived, - ) - ) - return page.items, page.next_cursor is not None - - -async def _list_workstreams( - client: PowerContextClient, - project_id: str, - *, - include_archived: bool, -) -> tuple[list[WorkstreamDescriptor], bool]: - page = await client.list_handoff_report_workstreams( - ListHandoffReportWorkstreamsRequest( - project_id=project_id, - limit=_MAX_PICKER_CHOICES, - include_archived=include_archived, - ) - ) - return page.items, page.next_cursor is not None - - -def _supports_form_elicitation(ctx: Context) -> bool: - return ctx.session.check_client_capability(_FORM_ELICITATION_CAPABILITY) - - -def _project_by_id(projects: Sequence[ProjectDescriptor], project_id: str | None) -> ProjectDescriptor | None: - if project_id is None: - return None - return next((project for project in projects if project.project_id == project_id), None) - - -def _workstream_by_id( - choices: Sequence[HandoffWorkstreamChoice], - work_id: str | None, -) -> HandoffWorkstreamChoice | None: - if work_id is None: - return None - matches = [choice for choice in choices if choice.work_id == work_id or choice.scope_id == work_id] - return matches[0] if len(matches) == 1 else None - - -def _filter_workstreams( - workstreams: Sequence[WorkstreamDescriptor], - query: str | None, -) -> list[WorkstreamDescriptor]: - normalized_query = "" if query is None else query.strip().casefold() - if not normalized_query: - return list(workstreams) - return [workstream for workstream in workstreams if normalized_query in _workstream_search_text(workstream)] - - -def _workstream_search_text(workstream: WorkstreamDescriptor) -> str: - values = ( - workstream.title, - workstream.key or "", - workstream.scope_id, - str(workstream.kind), - *(label.root for label in workstream.labels), - ) - return "\n".join(values).casefold() - - -def _project_choice(project: ProjectDescriptor) -> HandoffProjectChoice: - return HandoffProjectChoice( - project_id=project.project_id, - project_key=project.project_key, - title=project.title, - ) - - -def _workstream_choice( - workstream: WorkstreamDescriptor, - project: ProjectDescriptor, -) -> HandoffWorkstreamChoice: - return HandoffWorkstreamChoice( - work_id=workstream.key or workstream.scope_id, - scope_id=workstream.scope_id, - project_id=project.project_id, - project_key=project.project_key, - title=workstream.title, - kind=str(workstream.kind), - catalog_version=workstream.version, - ) - - -def _project_title(project: ProjectDescriptor) -> str: - return f"{project.title} · {project.project_key}" - - -def _workstream_title(workstream: HandoffWorkstreamChoice) -> str: - return f"{workstream.title} · {workstream.work_id} · {workstream.kind}" - - -def _selection( - *, - status: PickerStatus, - locale: PickerLocale, - message_key: str, - stage: PickerStage | None = None, - selected: HandoffWorkstreamChoice | None = None, - project_choices: list[HandoffProjectChoice] | None = None, - workstream_choices: list[HandoffWorkstreamChoice] | None = None, - truncated: bool = False, -) -> HandoffWorkstreamSelection: - return HandoffWorkstreamSelection( - status=status, - message=_copy(locale, message_key), - stage=stage, - selected=selected, - project_choices=[] if project_choices is None else project_choices, - workstream_choices=[] if workstream_choices is None else workstream_choices, - truncated=truncated, - ) - - -def _copy(locale: PickerLocale, key: str) -> str: - return _COPY[locale][key] - - -_COPY: dict[PickerLocale, dict[str, str]] = { - "zh-CN": { - "cancelled": "已取消工作选择，未产生任何交接写入。", - "choose_project": "选择这次交接所属的项目。", - "choose_project_fallback": "当前客户端不支持原生选择框，请从 project_choices 选择并重新调用。", - "choose_workstream": "选择要交接或继续的工作。", - "choose_workstream_fallback": "当前客户端不支持原生选择框，请从 workstream_choices 选择并重新调用。", - "declined": "已拒绝工作选择，未产生任何交接写入。", - "no_matching_workstreams": "没有与查询条件匹配的工作。", - "no_projects": "没有可供选择的交接项目。", - "no_workstreams": "所选项目中没有可供选择的工作。", - "project_field": "项目", - "project_not_found": "找不到指定项目，请从 project_choices 重新选择。", - "selected": "已选择工作；此操作尚未创建或提交交接。", - "workstream_field": "工作", - "workstream_not_found": "找不到指定工作，请从 workstream_choices 重新选择。", - }, - "en": { - "cancelled": "Work selection was cancelled; no Handoff data was written.", - "choose_project": "Choose the Project that owns this Handoff.", - "choose_project_fallback": "This client has no native picker; choose from project_choices and call again.", - "choose_workstream": "Choose the work to hand off or continue.", - "choose_workstream_fallback": ( - "This client has no native picker; choose from workstream_choices and call again." - ), - "declined": "Work selection was declined; no Handoff data was written.", - "no_matching_workstreams": "No work matches the query.", - "no_projects": "No Handoff Projects are available.", - "no_workstreams": "The selected Project has no available work.", - "project_field": "Project", - "project_not_found": "The requested Project was not found; choose from project_choices.", - "selected": "Work selected; this operation has not created or committed a Handoff.", - "workstream_field": "Work", - "workstream_not_found": "The requested work was not found; choose from workstream_choices.", - }, -} - - -__all__ = [ - "HandoffProjectChoice", - "HandoffWorkstreamChoice", - "HandoffWorkstreamSelection", - "register_handoff_workstream_picker", -] diff --git a/src/powercontext/server/mcp.py b/src/powercontext/server/mcp.py index 9b053db83..f8cce4253 100644 --- a/src/powercontext/server/mcp.py +++ b/src/powercontext/server/mcp.py @@ -36,27 +36,30 @@ ACTIVATE_HANDOFF, APPROVE_ARTIFACT_CANDIDATE, CAPTURE_CONTENT_SOURCE, + CLEAR_SCOPE_BINDING, COMMIT_HANDOFF, CONTINUE_HANDOFF, + CREATE_SCOPE, CREATE_WORK_CONTRACT, FINALIZE_HANDOFF, GET_ARTIFACT_CANDIDATE, GET_HANDOFF_REPORT, - GET_HANDOFF_REPORT_WORKSPACE, GET_MEMORY_ENTRY, + GET_SCOPE, HANDOFF_CURRENT_WORK, LIST_ARTIFACT_CANDIDATES, - LIST_HANDOFF_REPORT_KNOWN_SCOPES, - LIST_HANDOFF_REPORT_PROJECTS, - LIST_HANDOFF_REPORT_WORKSTREAMS, LIST_MEMORY_ENTRIES, + LIST_SCOPES, + PUBLISH_ARTIFACT, RECORD_TASK_OUTCOME, REJECT_ARTIFACT_CANDIDATE, REMEMBER_MEMORY, + RESOLVE_SCOPE_BINDING, RETIRE_MEMORY_ENTRY, REVISE_ARTIFACT_CANDIDATE, REVISE_MEMORY_ENTRY, SEARCH_MEMORY, + SET_SCOPE_BINDING, ) from powercontext.server.access import McpAccessLogMiddleware from powercontext.server.app import REQUEST_ID_HEADER @@ -65,7 +68,6 @@ current_request_id, reset_internal_bridge, ) -from powercontext.server.handoff_picker import register_handoff_workstream_picker from powercontext.server.metrics import McpMetricsMiddleware, ServerMetrics from powercontext.server.tracing import McpTracingMiddleware, ServerTracing @@ -87,14 +89,19 @@ REMEMBER_MEMORY.operation_id, REVISE_MEMORY_ENTRY.operation_id, GET_HANDOFF_REPORT.operation_id, - LIST_HANDOFF_REPORT_KNOWN_SCOPES.operation_id, - GET_HANDOFF_REPORT_WORKSPACE.operation_id, RETIRE_MEMORY_ENTRY.operation_id, LIST_ARTIFACT_CANDIDATES.operation_id, GET_ARTIFACT_CANDIDATE.operation_id, APPROVE_ARTIFACT_CANDIDATE.operation_id, REJECT_ARTIFACT_CANDIDATE.operation_id, REVISE_ARTIFACT_CANDIDATE.operation_id, + CREATE_SCOPE.operation_id, + LIST_SCOPES.operation_id, + GET_SCOPE.operation_id, + RESOLVE_SCOPE_BINDING.operation_id, + SET_SCOPE_BINDING.operation_id, + CLEAR_SCOPE_BINDING.operation_id, + PUBLISH_ARTIFACT.operation_id, }) _MCP_READ_ONLY_OPERATION_IDS = frozenset({ CONTINUE_HANDOFF.operation_id, @@ -102,10 +109,11 @@ LIST_MEMORY_ENTRIES.operation_id, GET_MEMORY_ENTRY.operation_id, GET_HANDOFF_REPORT.operation_id, - LIST_HANDOFF_REPORT_KNOWN_SCOPES.operation_id, - GET_HANDOFF_REPORT_WORKSPACE.operation_id, LIST_ARTIFACT_CANDIDATES.operation_id, GET_ARTIFACT_CANDIDATE.operation_id, + LIST_SCOPES.operation_id, + GET_SCOPE.operation_id, + RESOLVE_SCOPE_BINDING.operation_id, }) _MCP_REVIEW_WRITE_OPERATION_IDS = frozenset({ APPROVE_ARTIFACT_CANDIDATE.operation_id, @@ -132,6 +140,7 @@ def _annotate_mcp_component( component.annotations = ToolAnnotations( readOnlyHint=True, destructiveHint=False, + idempotentHint=True, openWorldHint=False, ) elif route.operation_id == HANDOFF_CURRENT_WORK.operation_id: @@ -186,11 +195,6 @@ def create_mcp_server( validate_output=False, ) server = FastMCP(name=MCP_SERVER_NAME, providers=[provider]) - if { - LIST_HANDOFF_REPORT_PROJECTS.path, - LIST_HANDOFF_REPORT_WORKSTREAMS.path, - }.issubset(server_app.openapi()["paths"]): - register_handoff_workstream_picker(server, client) server.add_middleware(McpTracingMiddleware(resolved_tracing)) if access_log: server.add_middleware(McpAccessLogMiddleware()) diff --git a/src/powercontext/server/settings.py b/src/powercontext/server/settings.py index 060730d89..bc744db81 100644 --- a/src/powercontext/server/settings.py +++ b/src/powercontext/server/settings.py @@ -108,33 +108,10 @@ def require_token_when_enabled(self) -> BearerAuthConfig: return self -class DashboardScopeConfig(BaseModel): - """One scope exposed by the personal Dashboard.""" - - scope_id: str = Field(min_length=1, max_length=255) - display_name: str = Field(min_length=1, max_length=80) - - @field_validator("scope_id", "display_name") - @classmethod - def strip_non_empty_text(cls, value: str) -> str: - stripped = value.strip() - if not stripped: - raise ValueError("Dashboard scope values must not be empty") # noqa: TRY003 - return stripped - - class DashboardConfig(BaseModel): """Personal Dashboard served by the local Server.""" enabled: bool = True - scopes: list[DashboardScopeConfig] = Field(default_factory=list, max_length=100) - - @model_validator(mode="after") - def validate_scopes(self) -> DashboardConfig: - scope_ids = [scope.scope_id for scope in self.scopes] - if len(scope_ids) != len(set(scope_ids)): - raise ValueError("Dashboard scope IDs must be unique") # noqa: TRY003 - return self class ServerLoggingConfig(BaseModel): @@ -222,7 +199,6 @@ def reject_unauthenticated_non_loopback_bind(self) -> ServerSettings: __all__ = [ "BearerAuthConfig", "DashboardConfig", - "DashboardScopeConfig", "HandoffReportConfig", "HttpConfig", "McpConfig", diff --git a/src/powercontext/server/static/dashboard.js b/src/powercontext/server/static/dashboard.js index d8a588bb4..c7a087dbd 100644 --- a/src/powercontext/server/static/dashboard.js +++ b/src/powercontext/server/static/dashboard.js @@ -23,6 +23,7 @@ import { storeServerToken } from "./auth.js?v=optional-auth"; import {createPageUi, createRequestGate} from "./page-ui.js?v=locale-complete"; +import {buildScopeSelectionChoices} from "./scope-selection.js?v=selection-v1"; const translations = { en: { @@ -40,6 +41,10 @@ const translations = { tokenLabel: "Server token", continue: "Continue", selectScope: "View", + allScopes: "All work", + subtreeView: "{title} and related work", + exactFocus: "Focus: {title}", + period30: "Last 30 days", estimatedReduction: "Compared with using the original materials directly", sources: "Work materials", memoryEntries: "Memory", @@ -49,6 +54,7 @@ const translations = { family: "Type", currentArtifacts: "Saved", pendingCandidates: "Awaiting review", + artifactSubtitle: "Current Artifacts and pending Candidates", experience: "Experience", handoff: "Handoff", memory: "Memory", @@ -105,6 +111,10 @@ const translations = { tokenLabel: "服务器访问令牌", continue: "继续", selectScope: "查看", + allScopes: "全部工作", + subtreeView: "{title}及相关工作", + exactFocus: "聚焦：{title}", + period30: "过去 30 天", estimatedReduction: "相比直接使用原始材料", sources: "工作材料", memoryEntries: "记忆", @@ -239,11 +249,10 @@ async function authenticate(token, scopeId = "") { showPageStatus("noScopes"); return; } - const selectedScopeId = currentScopes.some((scope) => scope.scope_id === scopeId) - ? scopeId - : currentScopes[0].scope_id; - currentScopeId = selectedScopeId; - await loadStatistics(token, selectedScopeId, request); + const choices = buildScopeSelectionChoices(currentScopes, translate); + const selectedKey = choices.some((choice) => choice.key === scopeId) ? scopeId : "all"; + currentScopeId = selectedKey; + await loadStatistics(token, selectedKey, request); } catch (error) { if (request.isCurrent()) { showPageStatus("serverUnavailable", {}, true); @@ -265,10 +274,16 @@ async function loadStatistics(token, scopeId, request = null) { currentScopeId = scopeId; scopeSelect.disabled = true; try { - const url = new URL("/v1/stats", window.location.origin); - url.searchParams.set("scope_id", scopeId); - url.searchParams.set("period", "30d"); - const response = await fetchWithBearer(url, token); + const choice = buildScopeSelectionChoices(currentScopes, translate).find((item) => item.key === scopeId); + if (!choice) { + showPageStatus("scopeUnavailable", {}, true); + return; + } + const response = await fetchWithBearer("/v1/stats", token, { + method: "POST", + headers: {"Content-Type": "application/json"}, + body: JSON.stringify({selection: choice.selection, period: "30d"}) + }); if (!activeRequest.isCurrent()) { return; } @@ -285,12 +300,7 @@ async function loadStatistics(token, scopeId, request = null) { if (!activeRequest.isCurrent()) { return; } - const selectedScope = currentScopes.find((scope) => scope.scope_id === statistics.scope_id); - if (!selectedScope) { - showPageStatus("scopeUnavailable", {}, true); - return; - } - renderDashboard({scopes: currentScopes, selectedScope, statistics}); + renderDashboard({scopes: currentScopes, choice, statistics}); } catch (error) { if (activeRequest.isCurrent()) { showPageStatus("serverUnavailable", {}, true); @@ -359,8 +369,8 @@ function renderDashboard(view) { dashboard.hidden = false; signOut.hidden = !authenticationRequired; - renderScopes(view.scopes, statistics.scope_id); - setText("dashboard-name", view.selectedScope.display_name); + renderScopes(view.scopes, view.choice.key); + setText("dashboard-name", view.choice.label); setText("as-of", translate("updated", {value: formatDateTime(statistics.as_of)})); setText("sources", formatNumber(inventory.sources.total)); setText("memory-entries", formatNumber(inventory.memory.entries.active)); @@ -376,13 +386,13 @@ function renderDashboard(view) { renderTrend(recall.daily, comparisonAvailable); } -function renderScopes(scopes, selectedScopeId) { +function renderScopes(scopes, selectedKey) { scopeSelect.replaceChildren(); - for (const scope of scopes) { + for (const choice of buildScopeSelectionChoices(scopes, translate)) { const option = document.createElement("option"); - option.value = scope.scope_id; - option.textContent = scope.display_name; - option.selected = scope.scope_id === selectedScopeId; + option.value = choice.key; + option.textContent = choice.label; + option.selected = choice.key === selectedKey; scopeSelect.appendChild(option); } } diff --git a/src/powercontext/server/static/handoff-report.js b/src/powercontext/server/static/handoff-report.js index 58d7380ea..75d0286df 100644 --- a/src/powercontext/server/static/handoff-report.js +++ b/src/powercontext/server/static/handoff-report.js @@ -22,16 +22,9 @@ import { readServerToken, storeServerToken } from "./auth.js?v=optional-auth"; -import {formatDateRange, resolvePeriodSelection, validateDateRange} from "./handoff-period.js"; import {createPageUi, createRequestGate} from "./page-ui.js?v=locale-complete"; +import {buildScopeSelectionChoices} from "./scope-selection.js?v=selection-v1"; -const selectedProjectKey = "powercontext.handoff-report.project"; -const selectedWorkKey = "powercontext.handoff-report.work"; -const autoRefreshIntervalMilliseconds = 5_000; -const continuityTimelineRecentLimit = 6; -const workstreamSearchThreshold = 8; -const projectOptionRenderLimit = 50; -const authenticationRequired = document.documentElement.dataset.serverAuthRequired === "true"; const translations = { en: { pageTitle: "PowerContext Handoff Report", @@ -41,7 +34,6 @@ const translations = { handoffReportTitle: "Handoff Report", brandHomeLabel: "PowerContext Overview", primaryNavigation: "Primary navigation", - handoffSummary: "Handoff summary", maintainedBy: "Maintained by OceanBase.", signOut: "Sign out", authTitle: "Connect to PowerContext", @@ -50,200 +42,52 @@ const translations = { continue: "Continue", refresh: "Refresh", downloadMarkdown: "Download Markdown", - projects: "Scopes", - searchProjectsPlaceholder: "Search by scope ID", - projectSearchCount: "{count} scopes", - projectSearchMatches: "{count} matching scopes", - projectSearchLimited: "Showing the first {shown} of {total} matches. Keep typing to narrow the list.", - noMatchingProjects: "No scopes match this search.", - reportPeriod: "Report period", - activity: "Activity", - activitySubtitle: "Period controls affect Activity counts only. Handoff status stays on the current exact selection.", - activityPeriod: "Activity period", - activityByWorkstream: "Activity by Workstream", - day: "Day", - week: "Week", - month: "Month", - custom: "Custom", - periodStart: "Start date", - periodEnd: "End date", - apply: "Apply", - periodSummary: "{preset} / {range} / {timezone}", - periodComparison: "Activity: {current} current / {previous} previous / {delta} change", - periodBoundaryUnavailable: "Handoff status uses the current exact selection; this period filters Activity but cannot reconstruct historical Handoff boundaries.", - periodDatesRequired: "Select both a start date and an end date.", - periodInvalidRange: "The start date must not be later than the end date.", + scopeHandoffState: "Scope Handoff state", + reportDescription: "An exact Handoff projection over the selected Scope view.", + scopeView: "Scope view", + scopeViewDescription: "All, subtree, and exact use the same selection semantics as Dashboard.", + selectScope: "Scope", + allScopes: "All", + subtreeView: "{title} and descendants", + exactFocus: "Focus: {title}", + handoffSummary: "Handoff summary", continuable: "Continuable", blocked: "Blocked", complete: "Complete", noHandoff: "No Handoff", - coverage: "Report coverage", - workstreams: "Workstreams", - activities: "Activities", - evidenceUnavailable: "Evidence unavailable", - blockers: "Blockers", - blockersSubtitle: "Workstreams that cannot be continued without intervention", - workstreamsSubtitle: "Exact Handoff state and the next action for each scope", - workstreamNavigation: "Workstream navigation", - workstreamPagination: "Workstream pagination", - searchWorkstreams: "Search Workstreams", - searchWorkstreamsPlaceholder: "Search by name or scope", - previousWorkstream: "Previous", - nextWorkstream: "Next", - workstreamPosition: "{current} / {total}", - workstreamMatchCount: "{count} matches", - noMatchingWorkstreams: "No Workstreams match this search.", - workstream: "Workstream", + no_handoff: "No Handoff", + selectedScopes: "Selected Scopes", + selectedScopesDescription: "Parent describes organization; each row reports only that Scope's exact latest Handoff.", + scope: "Scope", + parent: "Parent", status: "Status", - reporting: "Reporting", + objective: "Objective", nextAction: "Next action", - state: "Current state", - next_action: "Next action", - available: "Available", - unavailable: "Unavailable", - noWorkstreams: "No Workstreams are registered for this Project.", - handoffContents: "Handoff content", - handoffContentsSubtitle: "Edit the Handoff as one document. Every save creates a new Handoff Revision.", - currentSnapshot: "Current Handoff snapshot", exactRevision: "Exact Revision", - editHandoffContent: "Edit", - editHandoffContentLabel: "Edit all Handoff content", - cancelEdit: "Cancel", - saveRevision: "Save Revision", - createFirstRevision: "Create first Revision", - firstRevisionNote: "The first Revision needs an Objective and at least one Current state item.", - emptyField: "Not provided.", - savingRevision: "Saving a new Handoff Revision...", - revisionSaved: "Saved as Handoff Revision @{revision}.", - revisionSaveFailed: "The Handoff Revision could not be saved (HTTP {status}).", - objective: "Objective", - currentState: "Current state", - omissions: "Known omissions", - currentStateLines: "Current state, one item per line", - disposition: "Disposition", - omissionLines: "Known omissions, one item per line", - liveStateCheck: "Live workspace", - capabilityCheck: "Capability", - authorizationCheck: "Authorization", - notChecked: "Not checked", - confirmed: "Confirmed", - mismatch: "Mismatch", - insufficient: "Insufficient", - receiverIdentity: "Receiver identity", - continuityTimeline: "Continuity timeline", - continuityOrderNote: "Ordered by Source journal position, not wall-clock time.", - revisionHistory: "Handoff Revision history", - revisionHistorySummary: "{total} Revisions. Latest first.", - revisionHistoryTruncated: "Showing the latest {shown} of {total} Revisions.", - revisionHistoryEmpty: "No committed Handoff Revisions are available.", - revisionCurrent: "Current", - revisionNextAction: "Next: {value}", - revisionCounts: "{state} state items / {omissions} omissions", - transferState: "Transfer", - outcomeState: "Outcome", - editorRequired: "Objective and at least one current-state item are required.", - timelineEmpty: "No high-level Work continuity records are available for this scope.", - timelineTruncated: "Only the latest {count} of {total} continuity events are shown.", - timelineInvalid: "{count} Work record(s) could not be read and were excluded.", - timelineShowEarlier: "Show {count} earlier events", - timelineShowRecent: "Show latest {count}", - eventSource: "Source", - eventRevision: "Handoff Revision", - eventReceipt: "Receipt", - eventReceiverChecks: "Receiver checks", - eventSchema: "Record schema", - eventNoDetails: "No additional details were recorded.", - autoRefreshActive: "Auto-refresh every 5 seconds", - autoRefreshEditing: "Auto-refresh paused while Handoff content is being edited.", - autoRefreshBusy: "Auto-refresh paused during this action.", - autoRefreshing: "Refreshing report...", - autoRefreshUpdated: "Auto-refreshed just now", - autoRefreshFailed: "Auto-refresh failed. Use Refresh to retry.", - eventActor: "Receiver: {actor}", - "work-contract": "Delegation contract", - "handoff-boundary": "Handoff sent", - "handoff-receipt": "Receiver decision", - "task-outcome": "Task outcome", - delegated: "Delegated", - accepted: "Accepted", - needs_clarification: "Needs clarification", - declined: "Declined", - succeeded: "Succeeded", - partial: "Partial", - failed: "Failed", - cancelled: "Cancelled", - awaiting_receipt: "Awaiting receipt", - awaiting_outcome: "Awaiting outcome", - not_expected: "Not expected", - not_applicable: "Not applicable", - covered: "Covered", metadata: "Report metadata", - selectionConsistency: "Selection consistency", - activityCoverage: "Activity coverage", + generatedAt: "Generated at", selectionDigest: "Selection digest", reportDigest: "Report digest", - dark: "Dark", - light: "Light", + noScopes: "No Scopes are available.", + requestFailed: "The Handoff Report request failed with HTTP {status}.", + serverUnavailable: "The Server is unavailable.", + authRejected: "The Server rejected this token.", + retry: "Retry", switchDark: "Switch to dark mode", switchLight: "Switch to light mode", switchChinese: "Switch to Chinese", switchEnglish: "Switch to English", languageChinese: "中文", - languageEnglish: "EN", - updated: "Updated {value}", - projectOption: "{projectId}", - coverageCaptured: "Captured Activity is included through cursor {cursor}. Counts describe observed events, not completion percentage.", - coverageNotConfigured: "Activity adapters are not configured. Missing Activity must not be read as no work occurring.", - coverageUnavailable: "Activity coverage is unavailable for this report.", - noProjects: "No scope contains a committed Handoff.", - previewReportTitle: "Handoff Report template", - preview: "Preview", - previewNotice: "This data-free preview shows the report's main Handoff sections. Values shown as \u201c\u2014\u201d do not represent real scope status.", - previewRetryHint: "Commit a Handoff for a scope, then retry to load its report.", - previewPlaceholder: "\u2014", - previewProjectSummary: "Project summary and scope", - previewProjectSummarySubtitle: "Project identity, selected scope, and reporting period", - previewProject: "Project", - previewScope: "Scope", - previewWorkstreamsTitle: "Workstreams and Handoff", - previewWorkstreamsSubtitle: "Current Handoff state and continuation content for each scope", - previewHandoffContentsSubtitle: "Objective, current state, disposition, next action, and known omissions", - previewActivitySubtitle: "Coverage and period comparison become available with a real Project report.", - previewCoverageDescription: "Coverage values appear here after a Project report is available.", - previewActivityComparison: "Activity and period comparison", - previewActivityComparisonSubtitle: "Observed Activity in the selected and previous periods", - previewCurrentPeriod: "Current period", - previewPreviousPeriod: "Previous period", - previewChange: "Change", - authRejected: "The Server rejected this token.", - requestFailed: "The Handoff Report request failed with HTTP {status}.", - serverUnavailable: "The Server is unavailable.", - retry: "Retry", - reportUnavailable: "The selected scope report is unavailable.", - downloadFailed: "The Markdown download failed with HTTP {status}.", - reported: "Reported", - reported_with_omissions: "Reported with omissions", - evidence_unavailable: "Evidence unavailable", - no_handoff: "No Handoff", - activity_after_handoff: "Activity after Handoff", - activity_without_handoff: "Activity without Handoff", - no_observed_activity: "No observed Activity", - current_only: "Current only", - exact_input: "Exact input", - optimistic_stable: "Optimistically stable", - captured: "Captured", - not_configured: "Not configured", - unknown: "Unknown" + languageEnglish: "EN" }, zh: { - pageTitle: "PowerContext 项目交接报告", + pageTitle: "PowerContext 交接报告", dashboardTitle: "概览", skillsTitle: "技能", reviewTitle: "审核", handoffReportTitle: "交接报告", brandHomeLabel: "PowerContext 概览", primaryNavigation: "主导航", - handoffSummary: "交接摘要", maintainedBy: "由 OceanBase 维护。", signOut: "退出", authTitle: "连接 PowerContext", @@ -252,193 +96,47 @@ const translations = { continue: "继续", refresh: "刷新", downloadMarkdown: "下载 Markdown", - projects: "范围", - searchProjectsPlaceholder: "按范围标识搜索", - projectSearchCount: "共 {count} 个范围", - projectSearchMatches: "匹配 {count} 个范围", - projectSearchLimited: "显示前 {shown} 个，共匹配 {total} 个。继续输入可缩小范围。", - noMatchingProjects: "没有匹配的范围。", - reportPeriod: "报告周期", - activity: "活动", - activitySubtitle: "周期控件只影响活动数量，交接状态始终采用当前精确选择。", - activityPeriod: "活动周期", - activityByWorkstream: "各工作项活动", - day: "日", - week: "周", - month: "月", - custom: "自定义", - periodStart: "开始日期", - periodEnd: "结束日期", - apply: "应用", - periodSummary: "{preset} / {range} / {timezone}", - periodComparison: "活动：本期 {current} / 上期 {previous} / 变化 {delta}", - periodBoundaryUnavailable: "交接状态采用当前精确选择；该周期只筛选活动，不能还原历史交接边界。", - periodDatesRequired: "请选择开始日期和结束日期。", - periodInvalidRange: "开始日期不能晚于结束日期。", + scopeHandoffState: "Scope 交接状态", + reportDescription: "按所选 Scope 视图汇总各 Scope 的精确交接状态。", + scopeView: "Scope 视图", + scopeViewDescription: "全部、下级范围和精确聚焦与仪表盘使用相同的选择语义。", + selectScope: "作用域", + allScopes: "全部", + subtreeView: "{title}及其下级", + exactFocus: "聚焦：{title}", + handoffSummary: "交接摘要", continuable: "可继续", blocked: "阻塞", complete: "已完成", noHandoff: "无交接", - coverage: "报告覆盖范围", - workstreams: "工作项", - activities: "活动", - evidenceUnavailable: "证据不可用", - blockers: "阻塞事项", - blockersSubtitle: "需要人工处理后才能继续的工作项", - workstreamsSubtitle: "每个工作范围的精确交接状态与下一步", - workstreamNavigation: "工作项导航", - workstreamPagination: "工作项翻页", - searchWorkstreams: "搜索工作项", - searchWorkstreamsPlaceholder: "按名称或范围标识搜索", - previousWorkstream: "上一项", - nextWorkstream: "下一项", - workstreamPosition: "{current} / {total}", - workstreamMatchCount: "匹配 {count} 项", - noMatchingWorkstreams: "没有匹配的工作项。", - workstream: "工作项", + no_handoff: "无交接", + selectedScopes: "所选 Scope", + selectedScopesDescription: "Parent 只表达组织关系；每一行只报告该 Scope 自身最新的精确 Handoff。", + scope: "Scope", + parent: "上级", status: "状态", - reporting: "汇报状态", + objective: "目标", nextAction: "下一步", - state: "当前状态", - next_action: "下一步", - available: "可用", - unavailable: "不可用", - noWorkstreams: "该项目尚未登记工作项。", - handoffContents: "交接内容", - handoffContentsSubtitle: "统一编辑整份交接内容，每次保存都会生成新的交接版本。", - currentSnapshot: "当前交接快照", exactRevision: "精确版本", - editHandoffContent: "编辑", - editHandoffContentLabel: "编辑全部交接内容", - cancelEdit: "取消", - saveRevision: "保存新版本", - createFirstRevision: "创建首个版本", - firstRevisionNote: "首个版本必须包含目标和至少一项当前状态。", - emptyField: "未填写。", - savingRevision: "正在保存新的交接版本...", - revisionSaved: "已保存为交接版本 @{revision}。", - revisionSaveFailed: "交接版本保存失败（HTTP {status}）。", - objective: "目标", - currentState: "当前状态", - omissions: "已知缺失", - currentStateLines: "当前状态，每行一项", - disposition: "处置状态", - omissionLines: "已知缺失，每行一项", - liveStateCheck: "实时工作区", - capabilityCheck: "能力", - authorizationCheck: "授权", - notChecked: "未检查", - confirmed: "已确认", - mismatch: "不匹配", - insufficient: "不足", - receiverIdentity: "接手方身份", - continuityTimeline: "连续性时间线", - continuityOrderNote: "按来源日志位置排序，不代表实际发生时间。", - revisionHistory: "交接版本历史", - revisionHistorySummary: "共 {total} 个版本，按最新优先显示。", - revisionHistoryTruncated: "共 {total} 个版本，显示最近 {shown} 个。", - revisionHistoryEmpty: "该工作项尚无已提交的交接版本。", - revisionCurrent: "当前版本", - revisionNextAction: "下一步：{value}", - revisionCounts: "状态 {state} 项 / 缺失 {omissions} 项", - transferState: "交接状态", - outcomeState: "结果状态", - editorRequired: "目标和至少一项当前状态不能为空。", - timelineEmpty: "该工作范围尚无高层工作连续性记录。", - timelineTruncated: "仅显示最近 {count} 条，共有 {total} 条连续性事件。", - timelineInvalid: "有 {count} 条工作记录无法读取，已明确排除。", - timelineShowEarlier: "查看更早的 {count} 条记录", - timelineShowRecent: "收起，仅看最近 {count} 条", - eventSource: "来源", - eventRevision: "交接版本", - eventReceipt: "接手回执", - eventReceiverChecks: "接手检查", - eventSchema: "记录格式", - eventNoDetails: "该事件没有记录更多详情。", - autoRefreshActive: "每 5 秒自动刷新", - autoRefreshEditing: "正在编辑交接内容，自动刷新已暂停。", - autoRefreshBusy: "当前操作进行中，自动刷新已暂停。", - autoRefreshing: "正在刷新报告...", - autoRefreshUpdated: "刚刚已自动刷新", - autoRefreshFailed: "自动刷新失败，请使用刷新按钮重试。", - eventActor: "接手方：{actor}", - "work-contract": "委派契约", - "handoff-boundary": "发送交接", - "handoff-receipt": "接手选择", - "task-outcome": "任务结果", - delegated: "已委派", - accepted: "已接手", - needs_clarification: "需要补充", - declined: "无法接手", - succeeded: "成功", - partial: "部分完成", - failed: "失败", - cancelled: "已取消", - awaiting_receipt: "等待接手选择", - awaiting_outcome: "等待任务结果", - not_expected: "暂不需要", - not_applicable: "暂不适用", - covered: "已覆盖", metadata: "报告元数据", - selectionConsistency: "选择一致性", - activityCoverage: "活动覆盖范围", - selectionDigest: "选择摘要哈希", - reportDigest: "报告摘要哈希", - dark: "深色", - light: "浅色", + generatedAt: "生成时间", + selectionDigest: "选择摘要", + reportDigest: "报告摘要", + noScopes: "当前没有可用 Scope。", + requestFailed: "交接报告请求失败（HTTP {status}）。", + serverUnavailable: "服务器无法访问。", + authRejected: "服务器拒绝了该访问令牌。", + retry: "重试", switchDark: "切换至深色模式", switchLight: "切换至浅色模式", switchChinese: "切换至中文", switchEnglish: "切换至英文", languageChinese: "中文", - languageEnglish: "EN", - updated: "更新于 {value}", - projectOption: "{projectId}", - coverageCaptured: "已纳入游标 {cursor} 之前捕获的活动。数量表示已观察事件，不代表完成百分比。", - coverageNotConfigured: "活动适配器尚未配置；缺少活动不能解释为没有发生工作。", - coverageUnavailable: "当前报告无法取得活动覆盖信息。", - noProjects: "尚无包含已提交交接的范围。", - previewReportTitle: "交接报告模板", - preview: "预览", - previewNotice: "此无数据预览展示报告的主要交接部分。以“—”显示的值不代表真实范围状态。", - previewRetryHint: "为某个范围提交交接后，点击重试以加载真实报告。", - previewPlaceholder: "—", - previewProjectSummary: "项目摘要与范围", - previewProjectSummarySubtitle: "项目身份、所选范围和报告周期", - previewProject: "项目", - previewScope: "范围", - previewWorkstreamsTitle: "工作项与交接", - previewWorkstreamsSubtitle: "每个范围的当前交接状态与继续工作所需内容", - previewHandoffContentsSubtitle: "目标、当前状态、处置状态、下一步和已知缺失", - previewActivitySubtitle: "配置真实项目后，将显示覆盖范围和周期对比。", - previewCoverageDescription: "项目报告可用后，此处将显示覆盖数据。", - previewActivityComparison: "活动与周期对比", - previewActivityComparisonSubtitle: "所选周期与上一周期内观察到的活动", - previewCurrentPeriod: "本期", - previewPreviousPeriod: "上期", - previewChange: "变化", - authRejected: "服务器拒绝了该访问令牌。", - requestFailed: "交接报告请求失败（HTTP {status}）。", - serverUnavailable: "服务器无法访问。", - retry: "重试", - reportUnavailable: "当前范围的交接报告不可用。", - downloadFailed: "Markdown 下载失败（HTTP {status}）。", - reported: "已汇报", - reported_with_omissions: "已汇报但有缺失", - evidence_unavailable: "证据不可用", - no_handoff: "无交接记录", - activity_after_handoff: "交接后有活动", - activity_without_handoff: "有活动但无交接记录", - no_observed_activity: "未观察到活动", - current_only: "仅当前状态", - exact_input: "精确输入", - optimistic_stable: "乐观稳定", - captured: "已捕获", - not_configured: "未配置", - unknown: "未知" + languageEnglish: "EN" } }; +const authenticationRequired = document.documentElement.dataset.serverAuthRequired === "true"; const authShell = document.getElementById("auth-shell"); const authForm = document.getElementById("auth-form"); const authError = document.getElementById("auth-error"); @@ -446,240 +144,41 @@ const tokenInput = document.getElementById("token"); const pageStatus = document.getElementById("page-status"); const pageStatusMessage = document.getElementById("page-status-message"); const pageStatusRetry = document.getElementById("page-status-retry"); -const previewShell = document.getElementById("handoff-report-preview"); -const previewRetryButton = document.getElementById("preview-retry"); const reportShell = document.getElementById("handoff-report"); -const reportError = document.getElementById("report-error"); -const projectCombobox = document.getElementById("project-combobox"); -const projectSearchInput = document.getElementById("project-search"); -const projectOptions = document.getElementById("project-options"); -const projectSearchStatus = document.getElementById("project-search-status"); +const signOut = document.getElementById("sign-out"); +const scopeSelect = document.getElementById("scope-select"); const refreshButton = document.getElementById("refresh-report"); const downloadButton = document.getElementById("download-report"); -const periodButtons = Array.from(document.querySelectorAll("[data-period-mode]")); -const customPeriodForm = document.getElementById("custom-period-form"); -const periodStartInput = document.getElementById("period-start"); -const periodEndInput = document.getElementById("period-end"); -const applyCustomPeriodButton = document.getElementById("apply-custom-period"); -const periodError = document.getElementById("period-error"); -const autoRefreshStatus = document.getElementById("auto-refresh-status"); -const signOut = document.getElementById("sign-out"); -const handoffSaveStatus = document.getElementById("handoff-save-status"); -const handoffEditorActions = document.getElementById("handoff-editor-actions"); -const editHandoffContentButton = document.getElementById("edit-handoff-content"); -const saveHandoffRevisionButton = document.getElementById("save-handoff-revision"); -const cancelHandoffEditButton = document.getElementById("cancel-handoff-edit"); -const continuityTimelineToggle = document.getElementById("continuity-timeline-toggle"); -const workstreamSwitcherToolbar = document.getElementById("workstream-switcher-toolbar"); -const workstreamSearchField = document.getElementById("workstream-search-field"); -const workstreamSearchInput = document.getElementById("workstream-search"); -const workstreamSwitcherNavigation = document.getElementById("workstream-switcher-navigation"); -const previousWorkstreamButton = document.getElementById("previous-workstream"); -const nextWorkstreamButton = document.getElementById("next-workstream"); -const workstreamPosition = document.getElementById("workstream-position"); -const workstreamListPanel = document.querySelector(".workstream-list-panel"); -const workstreamList = document.getElementById("workstream-list"); -const workstreamFilterEmpty = document.getElementById("workstream-filter-empty"); -let currentProjects = []; -let currentHandoffWorks = []; -let currentProject = null; +const requests = createRequestGate(); +let scopes = []; +let selectedKey = "all"; let currentReport = null; -let currentAuthError = null; -let currentPageStatus = null; -let currentPeriodMode = "day"; -let currentPeriodSelection = null; -let appliedCustomRange = null; -let currentWorkstreamScope = null; -let revisionSaving = false; -let reportLoading = false; -let editorDirty = false; -let autoRefreshTimer = null; -let currentWorkstreamQuery = ""; -let projectActiveIndex = -1; -let lastCenteredWorkstreamKey = null; -let pendingWorkstreamLayoutFrame = null; -const handoffDrafts = new Map(); -const pendingHandoffAttempts = new Map(); -const expandedContinuityScopes = new Set(); -const openContinuityEvents = new Map(); -const ui = createPageUi(translations, ({userInitiated = false} = {}) => { - renderAuthError(); - renderPageStatus(); - if (currentProject !== null) { - renderProjectCombobox(currentProjects, currentProject.project_id); - } +let currentStatus = null; + +const ui = createPageUi(translations, () => { + renderChoices(); if (currentReport !== null) { renderReport(currentReport); - } else { - renderPeriodControls(); - } - updateAutoRefreshStatus(); - if (userInitiated && currentProject !== null && readServerToken()) { - void loadReport(readServerToken(), currentProject.project_id, { - background: true, - selectedScopeId: currentWorkstreamScope - }); } + renderStatus(); }); -const {formatDateTime, formatNumber, translate} = ui; -const reportRequests = createRequestGate(); +const {formatDateTime, translate} = ui; authForm.addEventListener("submit", async (event) => { event.preventDefault(); await authenticate(tokenInput.value); }); - signOut.addEventListener("click", () => { - stopAutoRefresh(); clearServerToken(); - tokenInput.value = ""; showLogin(); }); - -pageStatusRetry.addEventListener("click", async () => { - const token = readServerToken(); - if (currentProject === null) { - await authenticate(token); - } else { - await loadReport(token, currentProject.project_id); - } -}); - -previewRetryButton.addEventListener("click", async () => { - await authenticate(readServerToken()); -}); - -refreshButton.addEventListener("click", async () => { - if (currentProject !== null) { - await loadReport(readServerToken(), currentProject.project_id); - } -}); - -editHandoffContentButton.addEventListener("click", () => { - const item = currentReport?.workstreams.find( - (candidate) => candidate.workstream.scope_id === currentWorkstreamScope - ) || null; - if (item !== null) { - startHandoffEdit(item); - } -}); - -cancelHandoffEditButton.addEventListener("click", () => { - cancelHandoffEdit(); -}); - -downloadButton.addEventListener("click", async () => { - await downloadMarkdown(); -}); - -projectSearchInput.addEventListener("focus", () => { - if (projectOptions.hidden) { - projectSearchInput.value = ""; - } - openProjectOptions(); -}); - -projectSearchInput.addEventListener("input", () => { - projectActiveIndex = -1; - renderProjectOptionsList(); - openProjectOptions(); -}); - -projectSearchInput.addEventListener("keydown", (event) => { - handleProjectSearchKeydown(event); -}); - -projectCombobox.addEventListener("focusout", (event) => { - if (!projectCombobox.contains(event.relatedTarget)) { - closeProjectOptions({restoreSelection: true}); - } -}); - -workstreamSearchInput.addEventListener("input", () => { - currentWorkstreamQuery = normalizeWorkstreamQuery(workstreamSearchInput.value); - lastCenteredWorkstreamKey = null; - applyWorkstreamFilter(); -}); - -workstreamSearchInput.addEventListener("keydown", (event) => { - if (event.key === "Escape" && workstreamSearchInput.value) { - event.preventDefault(); - resetWorkstreamSearch(); - applyWorkstreamFilter(); - workstreamSearchInput.focus(); - return; - } - if (event.key === "Enter") { - const visibleButtons = visibleWorkstreamButtons(); - const selected = visibleButtons.find((button) => button.getAttribute("aria-current") === "true"); - const target = selected || visibleButtons[0]; - if (target !== undefined) { - event.preventDefault(); - activateWorkstream(target.dataset.scopeId); - } - } -}); - -previousWorkstreamButton.addEventListener("click", () => { - activateAdjacentWorkstream(-1); -}); - -nextWorkstreamButton.addEventListener("click", () => { - activateAdjacentWorkstream(1); -}); - -new ResizeObserver(() => { - scheduleWorkstreamLayoutUpdate(); -}).observe(workstreamListPanel); - -continuityTimelineToggle.addEventListener("click", () => { - if (currentWorkstreamScope === null) { - return; - } - if (expandedContinuityScopes.has(currentWorkstreamScope)) { - expandedContinuityScopes.delete(currentWorkstreamScope); - } else { - expandedContinuityScopes.add(currentWorkstreamScope); - } - const item = currentReport?.workstreams.find( - (candidate) => candidate.workstream.scope_id === currentWorkstreamScope - ) || null; - renderContinuity(item?.continuity || null); -}); - -for (const button of periodButtons) { - button.addEventListener("click", async () => { - currentPeriodMode = button.dataset.periodMode; - clearPeriodError(); - if (currentProject !== null) { - await loadReport(readServerToken(), currentProject.project_id); - } - }); -} - -customPeriodForm.addEventListener("submit", async (event) => { - event.preventDefault(); - try { - validateDateRange(periodStartInput.value, periodEndInput.value); - } catch (error) { - showPeriodError(error.message); - return; - } - appliedCustomRange = {startDate: periodStartInput.value, endDate: periodEndInput.value}; - currentPeriodMode = "custom"; - clearPeriodError(); - if (currentProject !== null) { - await loadReport(readServerToken(), currentProject.project_id); - } -}); - -periodStartInput.addEventListener("change", updatePeriodInputBounds); -periodEndInput.addEventListener("change", updatePeriodInputBounds); -document.addEventListener("visibilitychange", () => { - if (!document.hidden) { - void autoRefreshReport(); - } +scopeSelect.addEventListener("change", async () => { + selectedKey = scopeSelect.value; + await loadReport(readServerToken()); }); +refreshButton.addEventListener("click", async () => loadReport(readServerToken())); +pageStatusRetry.addEventListener("click", async () => authenticate(readServerToken())); +downloadButton.addEventListener("click", async () => downloadMarkdown(readServerToken())); async function authenticate(token) { if (authenticationRequired && !token) { @@ -690,1552 +189,187 @@ async function authenticate(token) { storeServerToken(token); } tokenInput.value = ""; - currentAuthError = null; - const request = beginReportRequest(); + const request = requests.start(); try { - const projects = await listProjects(token); - if (!request.isCurrent()) { + const response = await fetchWithBearer("/dashboard/scopes", token); + if (!request.isCurrent()) return; + if (response.status === 401) { + clearServerToken(); + showLogin("authRejected"); return; } - currentProjects = projects; - if (currentProjects.length === 0) { - stopAutoRefresh(); - currentHandoffWorks = []; - currentProject = null; - currentReport = null; - currentWorkstreamScope = null; - showReportPreview(); + if (!response.ok) { + showStatus("requestFailed", {status: response.status}); return; } - const rememberedProjectId = readSelectedProject(); - const rememberedWork = readSelectedWorkLocation(); - const selectedProject = currentProjects.find( - (project) => project.project_id === rememberedWork?.projectId - ) || currentProjects.find( - (project) => project.project_id === rememberedProjectId - ) || currentProjects[0]; - currentHandoffWorks = await listHandoffWorks(token, selectedProject); - if (!request.isCurrent()) { + scopes = await response.json(); + if (scopes.length === 0) { + showStatus("noScopes"); return; } - const selectedScopeId = rememberedWork?.projectId === selectedProject.project_id - && currentHandoffWorks.some((item) => item.workstream.scope_id === rememberedWork.scopeId) - ? rememberedWork.scopeId - : currentHandoffWorks[0]?.workstream.scope_id || null; - await loadReportData(token, selectedProject.project_id, request, { - selectedScopeId - }); - if (request.isCurrent()) { - startAutoRefresh(); - } + const choices = buildScopeSelectionChoices(scopes, translate); + if (!choices.some((choice) => choice.key === selectedKey)) selectedKey = "all"; + renderChoices(); + await loadReport(token, request); } catch (error) { - if (request.isCurrent()) { - handleRequestError(error); - } - } finally { - request.finish(); + if (request.isCurrent()) showStatus("serverUnavailable"); } } -async function listProjects(token) { - const projects = []; - let cursor = null; - do { - const payload = {limit: 100}; - if (cursor !== null) { - payload.cursor = cursor; - } - const page = await requestJson("/v1/handoff-reports/scopes/list-known", token, payload); - projects.push(...page.items.map(({scope_id: scopeId}) => ({ - project_id: scopeId, - project_key: scopeId, - title: scopeId, - default_locale: null, - timezone: "UTC" - }))); - cursor = page.next_cursor; - } while (cursor !== null); - return projects.sort((left, right) => ( - left.title.localeCompare(right.title, ui.localeTag(), {numeric: true, sensitivity: "base"}) - || left.project_id.localeCompare(right.project_id) - )); -} - -async function listHandoffWorks(token, project) { - void token; - return [{project, workstream: {scope_id: project.project_id}}]; -} - -async function loadReport(token, projectId, {background = false, selectedScopeId = null} = {}) { - if (reportLoading) { - return false; - } - if (authenticationRequired && !token) { - showLogin(); - return false; - } - reportLoading = true; - if (background) { - setAutoRefreshStatus("refreshing"); - } else { - clearReportError(); - } - const request = beginReportRequest({busy: !background}); +async function loadReport(token, request = requests.start()) { + const choice = selectedChoice(); + if (choice === null) return; + setBusy(true); try { - if (currentProject?.project_id !== projectId) { - const project = currentProjects.find((item) => item.project_id === projectId); - if (project === undefined) { - throw new Error("reportUnavailable"); - } - currentHandoffWorks = await listHandoffWorks(token, project); - if (!request.isCurrent()) { - return false; - } - } - await loadReportData(token, projectId, request, {selectedScopeId}); - if (!request.isCurrent()) { - return false; - } - if (background) { - setAutoRefreshStatus("updated"); - } - return true; - } catch (error) { - if (!request.isCurrent()) { - return false; - } - if (currentProject !== null) { - renderProjectCombobox(currentProjects, currentProject.project_id); - } - if (background) { - if (error.status === 401) { - handleRequestError(error); - } else { - setAutoRefreshStatus("failed"); - } - return false; - } - handleRequestError(error); - return false; - } finally { - reportLoading = false; - request.finish(); - syncHandoffEditingState(); - if (!background && request.isCurrent()) { - updateAutoRefreshStatus(); - } - } -} - -async function loadReportData(token, projectId, request, {selectedScopeId = null} = {}) { - const projectChanged = currentProject?.project_id !== projectId; - const project = currentProjects.find((item) => item.project_id === projectId) || currentProject; - const defaultLocale = projectUiLocale(project); - if (!ui.hasLocalePreference() && defaultLocale !== null && defaultLocale !== ui.locale()) { - ui.applyLocale(defaultLocale, false); - } - const periodSelection = resolveSelectedPeriod(project); - const response = await requestJson("/v1/handoff-reports/get", token, { - scope_id: projectId, - locale: ui.locale() === "zh" ? "zh-CN" : "en", - include_evidence_checks: false, - format: "json", - include_archived: false, - download: false, - period: periodSelection.period - }); - if (!request.isCurrent()) { - return; - } - if (response.report === null) { - throw new Error("reportUnavailable"); - } - if (projectChanged) { - resetWorkstreamSearch(); - lastCenteredWorkstreamKey = null; - } - currentProject = currentProjects.find((item) => item.project_id === projectId) || response.report.project; - currentReport = response.report; - currentPeriodSelection = periodSelection; - if (selectedScopeId !== null) { - currentWorkstreamScope = selectedScopeId; - } - rememberSelectedProject(projectId); - renderProjectCombobox(currentProjects, projectId); - renderReport(currentReport); -} - -function projectUiLocale(project) { - if (typeof project?.default_locale !== "string") { - return null; - } - return project.default_locale.toLowerCase().startsWith("zh") ? "zh" : "en"; -} - -function beginReportRequest({busy = true} = {}) { - if (busy) { - setBusy(true); - } - const request = reportRequests.start(); - return { - finish() { - if (busy && request.isCurrent()) { - setBusy(false); - } - }, - isCurrent: request.isCurrent - }; -} - -async function requestJson(path, token, payload) { - const response = await fetchWithBearer(path, token, { - method: "POST", - headers: {"Content-Type": "application/json"}, - body: JSON.stringify(payload) - }); - if (response.status === 401) { - const error = new Error("authRejected"); - error.status = 401; - throw error; - } - if (!response.ok) { - const error = new Error("requestFailed"); - error.status = response.status; - throw error; - } - return response.json(); -} - -function handleRequestError(error) { - if (error.status === 401) { - clearServerToken(); - showLogin("authRejected"); - return; - } - const key = error.message === "reportUnavailable" ? "reportUnavailable" : "serverUnavailable"; - if (typeof error.status === "number") { - showReportFailure("requestFailed", {status: error.status}); - return; - } - showReportFailure(key); -} - -function showReportFailure(key, values = {}) { - if (currentReport === null) { - showPageStatus(key, values, true); - return; - } - currentPageStatus = null; - pageStatus.hidden = true; - previewShell.hidden = true; - reportShell.hidden = false; - signOut.hidden = !authenticationRequired; - showReportError(key, values); -} - -function showLogin(messageKey = "", values = {}) { - stopAutoRefresh(); - reportRequests.cancel(); - setBusy(false); - reportLoading = false; - revisionSaving = false; - handoffDrafts.clear(); - pendingHandoffAttempts.clear(); - editorDirty = false; - currentProjects = []; - currentHandoffWorks = []; - currentProject = null; - currentReport = null; - currentWorkstreamScope = null; - currentPeriodSelection = null; - currentPageStatus = null; - currentAuthError = messageKey ? {key: messageKey, values} : null; - closeProjectOptions(); - projectSearchInput.value = ""; - projectSearchInput.disabled = false; - projectSearchStatus.textContent = ""; - handoffSaveStatus.textContent = ""; - renderAuthError(); - clearReport(); - authShell.hidden = false; - pageStatus.hidden = true; - previewShell.hidden = true; - reportShell.hidden = true; - signOut.hidden = true; - tokenInput.focus(); -} - -function showPageStatus(messageKey, values = {}, retryable = false) { - currentPageStatus = {key: messageKey, values, retryable}; - renderPageStatus(); - authShell.hidden = true; - pageStatus.hidden = false; - previewShell.hidden = true; - reportShell.hidden = true; - signOut.hidden = !authenticationRequired; -} - -function showReportPreview() { - currentPageStatus = null; - clearReport(); - authShell.hidden = true; - pageStatus.hidden = true; - previewShell.hidden = false; - reportShell.hidden = true; - signOut.hidden = !authenticationRequired; -} - -function renderPageStatus() { - if (currentPageStatus === null) { - pageStatusMessage.textContent = ""; - pageStatusRetry.hidden = true; - return; - } - pageStatusMessage.textContent = translate(currentPageStatus.key, currentPageStatus.values); - pageStatusRetry.hidden = !currentPageStatus.retryable; -} - -function renderAuthError() { - authError.textContent = currentAuthError === null - ? "" - : translate(currentAuthError.key, currentAuthError.values); -} - -function renderProjectCombobox(projects, selectedProjectId) { - const selected = projects.find((project) => project.project_id === selectedProjectId) || null; - if (projectOptions.hidden) { - projectSearchInput.value = selected === null ? "" : projectOptionLabel(selected); - projectSearchStatus.textContent = translate("projectSearchCount", {count: formatNumber(projects.length)}); - return; - } - renderProjectOptionsList(); -} - -function projectOptionLabel(project) { - return translate("projectOption", {title: project.title, projectId: project.project_id}); -} - -function normalizedProjectQuery(value) { - return value.trim().toLocaleLowerCase(); -} - -function matchingProjects() { - const query = normalizedProjectQuery(projectSearchInput.value); - if (!query) { - return currentProjects; - } - return currentProjects.filter((project) => ( - `${project.title}\n${project.project_id}\n${project.project_key}`.toLocaleLowerCase().includes(query) - )); -} - -function renderProjectOptionsList() { - const matches = matchingProjects(); - const visible = matches.slice(0, projectOptionRenderLimit); - projectOptions.replaceChildren(); - projectActiveIndex = Math.min(projectActiveIndex, visible.length - 1); - for (const [index, project] of visible.entries()) { - const option = document.createElement("button"); - option.className = "project-option"; - option.id = `project-option-${index}`; - option.type = "button"; - option.role = "option"; - option.dataset.projectId = project.project_id; - option.setAttribute("aria-selected", String(project.project_id === currentProject?.project_id)); - - const title = document.createElement("strong"); - title.textContent = project.title; - const identity = document.createElement("code"); - identity.textContent = project.project_id; - option.append(title, identity); - option.addEventListener("click", () => { - void selectProject(project.project_id); - }); - projectOptions.appendChild(option); - } - if (matches.length === 0) { - const empty = document.createElement("p"); - empty.className = "project-options-empty"; - empty.textContent = translate("noMatchingProjects"); - projectOptions.appendChild(empty); - } - if (matches.length > visible.length) { - projectSearchStatus.textContent = translate("projectSearchLimited", { - shown: formatNumber(visible.length), - total: formatNumber(matches.length) - }); - } else { - projectSearchStatus.textContent = translate( - projectSearchInput.value ? "projectSearchMatches" : "projectSearchCount", - {count: formatNumber(matches.length)} - ); - } - updateActiveProjectOption(); -} - -function openProjectOptions() { - projectOptions.hidden = false; - projectSearchInput.setAttribute("aria-expanded", "true"); - renderProjectOptionsList(); -} - -function closeProjectOptions({restoreSelection = false} = {}) { - projectOptions.hidden = true; - projectSearchInput.setAttribute("aria-expanded", "false"); - projectSearchInput.removeAttribute("aria-activedescendant"); - projectActiveIndex = -1; - if (restoreSelection) { - const selected = currentProjects.find((project) => project.project_id === currentProject?.project_id); - projectSearchInput.value = selected === undefined ? "" : projectOptionLabel(selected); - projectSearchStatus.textContent = translate("projectSearchCount", {count: formatNumber(currentProjects.length)}); - } -} - -function handleProjectSearchKeydown(event) { - if (event.key === "Escape") { - event.preventDefault(); - closeProjectOptions({restoreSelection: true}); - return; - } - if (!["ArrowDown", "ArrowUp", "Enter", "Home", "End"].includes(event.key)) { - return; - } - const options = Array.from(projectOptions.querySelectorAll(".project-option")); - if (projectOptions.hidden) { - openProjectOptions(); - } - if (options.length === 0) { - return; - } - event.preventDefault(); - if (event.key === "Enter") { - const target = options[projectActiveIndex] || options[0]; - void selectProject(target.dataset.projectId); - return; - } - if (event.key === "Home") { - projectActiveIndex = 0; - } else if (event.key === "End") { - projectActiveIndex = options.length - 1; - } else if (event.key === "ArrowDown") { - projectActiveIndex = Math.min(projectActiveIndex + 1, options.length - 1); - } else { - projectActiveIndex = projectActiveIndex <= 0 ? options.length - 1 : projectActiveIndex - 1; - } - updateActiveProjectOption(); -} - -function updateActiveProjectOption() { - const options = Array.from(projectOptions.querySelectorAll(".project-option")); - options.forEach((option, index) => { - option.dataset.active = String(index === projectActiveIndex); - }); - const active = options[projectActiveIndex]; - if (active === undefined) { - projectSearchInput.removeAttribute("aria-activedescendant"); - return; - } - projectSearchInput.setAttribute("aria-activedescendant", active.id); - active.scrollIntoView({block: "nearest"}); -} - -async function selectProject(projectId) { - const selected = currentProjects.find((project) => project.project_id === projectId); - if (selected === undefined) { - return; - } - projectSearchInput.value = projectOptionLabel(selected); - closeProjectOptions(); - if (projectId !== currentProject?.project_id) { - currentWorkstreamScope = null; - await loadReport(readServerToken(), projectId); - } -} - -function renderReport(report) { - currentPageStatus = null; - authShell.hidden = true; - pageStatus.hidden = true; - previewShell.hidden = true; - reportShell.hidden = false; - signOut.hidden = !authenticationRequired; - clearReportError(); - setText("project-name", currentWorkstreamScope || report.workstreams[0]?.workstream.scope_id || translate("handoffReportTitle")); - setText("report-updated", translate("updated", {value: formatDateTime(report.generated_at)})); - setText("continuable-count", formatNumber(report.summary.continuable_count)); - setText("blocked-count", formatNumber(report.summary.blocked_count)); - setText("complete-count", formatNumber(report.summary.complete_count)); - setText("no-handoff-count", formatNumber(report.summary.no_handoff_count)); - setText("selected-workstreams", formatNumber(report.coverage.selected_workstreams)); - setText("activity-count", formatNumber(report.activity_selection.length)); - setText("evidence-unavailable", formatNumber(report.coverage.unavailable_evidence_workstreams)); - setText("coverage-description", coverageDescription(report)); - setText("selection-consistency", statusLabel(report.selection_consistency)); - setText("activity-coverage", statusLabel(report.coverage.activity_coverage)); - setText("selection-digest", report.selection_digest || "-"); - setText("report-digest", report.report_digest || "-"); - renderPeriodControls(report); - renderBlockers(report.workstreams.filter((item) => item.work_status === "blocked")); - renderHandoffWorkstreams(report.workstreams); - renderActivityBreakdown(report.workstreams); -} - -function clearReport() { - setText("project-name", translate("handoffReportTitle")); - setText("report-updated", ""); - for (const id of [ - "continuable-count", - "blocked-count", - "complete-count", - "no-handoff-count", - "selected-workstreams", - "activity-count", - "evidence-unavailable" - ]) { - setText(id, "0"); - } - setText("coverage-description", ""); - setText("selection-consistency", "-"); - setText("activity-coverage", "-"); - setText("selection-digest", "-"); - setText("report-digest", "-"); - currentPeriodSelection = null; - renderPeriodControls(); - renderBlockers([]); - renderHandoffWorkstreams([]); - renderActivityBreakdown([]); -} - -function coverageDescription(report) { - const status = report.coverage.activity_coverage; - if (status === "captured") { - return translate("coverageCaptured", {cursor: formatNumber(report.activity_cursor)}); - } - if (status === "not_configured") { - return translate("coverageNotConfigured"); - } - return translate("coverageUnavailable"); -} - -function renderBlockers(blockers) { - const section = document.getElementById("blockers-section"); - const list = document.getElementById("blocker-list"); - list.replaceChildren(); - section.hidden = blockers.length === 0; - for (const item of blockers) { - const card = document.createElement("article"); - card.className = "blocker-card"; - const heading = document.createElement("h3"); - heading.textContent = item.workstream.title; - const scope = document.createElement("code"); - scope.textContent = item.workstream.scope_id; - const detail = document.createElement("p"); - detail.textContent = item.content?.next_action?.text || item.content?.objective || translate("blocked"); - card.append(heading, scope, detail); - list.appendChild(card); - } -} - -function renderWorkstreams(workstreams) { - const empty = document.getElementById("workstream-empty"); - const existingButtons = new Map( - Array.from(workstreamList.querySelectorAll(".workstream-list-item")) - .map((button) => [button.dataset.scopeId, button]) - ); - empty.hidden = workstreams.length !== 0; - workstreamSearchField.hidden = workstreams.length <= workstreamSearchThreshold; - if (workstreamSearchField.hidden && currentWorkstreamQuery) { - resetWorkstreamSearch(); - } - for (const item of workstreams) { - const selected = item.workstream.scope_id === currentWorkstreamScope; - const button = existingButtons.get(item.workstream.scope_id) || document.createElement("button"); - if (!button.classList.contains("workstream-list-item")) { - button.className = "workstream-list-item"; - button.type = "button"; - button.addEventListener("click", () => { - activateWorkstream(button.dataset.scopeId); - }); - } - button.dataset.scopeId = item.workstream.scope_id; - button.dataset.searchText = normalizeWorkstreamQuery(`${item.workstream.title}\n${item.workstream.scope_id}`); - button.setAttribute("aria-current", String(selected)); - - const header = document.createElement("span"); - header.className = "workstream-list-item-header"; - const title = document.createElement("strong"); - title.textContent = item.workstream.title; - header.append(title, statusBadge(item.work_status)); - - const scope = document.createElement("code"); - scope.textContent = item.workstream.scope_id; - button.replaceChildren(header, scope); - workstreamList.appendChild(button); - existingButtons.delete(item.workstream.scope_id); - } - for (const button of existingButtons.values()) { - button.remove(); - } - applyWorkstreamFilter(); -} - -function normalizeWorkstreamQuery(value) { - return value.trim().toLocaleLowerCase(); -} - -function resetWorkstreamSearch() { - currentWorkstreamQuery = ""; - workstreamSearchInput.value = ""; -} - -function visibleWorkstreamButtons() { - return Array.from(workstreamList.querySelectorAll(".workstream-list-item:not([hidden])")); -} - -function applyWorkstreamFilter() { - const buttons = Array.from(workstreamList.querySelectorAll(".workstream-list-item")); - for (const button of buttons) { - button.hidden = currentWorkstreamQuery !== "" && !button.dataset.searchText.includes(currentWorkstreamQuery); - } - workstreamFilterEmpty.hidden = buttons.length === 0 || visibleWorkstreamButtons().length !== 0; - scheduleWorkstreamLayoutUpdate(); -} - -function scheduleWorkstreamLayoutUpdate() { - if (pendingWorkstreamLayoutFrame !== null) { - window.cancelAnimationFrame(pendingWorkstreamLayoutFrame); - } - pendingWorkstreamLayoutFrame = window.requestAnimationFrame(() => { - pendingWorkstreamLayoutFrame = null; - updateWorkstreamSwitcherControls(); - centerSelectedWorkstream(); - }); -} - -function updateWorkstreamSwitcherControls() { - const buttons = visibleWorkstreamButtons(); - const selectedIndex = buttons.findIndex((button) => button.getAttribute("aria-current") === "true"); - const overflowing = workstreamList.scrollWidth > workstreamListPanel.clientWidth + 1; - workstreamSwitcherNavigation.hidden = !overflowing; - workstreamSwitcherToolbar.hidden = workstreamSearchField.hidden && workstreamSwitcherNavigation.hidden; - if (buttons.length === 0) { - workstreamPosition.textContent = translate("noMatchingWorkstreams"); - } else if (selectedIndex === -1) { - workstreamPosition.textContent = translate("workstreamMatchCount", {count: formatNumber(buttons.length)}); - } else { - workstreamPosition.textContent = translate("workstreamPosition", { - current: formatNumber(selectedIndex + 1), - total: formatNumber(buttons.length) + const response = await fetchWithBearer("/v1/handoff-reports/get", token, { + method: "POST", + headers: {"Content-Type": "application/json"}, + body: JSON.stringify({selection: choice.selection, format: "json"}) }); - } - previousWorkstreamButton.disabled = editorDirty || revisionSaving || buttons.length === 0 || selectedIndex === 0; - nextWorkstreamButton.disabled = editorDirty - || revisionSaving - || buttons.length === 0 - || selectedIndex === buttons.length - 1; -} - -function activateAdjacentWorkstream(direction) { - const buttons = visibleWorkstreamButtons(); - if (buttons.length === 0) { - return; - } - const selectedIndex = buttons.findIndex((button) => button.getAttribute("aria-current") === "true"); - const targetIndex = selectedIndex === -1 - ? (direction < 0 ? buttons.length - 1 : 0) - : selectedIndex + direction; - if (targetIndex < 0 || targetIndex >= buttons.length) { - return; - } - activateWorkstream(buttons[targetIndex].dataset.scopeId); -} - -function centerSelectedWorkstream() { - const selected = workstreamList.querySelector('.workstream-list-item[aria-current="true"]:not([hidden])'); - if (selected === null || currentProject === null) { - return; - } - const selectionKey = `${currentProject.project_id}:${selected.dataset.scopeId}`; - if (selectionKey === lastCenteredWorkstreamKey) { - return; - } - selected.scrollIntoView({block: "nearest", inline: "center"}); - lastCenteredWorkstreamKey = selectionKey; -} - -function renderHandoffContents(workstreams) { - const list = document.getElementById("handoff-content-list"); - list.replaceChildren(); - const item = workstreams.find((candidate) => candidate.workstream.scope_id === currentWorkstreamScope) - || workstreams[0] - || null; - if (item === null) { - const empty = document.createElement("p"); - empty.className = "handoff-content-empty"; - empty.textContent = translate("noWorkstreams"); - list.appendChild(empty); - renderHandoffEditorActions(null, null); - return; - } - - const card = document.createElement("div"); - card.className = "handoff-content-card"; - const header = document.createElement("header"); - const identity = document.createElement("div"); - const title = document.createElement("h4"); - title.className = "handoff-content-title"; - title.textContent = item.workstream.title; - const scope = document.createElement("code"); - scope.textContent = item.workstream.scope_id; - identity.append(title, scope); - const state = document.createElement("div"); - state.className = "handoff-snapshot-state"; - state.appendChild(statusBadge(item.work_status)); - const reference = document.createElement("code"); - reference.textContent = `${translate("exactRevision")}: ${formatArtifactRef(item.handoff_ref)}`; - state.appendChild(reference); - header.append(identity, state); - card.appendChild(header); - - const draft = handoffDrafts.get(item.workstream.scope_id) || null; - if (draft !== null) { - card.appendChild(createHandoffEditor(item, draft)); - } else { - if (item.content === null) { - const note = document.createElement("p"); - note.className = "handoff-content-empty"; - note.textContent = translate("firstRevisionNote"); - card.appendChild(note); - } - for (const field of handoffFieldDefinitions(item)) { - appendHandoffBlock(card, field); - } - } - list.appendChild(card); - renderHandoffEditorActions(item, draft); - syncHandoffEditingState(); -} - -function handoffFieldDefinitions(item, values = draftFromWorkstream(item)) { - return [ - {name: "objective", label: translate("objective"), kind: "text", rows: 3, value: values.objective}, - {name: "state", label: translate("currentState"), kind: "lines", rows: 5, value: values.state}, - {name: "disposition", label: translate("disposition"), kind: "disposition", value: values.disposition}, - {name: "nextAction", label: translate("nextAction"), kind: "text", rows: 3, value: values.nextAction}, - {name: "omissions", label: translate("omissions"), kind: "lines", rows: 3, value: values.omissions} - ]; -} - -function appendHandoffBlock(card, field) { - const section = document.createElement("section"); - section.className = "handoff-content-block"; - section.dataset.field = field.name; - const header = document.createElement("header"); - const heading = document.createElement("h4"); - heading.textContent = field.label; - header.appendChild(heading); - section.appendChild(header); - appendHandoffFieldValue(section, field); - card.appendChild(section); -} - -function appendHandoffFieldValue(section, field) { - const value = field.value.trim(); - if (field.kind === "disposition") { - section.appendChild(statusBadge(field.value)); - return; - } - const entries = field.kind === "lines" ? normalizedLines(value) : [value]; - if (!value || entries.length === 0) { - const empty = document.createElement("p"); - empty.className = "handoff-block-empty"; - empty.textContent = translate("emptyField"); - section.appendChild(empty); - return; - } - if (field.kind === "lines") { - const list = document.createElement("ul"); - for (const entry of entries) { - const row = document.createElement("li"); - row.textContent = entry; - list.appendChild(row); - } - section.appendChild(list); - return; - } - const paragraph = document.createElement("p"); - paragraph.textContent = value; - section.appendChild(paragraph); -} - -function createHandoffEditor(item, draft) { - const form = document.createElement("form"); - form.className = "handoff-content-editor"; - form.id = "handoff-content-editor"; - if (item.content === null) { - const note = document.createElement("p"); - note.className = "handoff-content-empty"; - note.textContent = translate("firstRevisionNote"); - form.appendChild(note); - } - for (const field of handoffFieldDefinitions(item)) { - const section = document.createElement("section"); - section.className = "handoff-content-block is-editing"; - section.dataset.field = field.name; - const label = document.createElement("label"); - const text = document.createElement("span"); - text.textContent = field.kind === "lines" && field.name === "state" - ? translate("currentStateLines") - : field.kind === "lines" && field.name === "omissions" - ? translate("omissionLines") - : field.label; - const control = createHandoffControl( - field, - draft.values[field.name], - `${item.workstream.scope_id}-${field.name}` - ); - label.htmlFor = control.id; - const update = () => { - draft.values[field.name] = control.value; - draft.dirty = handoffDraftChanged(draft); - syncHandoffEditingState(); - }; - control.addEventListener("input", update); - control.addEventListener("change", update); - label.appendChild(text); - section.append(label, control); - form.appendChild(section); - } - form.addEventListener("submit", (event) => { - event.preventDefault(); - void saveHandoffRevision(item, draft); - }); - return form; -} - -function createHandoffControl(field, value, id) { - let control; - if (field.kind === "disposition") { - control = document.createElement("select"); - for (const status of ["continuable", "blocked", "complete"]) { - const option = document.createElement("option"); - option.value = status; - option.textContent = statusLabel(status); - option.selected = status === value; - control.appendChild(option); + if (!request.isCurrent()) return; + if (response.status === 401) { + clearServerToken(); + showLogin("authRejected"); + return; } - } else { - control = document.createElement("textarea"); - control.rows = field.rows; - control.maxLength = 8192; - control.value = value; - } - control.id = id.replaceAll(/[^a-zA-Z0-9_-]/g, "-"); - control.setAttribute("aria-label", field.label); - return control; -} - -function startHandoffEdit(item) { - const values = draftFromWorkstream(item); - handoffDrafts.clear(); - handoffDrafts.set(item.workstream.scope_id, { - initialValues: {...values}, - values: {...values}, - dirty: false - }); - syncHandoffEditingState(); - handoffSaveStatus.textContent = ""; - handoffSaveStatus.classList.remove("is-error"); - renderHandoffContents(currentReport?.workstreams || []); - document.querySelector(".handoff-content-editor :is(textarea, select)")?.focus(); -} - -function cancelHandoffEdit() { - if (currentWorkstreamScope === null || revisionSaving) { - return; - } - handoffDrafts.delete(currentWorkstreamScope); - pendingHandoffAttempts.delete(currentWorkstreamScope); - syncHandoffEditingState(); - renderHandoffContents(currentReport?.workstreams || []); - editHandoffContentButton.focus(); -} - -function handoffDraftChanged(draft) { - return Object.keys(draft.values).some((name) => draft.values[name] !== draft.initialValues[name]); -} - -function renderHandoffEditorActions(item, draft) { - const available = item !== null; - const editing = draft !== null; - handoffEditorActions.hidden = !available; - editHandoffContentButton.hidden = !available || editing; - saveHandoffRevisionButton.hidden = !editing; - cancelHandoffEditButton.hidden = !editing; - if (available) { - const editKey = item.content === null ? "createFirstRevision" : "editHandoffContent"; - editHandoffContentButton.textContent = translate(editKey); - editHandoffContentButton.setAttribute( - "aria-label", - translate(item.content === null ? "createFirstRevision" : "editHandoffContentLabel") - ); - } - editHandoffContentButton.disabled = revisionSaving || reportLoading; - saveHandoffRevisionButton.disabled = revisionSaving || !draft?.dirty; - cancelHandoffEditButton.disabled = revisionSaving; -} - -function syncHandoffEditingState() { - editorDirty = handoffDrafts.size > 0; - projectSearchInput.disabled = reportLoading || revisionSaving || editorDirty; - workstreamSearchInput.disabled = revisionSaving || editorDirty; - document.querySelectorAll(".workstream-list-item").forEach((button) => { - button.disabled = revisionSaving || editorDirty; - }); - const activeDraft = currentWorkstreamScope === null ? null : handoffDrafts.get(currentWorkstreamScope) || null; - const item = currentReport?.workstreams.find( - (candidate) => candidate.workstream.scope_id === currentWorkstreamScope - ) || null; - renderHandoffEditorActions(item, activeDraft); - updateWorkstreamSwitcherControls(); - updateAutoRefreshStatus(); -} - -function renderActivityBreakdown(workstreams) { - const list = document.getElementById("activity-breakdown-list"); - list.replaceChildren(); - if (workstreams.length === 0) { - const empty = document.createElement("p"); - empty.className = "empty-state"; - empty.textContent = translate("noWorkstreams"); - list.appendChild(empty); - return; - } - for (const item of workstreams) { - const row = document.createElement("div"); - row.className = "activity-breakdown-item"; - const identity = document.createElement("div"); - const title = document.createElement("strong"); - title.textContent = item.workstream.title; - const scope = document.createElement("code"); - scope.textContent = item.workstream.scope_id; - identity.append(title, scope); - const reporting = document.createElement("span"); - reporting.textContent = statusLabel(item.reporting_status); - const count = document.createElement("strong"); - count.textContent = formatNumber(item.observed_activity_count); - row.append(identity, reporting, count); - list.appendChild(row); - } -} - -function renderHandoffWorkstreams(workstreams) { - const selected = workstreams.some((item) => item.workstream.scope_id === currentWorkstreamScope) - ? currentWorkstreamScope - : workstreams[0]?.workstream.scope_id || null; - if (workstreams.length === 0) { - currentWorkstreamScope = null; - renderWorkstreams([]); - renderHandoffContents([]); - renderRevisionHistory(null); - renderContinuity(null); - return; - } - - activateWorkstream(selected); -} - -function activateWorkstream(scopeId) { - const item = currentReport?.workstreams.find((candidate) => candidate.workstream.scope_id === scopeId) || null; - if (item === null) { - return; - } - const scopeChanged = currentWorkstreamScope !== scopeId; - currentWorkstreamScope = scopeId; - rememberSelectedWork(currentProject.project_id, scopeId); - if (scopeChanged) { - handoffSaveStatus.textContent = ""; - handoffSaveStatus.classList.remove("is-error"); - } - renderWorkstreams(currentReport.workstreams); - renderHandoffContents(currentReport.workstreams); - renderRevisionHistory(item); - renderContinuity(item.continuity || null); -} - -function artifactRefsEqual(left, right) { - return left !== null - && right !== null - && left.family === right.family - && left.artifact_id === right.artifact_id - && left.revision === right.revision; -} - -function formatArtifactRef(reference) { - return reference === null ? "-" : `${reference.family}/${reference.artifact_id}@${reference.revision}`; -} - -function draftFromWorkstream(item) { - const content = item.content; - if (content === null) { - return {objective: "", state: "", disposition: "continuable", nextAction: "", omissions: ""}; - } - return { - objective: content.objective, - state: content.state.map((statement) => statement.text).join("\n"), - disposition: content.disposition, - nextAction: content.next_action?.text || "", - omissions: content.omissions.map((omission) => omission.text).join("\n") - }; -} - -function normalizedLines(value) { - return [...new Set(value.split("\n").map((line) => line.trim()).filter(Boolean))]; -} - -async function saveHandoffRevision(item, draft) { - if (currentWorkstreamScope === null || revisionSaving || currentWorkstreamScope !== item.workstream.scope_id) { - return; - } - const values = {...draft.values}; - const objective = values.objective.trim(); - const state = normalizedLines(values.state); - if (!objective || state.length === 0) { - setHandoffSaveStatus("editorRequired", {}, true); - return; - } - - const scopeId = currentWorkstreamScope; - const handoff = { - schema: "powercontext.current-work-handoff.v1", - trust: "untrusted_input", - objective, - state: state.map(declaredClaim), - disposition: values.disposition, - next_action: values.nextAction.trim() ? declaredClaim(values.nextAction.trim()) : null, - omissions: normalizedLines(values.omissions) - }; - const attempt = pendingHandoffAttempt(scopeId, handoff); - setRevisionSaving(true); - setHandoffSaveStatus("savingRevision"); - try { - const prepared = attempt.prepared || await requestJson( - "/v1/work/handoffs/prepare-current", - readServerToken(), - {scope_id: scopeId, source_id: attempt.sourceId, handoff} - ); - attempt.prepared = prepared; - const committed = await requestJson("/v1/handoff/commit", readServerToken(), { - scope_id: scopeId, - handoff: prepared.handoff - }); - pendingHandoffAttempts.delete(scopeId); - handoffDrafts.delete(scopeId); - syncHandoffEditingState(); - await loadReport(readServerToken(), currentProject.project_id, {selectedScopeId: scopeId}); - setHandoffSaveStatus("revisionSaved", {revision: committed.reference.revision}); - } catch (error) { - if (error.status === 401) { - handleRequestError(error); + if (!response.ok) { + showStatus("requestFailed", {status: response.status}); return; } - setHandoffSaveStatus("revisionSaveFailed", {status: error.status || "network"}, true); + const payload = await response.json(); + currentReport = payload.report; + currentStatus = null; + authShell.hidden = true; + pageStatus.hidden = true; + reportShell.hidden = false; + signOut.hidden = !authenticationRequired; + renderReport(currentReport); + } catch (error) { + if (request.isCurrent()) showStatus("serverUnavailable"); } finally { - setRevisionSaving(false); + if (request.isCurrent()) setBusy(false); } } -function setHandoffSaveStatus(key, values = {}, isError = false) { - handoffSaveStatus.textContent = translate(key, values); - handoffSaveStatus.classList.toggle("is-error", isError); -} - -function pendingHandoffAttempt(scopeId, handoff) { - const fingerprint = JSON.stringify(handoff); - const existing = pendingHandoffAttempts.get(scopeId); - if (existing?.fingerprint === fingerprint) { - return existing; - } - const attempt = { - fingerprint, - sourceId: revisionSourceId("handoff-boundary"), - prepared: null - }; - pendingHandoffAttempts.set(scopeId, attempt); - return attempt; -} - -function declaredClaim(text) { - return {text, basis: "declared", evidence: []}; -} - -function setRevisionSaving(saving) { - revisionSaving = saving; - document.querySelectorAll( - ".handoff-content-card :is(button, input, select, textarea), .handoff-editor-actions button" - ).forEach((element) => { - element.disabled = saving; - }); - projectSearchInput.disabled = saving || reportLoading || editorDirty; - syncHandoffEditingState(); -} - -function revisionSourceId(kind) { - const unique = typeof window.crypto?.randomUUID === "function" - ? window.crypto.randomUUID() - : `${Date.now()}-${Math.random().toString(16).slice(2)}`; - return `handoff-report:${kind}:${unique}`; -} - -function renderRevisionHistory(item) { - const list = document.getElementById("handoff-revision-history"); - const summary = document.getElementById("revision-history-summary"); - list.replaceChildren(); - const history = Array.isArray(item?.handoff_history) ? item.handoff_history : []; - if (history.length === 0) { - summary.textContent = translate("revisionHistoryEmpty"); - return; - } - const total = Number(item.handoff_revision_count) || history.length; - summary.textContent = translate( - item.handoff_history_truncated ? "revisionHistoryTruncated" : "revisionHistorySummary", - {shown: history.length, total} - ); - for (const revision of [...history].reverse()) { - const current = artifactRefsEqual(revision.reference, item.handoff_ref); - const row = document.createElement("li"); - row.className = "revision-history-item"; - row.dataset.current = String(current); - if (current) { - row.setAttribute("aria-current", "true"); - } - - const header = document.createElement("div"); - header.className = "revision-history-item-header"; - const reference = document.createElement("code"); - reference.textContent = `@${revision.reference.revision}`; - const disposition = document.createElement("span"); - disposition.className = "revision-history-disposition"; - disposition.textContent = statusLabel(revision.disposition); - header.append(reference, disposition); - if (current) { - const currentLabel = document.createElement("strong"); - currentLabel.textContent = translate("revisionCurrent"); - header.appendChild(currentLabel); - } - - const objective = document.createElement("p"); - objective.className = "revision-history-objective"; - objective.textContent = revision.objective_excerpt; - row.append(header, objective); - if (revision.next_action_excerpt) { - const nextAction = document.createElement("p"); - nextAction.className = "revision-history-next"; - nextAction.textContent = translate("revisionNextAction", {value: revision.next_action_excerpt}); - row.appendChild(nextAction); - } - const counts = document.createElement("p"); - counts.className = "revision-history-counts"; - counts.textContent = translate("revisionCounts", { - state: formatNumber(revision.state_count), - omissions: formatNumber(revision.omission_count) - }); - row.appendChild(counts); - list.appendChild(row); - } -} - -function renderContinuity(continuity) { - const timeline = document.getElementById("continuity-timeline"); - const note = document.getElementById("continuity-note"); - const transferState = document.getElementById("transfer-state-status"); - const outcomeState = document.getElementById("outcome-state-status"); - timeline.replaceChildren(); - continuityTimelineToggle.hidden = true; - if (continuity === null) { - transferState.textContent = "-"; - outcomeState.textContent = "-"; - transferState.removeAttribute("data-state"); - outcomeState.removeAttribute("data-state"); - note.textContent = translate("timelineEmpty"); - return; - } - transferState.textContent = statusLabel(continuity.coverage.transfer_state); - transferState.dataset.state = continuity.coverage.transfer_state; - outcomeState.textContent = statusLabel(continuity.coverage.outcome_state); - outcomeState.dataset.state = continuity.coverage.outcome_state; - const expanded = expandedContinuityScopes.has(continuity.scope_id); - const hiddenEventCount = Math.max(0, continuity.events.length - continuityTimelineRecentLimit); - const visibleEvents = expanded - ? continuity.events - : continuity.events.slice(-continuityTimelineRecentLimit); - for (const event of visibleEvents) { - timeline.appendChild(renderContinuityEvent(continuity.scope_id, event, timeline)); - } - if (hiddenEventCount > 0) { - continuityTimelineToggle.hidden = false; - continuityTimelineToggle.setAttribute("aria-expanded", String(expanded)); - continuityTimelineToggle.textContent = translate( - expanded ? "timelineShowRecent" : "timelineShowEarlier", - expanded ? {count: continuityTimelineRecentLimit} : {count: hiddenEventCount} - ); - } - const notes = []; - if (continuity.events.length === 0) { - notes.push(translate("timelineEmpty")); - } - if (continuity.truncated) { - notes.push(translate("timelineTruncated", { - count: continuity.events.length, - total: continuity.total_event_count - })); - } - if (continuity.invalid_record_count > 0) { - notes.push(translate("timelineInvalid", {count: continuity.invalid_record_count})); - } - note.textContent = notes.join(" "); -} - -function renderContinuityEvent(scopeId, event, timeline) { - const item = document.createElement("li"); - item.dataset.kind = event.kind; - item.dataset.status = event.status; - - const disclosure = document.createElement("details"); - disclosure.className = "continuity-event"; - disclosure.open = openContinuityEvents.get(scopeId) === event.position; - item.dataset.open = String(disclosure.open); - - const toggle = document.createElement("summary"); - const position = document.createElement("span"); - position.className = "continuity-position"; - position.textContent = `#${event.position}`; - const heading = document.createElement("span"); - heading.className = "continuity-event-heading"; - const title = document.createElement("strong"); - title.className = "continuity-event-title"; - title.textContent = statusLabel(event.kind); - const detail = event.summary || (event.actor ? translate("eventActor", {actor: event.actor}) : ""); - const preview = document.createElement("span"); - preview.className = "continuity-event-preview"; - preview.textContent = detail || translate("eventNoDetails"); - heading.append(title, preview); - const status = document.createElement("span"); - status.className = "continuity-event-status"; - status.textContent = statusLabel(event.status); - const arrow = document.createElement("span"); - arrow.className = "continuity-event-arrow"; - arrow.setAttribute("aria-hidden", "true"); - arrow.textContent = "↘"; - toggle.append(position, heading, status, arrow); - - const body = document.createElement("div"); - body.className = "continuity-event-body"; - const metadata = document.createElement("dl"); - metadata.className = "continuity-event-meta"; - if (event.actor && event.summary) { - appendContinuityMeta(metadata, translate("receiverIdentity"), event.actor); - } - if (event.selected_revision !== null) { - appendContinuityMeta(metadata, translate("eventRevision"), formatArtifactRef(event.selected_revision), {code: true}); - } - if (event.handoff_receipt_ref !== null) { - appendContinuityMeta(metadata, translate("eventReceipt"), formatSourceRef(event.handoff_receipt_ref), {code: true}); - } - if (event.receiver_checks !== null) { - appendContinuityMeta(metadata, translate("eventReceiverChecks"), formatReceiverChecks(event.receiver_checks)); - } - appendContinuityMeta(metadata, translate("eventSchema"), event.record_schema, {code: true}); - appendContinuityMeta(metadata, translate("eventSource"), formatSourceRef(event.source_ref), {code: true}); - body.appendChild(metadata); - - disclosure.append(toggle, body); - disclosure.addEventListener("toggle", () => { - item.dataset.open = String(disclosure.open); - if (disclosure.open) { - openContinuityEvents.set(scopeId, event.position); - for (const other of timeline.querySelectorAll("details[open]")) { - if (other !== disclosure) { - other.open = false; - } - } - } else if (openContinuityEvents.get(scopeId) === event.position) { - openContinuityEvents.delete(scopeId); - } - }); - item.appendChild(disclosure); - return item; -} - -function appendContinuityMeta(metadata, labelText, value, {code = false} = {}) { - const item = document.createElement("div"); - const label = document.createElement("dt"); - label.textContent = labelText; - const detail = document.createElement("dd"); - const content = document.createElement(code ? "code" : "span"); - content.textContent = value; - detail.appendChild(content); - item.append(label, detail); - metadata.appendChild(item); -} - -function formatSourceRef(reference) { - const sourceType = reference.source_type || reference.name; - return `${sourceType}/${reference.source_id}`; -} - -function formatReceiverChecks(checks) { - return [ - `${translate("liveStateCheck")}: ${statusLabel(checks.live_state)}`, - `${translate("capabilityCheck")}: ${statusLabel(checks.capability)}`, - `${translate("authorizationCheck")}: ${statusLabel(checks.authorization)}` - ].join(" / "); -} - -function statusBadge(status) { - const badge = document.createElement("span"); - badge.className = `status-badge status-${status.replaceAll("_", "-")}`; - badge.textContent = statusLabel(status); - return badge; -} - -function statusLabel(status) { - return translate(status); -} - -async function downloadMarkdown() { - const token = readServerToken(); - if (!token || currentProject === null) { - showLogin(); - return; - } +async function downloadMarkdown(token) { + const choice = selectedChoice(); + if (choice === null) return; setBusy(true); - clearReportError(); try { - const periodSelection = resolveSelectedPeriod(currentProject); const response = await fetchWithBearer("/v1/handoff-reports/get", token, { method: "POST", headers: {"Content-Type": "application/json"}, - body: JSON.stringify({ - scope_id: currentProject.project_id, - locale: ui.locale() === "zh" ? "zh-CN" : "en", - include_evidence_checks: true, - format: "markdown", - include_archived: false, - download: true, - period: periodSelection.period - }) + body: JSON.stringify({selection: choice.selection, format: "markdown", download: true}) }); - if (response.status === 401) { - clearServerToken(); - showLogin("authRejected"); - return; - } if (!response.ok) { - showReportError("downloadFailed", {status: response.status}); + showStatus("requestFailed", {status: response.status}); return; } - const blob = await response.blob(); - const url = URL.createObjectURL(blob); const link = document.createElement("a"); - link.href = url; + link.href = URL.createObjectURL(await response.blob()); link.download = "handoff-report.md"; link.click(); - URL.revokeObjectURL(url); + URL.revokeObjectURL(link.href); } catch (error) { - showReportError("serverUnavailable"); + showStatus("serverUnavailable"); } finally { setBusy(false); } } -function setBusy(busy) { - previewRetryButton.disabled = busy; - refreshButton.disabled = busy; - downloadButton.disabled = busy; - applyCustomPeriodButton.disabled = busy; - periodStartInput.disabled = busy; - periodEndInput.disabled = busy; - periodButtons.forEach((button) => { - button.disabled = busy; - }); - projectSearchInput.disabled = busy || revisionSaving || editorDirty; - if (busy) { - closeProjectOptions({restoreSelection: true}); - } -} - -function startAutoRefresh() { - if (autoRefreshTimer === null) { - autoRefreshTimer = window.setInterval(() => { - void autoRefreshReport(); - }, autoRefreshIntervalMilliseconds); - } - updateAutoRefreshStatus(); -} - -function stopAutoRefresh() { - if (autoRefreshTimer !== null) { - window.clearInterval(autoRefreshTimer); - autoRefreshTimer = null; - } - autoRefreshStatus.textContent = ""; - autoRefreshStatus.dataset.state = "inactive"; -} - -async function autoRefreshReport() { - const token = readServerToken(); - if (document.hidden || reportLoading || token === null || currentProject === null) { - return; - } - if (editorDirty || revisionSaving) { - updateAutoRefreshStatus(); - return; - } - await loadReport(token, currentProject.project_id, {background: true}); -} - -function updateAutoRefreshStatus() { - if (autoRefreshTimer === null) { - return; - } - if (editorDirty) { - setAutoRefreshStatus("editing"); - } else if (revisionSaving) { - setAutoRefreshStatus("busy"); - } else { - setAutoRefreshStatus("active"); - } +function selectedChoice() { + return buildScopeSelectionChoices(scopes, translate).find((choice) => choice.key === selectedKey) || null; } -function setAutoRefreshStatus(state) { - const translationKeys = { - active: "autoRefreshActive", - busy: "autoRefreshBusy", - editing: "autoRefreshEditing", - failed: "autoRefreshFailed", - refreshing: "autoRefreshing", - updated: "autoRefreshUpdated" - }; - autoRefreshStatus.dataset.state = state; - autoRefreshStatus.textContent = translate(translationKeys[state]); -} - -function resolveSelectedPeriod(project) { - if (project === null || project === undefined) { - throw new Error("reportUnavailable"); - } - return resolvePeriodSelection( - currentPeriodMode, - project.timezone, - appliedCustomRange || {startDate: periodStartInput.value, endDate: periodEndInput.value} - ); -} - -function renderPeriodControls(report = null) { - periodButtons.forEach((button) => { - button.setAttribute("aria-pressed", String(button.dataset.periodMode === currentPeriodMode)); - }); - customPeriodForm.classList.toggle("is-active", currentPeriodMode === "custom"); - const project = currentProject || currentProjects[0] || null; - if (currentPeriodSelection === null && project !== null && currentPeriodMode !== "custom") { - currentPeriodSelection = resolveSelectedPeriod(project); - } - const selection = currentPeriodSelection; - if (selection === null) { - setText("period-summary-label", ""); - setText("period-comparison", ""); - setText("period-boundary-note", ""); - return; - } - if (currentPeriodMode !== "custom") { - periodStartInput.value = selection.startDate; - periodEndInput.value = selection.endDate; +function renderChoices() { + if (scopeSelect === null) return; + scopeSelect.replaceChildren(); + for (const choice of buildScopeSelectionChoices(scopes, translate)) { + const option = document.createElement("option"); + option.value = choice.key; + option.textContent = choice.label; + option.selected = choice.key === selectedKey; + scopeSelect.appendChild(option); } - updatePeriodInputBounds(); - setText("period-summary-label", translate("periodSummary", { - preset: translate(currentPeriodMode), - range: formatDateRange(selection.startDate, selection.endDate, ui.localeTag()), - timezone: selection.period.timezone - })); - const comparison = report?.period_comparison; - setText("period-comparison", comparison === null || comparison === undefined - ? "" - : translate("periodComparison", { - current: formatNumber(comparison.current_activity_count), - previous: formatNumber(comparison.previous_activity_count), - delta: formatSignedNumber(comparison.activity_delta) - })); - setText("period-boundary-note", comparison?.handoff_boundary_coverage === "unavailable" - ? translate("periodBoundaryUnavailable") - : ""); -} - -function updatePeriodInputBounds() { - periodStartInput.setAttribute("aria-invalid", "false"); - periodEndInput.setAttribute("aria-invalid", "false"); -} - -function showPeriodError(key) { - periodError.textContent = translate(key); - periodStartInput.setAttribute("aria-invalid", "true"); - periodEndInput.setAttribute("aria-invalid", "true"); -} - -function clearPeriodError() { - periodError.textContent = ""; - updatePeriodInputBounds(); -} - -function showReportError(key, values = {}) { - reportError.textContent = translate(key, values); -} - -function clearReportError() { - reportError.textContent = ""; } -function rememberSelectedProject(projectId) { - try { - sessionStorage.setItem(selectedProjectKey, projectId); - } catch (error) { - // Project selection remains valid for the current render. - } +function renderReport(report) { + setText("continuable-count", report.summary.continuable_count); + setText("blocked-count", report.summary.blocked_count); + setText("complete-count", report.summary.complete_count); + setText("no-handoff-count", report.summary.no_handoff_count); + setText("generated-at", formatDateTime(report.generated_at)); + setText("selection-digest", report.selection_digest); + setText("report-digest", report.report_digest); + const rows = document.getElementById("scope-report-rows"); + rows.replaceChildren(); + for (const entry of report.scopes) { + const row = document.createElement("tr"); + appendCell(row, entry.scope.title, entry.scope.scope_id); + appendCell(row, entry.scope.parent_scope_id || "—"); + appendCell(row, translate(entry.status)); + appendCell(row, entry.content?.objective || "—"); + appendCell(row, entry.content?.next_action?.text || "—"); + appendCell(row, formatAddress(entry.handoff), null, true); + rows.appendChild(row); + } +} + +function appendCell(row, value, detail = null, code = false) { + const cell = document.createElement("td"); + const primary = document.createElement(code ? "code" : "span"); + primary.textContent = value; + cell.appendChild(primary); + if (detail !== null) { + const secondary = document.createElement("code"); + secondary.textContent = detail; + cell.appendChild(document.createElement("br")); + cell.appendChild(secondary); + } + row.appendChild(cell); +} + +function formatAddress(address) { + if (address === null) return "—"; + const artifact = address.artifact; + return `${address.scope_id}/${artifact.family}/${artifact.artifact_id}@${artifact.revision}`; +} + +function showLogin(messageKey = "") { + requests.cancel(); + currentReport = null; + reportShell.hidden = true; + pageStatus.hidden = true; + authShell.hidden = false; + signOut.hidden = true; + authError.textContent = messageKey ? translate(messageKey) : ""; + tokenInput.focus(); } -function readSelectedProject() { - try { - return sessionStorage.getItem(selectedProjectKey); - } catch (error) { - return null; - } +function showStatus(key, values = {}) { + currentStatus = {key, values}; + currentReport = null; + authShell.hidden = true; + reportShell.hidden = true; + pageStatus.hidden = false; + pageStatusRetry.hidden = false; + renderStatus(); } -function rememberSelectedWork(projectId, scopeId) { - try { - sessionStorage.setItem(selectedWorkKey, JSON.stringify([projectId, scopeId])); - } catch (error) { - // Work selection remains valid for the current render. +function renderStatus() { + if (currentStatus !== null) { + pageStatusMessage.textContent = translate(currentStatus.key, currentStatus.values); } } -function readSelectedWorkLocation() { - try { - const value = JSON.parse(sessionStorage.getItem(selectedWorkKey)); - return Array.isArray(value) && value.length === 2 && value.every((part) => typeof part === "string") - ? {projectId: value[0], scopeId: value[1]} - : null; - } catch (error) { - return null; - } +function setBusy(busy) { + scopeSelect.disabled = busy; + refreshButton.disabled = busy; + downloadButton.disabled = busy; } function setText(id, value) { - document.getElementById(id).textContent = value; -} - -function formatSignedNumber(value) { - return new Intl.NumberFormat(ui.localeTag(), {signDisplay: "always"}).format(value); + document.getElementById(id).textContent = String(value); } ui.initialize(); diff --git a/src/powercontext/server/static/scope-selection.js b/src/powercontext/server/static/scope-selection.js new file mode 100644 index 000000000..2f60c0471 --- /dev/null +++ b/src/powercontext/server/static/scope-selection.js @@ -0,0 +1,36 @@ +/* + * Copyright (c) 2026 OceanBase. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +"use strict"; + +export function buildScopeSelectionChoices(scopes, translate) { + const choices = [{key: "all", label: translate("allScopes"), selection: {mode: "all"}}]; + for (const scope of scopes.filter((item) => item.parent_scope_id === null)) { + choices.push({ + key: `subtree:${scope.scope_id}`, + label: translate("subtreeView", {title: scope.display_name || scope.title}), + selection: {mode: "subtree", root_scope_id: scope.scope_id} + }); + } + for (const scope of scopes) { + choices.push({ + key: `exact:${scope.scope_id}`, + label: translate("exactFocus", {title: scope.display_name || scope.title}), + selection: {mode: "exact", scope_ids: [scope.scope_id]} + }); + } + return choices; +} diff --git a/src/powercontext/server/static/site.css b/src/powercontext/server/static/site.css index 9a4507c4e..0df7182ee 100644 --- a/src/powercontext/server/static/site.css +++ b/src/powercontext/server/static/site.css @@ -470,12 +470,10 @@ button:disabled { border-color: var(--pc-accent); } -.project-combobox, .scope-combobox { position: relative; } -.project-combobox > input, .scope-combobox > input { width: 100%; min-height: 40px; @@ -486,14 +484,11 @@ button:disabled { padding: 8px 10px; } -.project-combobox > input:hover, -.project-combobox > input:focus, .scope-combobox > input:hover, .scope-combobox > input:focus { border-color: var(--pc-accent); } -.project-options, .scope-options { position: absolute; z-index: 10; @@ -508,7 +503,6 @@ button:disabled { overflow-y: auto; } -.project-option, .scope-option { display: grid; width: 100%; @@ -522,37 +516,30 @@ button:disabled { text-align: left; } -.project-option:last-child, .scope-option:last-child { border-bottom: 0; } -.project-option:hover, -.project-option[data-active="true"], .scope-option:hover, .scope-option[data-active="true"] { background: var(--pc-accent-soft); } -.project-option[aria-selected="true"], .scope-option[aria-selected="true"] { box-shadow: inset 3px 0 0 var(--pc-accent); } -.project-option strong, .scope-option strong { font-size: 13px; overflow-wrap: anywhere; } -.project-option code, .scope-option code { color: var(--pc-muted); font: 10px/1.4 var(--pc-font-code); overflow-wrap: anywhere; } -.project-options-empty, .scope-options-empty { margin: 0; color: var(--pc-muted); @@ -560,7 +547,6 @@ button:disabled { text-align: center; } -.project-search-status, .scope-search-status { min-height: 17px; color: var(--pc-muted); @@ -950,10 +936,6 @@ button:disabled { background: var(--pc-surface-secondary); } -.report-preview-workstream-item { - cursor: default; -} - .report-hero { align-items: flex-start; margin-bottom: 24px; @@ -965,10 +947,6 @@ button:disabled { gap: 10px; } -.report-project-picker { - min-width: min(360px, 70vw); -} - .report-actions { display: flex; flex-wrap: wrap; @@ -1229,78 +1207,6 @@ button:disabled { font-weight: 650; } -.workstream-browser-layout { - display: grid; - gap: 12px; -} - -.workstream-switcher-toolbar { - display: flex; - align-items: end; - justify-content: space-between; - gap: 12px; -} - -.workstream-search { - display: grid; - width: min(360px, 100%); -} - -.workstream-search input { - width: 100%; - min-height: 38px; - border: 1px solid var(--pc-rule-strong); - border-radius: var(--pc-radius-control); - background: var(--pc-surface); - color: var(--pc-ink); - padding: 8px 10px; -} - -.workstream-search input:hover, -.workstream-search input:focus { - border-color: var(--pc-accent); -} - -.workstream-switcher-navigation { - display: flex; - align-items: center; - gap: 8px; - margin-left: auto; -} - -.workstream-navigation-button { - min-height: 38px; - border: 1px solid var(--pc-rule-strong); - border-radius: var(--pc-radius-control); - background: var(--pc-surface); - color: var(--pc-ink); - padding: 0 12px; - white-space: nowrap; -} - -.workstream-navigation-button:hover:not(:disabled) { - border-color: var(--pc-accent); - color: var(--pc-accent); -} - -.workstream-navigation-button:active:not(:disabled) { - transform: translateY(1px); -} - -.workstream-navigation-button:disabled { - color: var(--pc-muted); - cursor: not-allowed; - opacity: 0.55; -} - -.workstream-position { - min-width: 72px; - color: var(--pc-muted); - font: 11px/1.4 var(--pc-font-code); - text-align: center; -} - -.workstream-list-panel, .handoff-snapshot { min-width: 0; border: 1px solid var(--pc-rule-strong); @@ -1308,70 +1214,6 @@ button:disabled { background: var(--pc-surface); } -.workstream-list-panel { - overflow-x: auto; - overflow-y: hidden; - scroll-snap-type: x proximity; - scrollbar-gutter: stable; -} - -.workstream-list { - display: flex; - width: max-content; - min-width: 100%; -} - -.workstream-list-item { - display: grid; - flex: 1 0 260px; - gap: 5px; - border: 0; - border-right: 1px solid var(--pc-rule); - border-radius: 0; - background: transparent; - color: var(--pc-ink); - padding: 12px 15px 14px; - scroll-snap-align: start; - text-align: left; - transition: background-color 160ms ease, box-shadow 160ms ease, transform 160ms ease; -} - -.workstream-list-item:last-child { - border-right: 0; -} - -.workstream-list-item:hover { - background: var(--pc-surface-secondary); -} - -.workstream-list-item:active { - transform: translateY(1px); -} - -.workstream-list-item[aria-current="true"] { - background: var(--pc-accent-soft); - box-shadow: inset 0 -3px 0 var(--pc-accent); -} - -.workstream-list-item-header { - display: flex; - align-items: flex-start; - justify-content: space-between; - gap: 12px; -} - -.workstream-list-item-header strong { - font-size: 13px; - line-height: 1.45; - overflow-wrap: anywhere; -} - -.workstream-list-item code { - color: var(--pc-muted); - font: 10px/1.45 var(--pc-font-code); - overflow-wrap: anywhere; -} - .handoff-snapshot { padding: 20px 22px 22px; } @@ -4129,12 +3971,6 @@ button:disabled { justify-items: start; } - .report-project-picker { - width: 100%; - min-width: 0; - } - - .project-options, .scope-options { max-height: min(320px, 52vh); } @@ -4255,20 +4091,6 @@ button:disabled { flex-direction: column; } - .workstream-switcher-toolbar { - align-items: stretch; - flex-direction: column; - } - - .workstream-search { - width: 100%; - } - - .workstream-switcher-navigation { - justify-content: space-between; - margin-left: 0; - } - .workbench-selection { width: 100%; align-items: flex-start; diff --git a/src/powercontext/server/templates/pages/handoff_report.html b/src/powercontext/server/templates/pages/handoff_report.html index 3a9cc941a..505f6f28d 100644 --- a/src/powercontext/server/templates/pages/handoff_report.html +++ b/src/powercontext/server/templates/pages/handoff_report.html @@ -25,485 +25,65 @@ {% set status_title = "Handoff Report" %} {% include "components/status.html" %} - -
Report metadata
-
Selection consistency
-
Activity coverage
+
Generated at
Selection digest
Report digest
@@ -512,5 +92,5 @@

Activity by W {% endblock %} {% block scripts %} - + {% endblock %} diff --git a/src/powercontext/server/web.py b/src/powercontext/server/web.py index b3f8f023a..c21e3b445 100644 --- a/src/powercontext/server/web.py +++ b/src/powercontext/server/web.py @@ -18,7 +18,6 @@ import asyncio import logging -from collections.abc import Mapping from functools import cache from typing import Literal @@ -40,6 +39,7 @@ ) from powercontext.builtin.review import CandidateStatus from powercontext.builtin.runtime import GetArtifactCandidateRequest, GetSkillRequest, ListExternalSkillsRequest +from powercontext.builtin.scope import ScopeNotFoundError from powercontext.http import ErrorDetail, ErrorResponse from powercontext.limits import MAX_ARTIFACT_ID_LENGTH @@ -55,12 +55,14 @@ class DashboardScope(BaseModel): - """One Server scope exposed by the personal Dashboard.""" + """One durable Scope exposed by the personal Dashboard.""" model_config = ConfigDict(extra="forbid") scope_id: str display_name: str + summary: str + parent_scope_id: str | None = None class DashboardSkillProjectionRequest(BaseModel): @@ -112,8 +114,7 @@ class DashboardSkillProjection(BaseModel): class _DashboardSkillProjectionRoutes: - def __init__(self, scope_ids: frozenset[str], targets: tuple[AgentSkillTarget, ...]) -> None: - self._scope_ids = scope_ids + def __init__(self, targets: tuple[AgentSkillTarget, ...]) -> None: self._targets = targets async def inspect( @@ -121,7 +122,7 @@ async def inspect( request: DashboardSkillProjectionRequest, http_request: Request, ) -> DashboardSkillProjection | JSONResponse: - resolved = await _dashboard_managed_skill(http_request, request, self._scope_ids) + resolved = await _dashboard_managed_skill(http_request, request) if isinstance(resolved, JSONResponse): return resolved application, skill = resolved @@ -132,7 +133,7 @@ async def publish( request: DashboardSkillPublishRequest, http_request: Request, ) -> DashboardSkillProjection | JSONResponse: - resolved = await _dashboard_managed_skill(http_request, request, self._scope_ids) + resolved = await _dashboard_managed_skill(http_request, request) if isinstance(resolved, JSONResponse): return resolved application, skill = resolved @@ -175,10 +176,9 @@ async def publish( return await _skill_projection_response(application, request.scope_id, skill, self._targets) -def mount_web_ui( +def mount_web_ui( # noqa: C901 app: FastAPI, *, - scopes: Mapping[str, str], dashboard_enabled: bool = False, handoff_report_enabled: bool = False, authentication_required: bool = False, @@ -186,10 +186,8 @@ def mount_web_ui( ) -> None: """Mount Server-owned pages, static assets, and UI support endpoints.""" - dashboard_scopes = tuple(DashboardScope(scope_id=scope_id, display_name=name) for scope_id, name in scopes.items()) - dashboard_scope_ids = frozenset(scopes) publish_targets = tuple(target for target in agent_skill_targets if target.allow_managed_publish) - skill_projection_routes = _DashboardSkillProjectionRoutes(dashboard_scope_ids, publish_targets) + skill_projection_routes = _DashboardSkillProjectionRoutes(publish_targets) templates = _templates() if dashboard_enabled: templates.env.get_template("pages/dashboard.html") @@ -265,9 +263,9 @@ async def handoff_report_page(request: Request) -> Response: headers=_PAGE_HEADERS, ) - async def list_dashboard_scopes(response: Response) -> tuple[DashboardScope, ...]: + async def list_dashboard_scopes(request: Request, response: Response) -> tuple[DashboardScope, ...]: response.headers["Cache-Control"] = "no-store" - return dashboard_scopes + return await _dashboard_scopes(request.app.state.application) if dashboard_enabled: router.add_api_route( @@ -277,13 +275,6 @@ async def list_dashboard_scopes(response: Response) -> tuple[DashboardScope, ... response_class=HTMLResponse, name="dashboard_home", ) - router.add_api_route( - "/dashboard/scopes", - list_dashboard_scopes, - methods=["GET"], - response_model=list[DashboardScope], - name="dashboard_scopes", - ) router.add_api_route( "/skills", skills_page, @@ -312,6 +303,14 @@ async def list_dashboard_scopes(response: Response) -> tuple[DashboardScope, ... response_model=DashboardSkillProjection, name="dashboard_skill_projection_publish", ) + if dashboard_enabled or handoff_report_enabled: + router.add_api_route( + "/dashboard/scopes", + list_dashboard_scopes, + methods=["GET"], + response_model=list[DashboardScope], + name="dashboard_scopes", + ) if handoff_report_enabled: router.add_api_route( "/handoff-reports", @@ -341,13 +340,16 @@ def _templates() -> Jinja2Templates: async def _dashboard_managed_skill( request: Request, selection: DashboardSkillProjectionRequest, - dashboard_scope_ids: frozenset[str], ): - if selection.scope_id not in dashboard_scope_ids: - return _web_error(404, "dashboard_scope_not_found", "The Dashboard scope was not found.") application = request.app.state.application if application is None: return _web_error(503, "runtime_not_ready", "The Runtime is not ready.") + if application.scopes is None: + return _web_error(503, "runtime_not_ready", "The Runtime is not ready.") + try: + await application.scopes.get(selection.scope_id) + except ScopeNotFoundError: + return _web_error(404, "dashboard_scope_not_found", "The Dashboard scope was not found.") candidate = await application.review.for_scope(selection.scope_id).get( GetArtifactCandidateRequest(candidate_id=selection.candidate_id) ) @@ -365,6 +367,20 @@ async def _dashboard_managed_skill( return application, skill +async def _dashboard_scopes(application) -> tuple[DashboardScope, ...]: + if application is None or application.scopes is None: + return () + return tuple( + DashboardScope( + scope_id=scope.scope_id, + display_name=scope.title, + summary=scope.summary, + parent_scope_id=scope.parent_scope_id, + ) + for scope in await application.scopes.list() + ) + + async def _skill_projection_response( application, scope_id: str, From 5cce29bdbe9792e2873b90ecd7fb034e1819e10a Mon Sep 17 00:00:00 2001 From: Chojan Shang Date: Wed, 2 Sep 2026 16:12:45 +0800 Subject: [PATCH 05/17] feat(integrations): resolve server-owned scopes --- .github/workflows/build-artifacts.yml | 46 +- .licenserc.yaml | 4 +- e2e/bub/src/powercontext_e2e/runner.py | 48 +- e2e/bub/tests/test_bub_capture.py | 5 + e2e/bub/tests/test_bub_scope_binding.py | 137 + .../skills/project-context/SKILL.md | 24 +- integrations/bub/README.md | 7 +- .../bub/src/powercontext_bub/plugin.py | 78 +- .../bub/src/powercontext_bub/scope.py | 53 + .../bub/src/powercontext_bub/tools.py | 39 +- integrations/claude-code/README.md | 7 +- .../plugins/powercontext/README.md | 6 +- .../powercontext/hooks/user_prompt_submit.py | 9 +- .../powercontext/scripts/project_scope.py | 224 - .../powercontext/scripts/workspace_scope.py | 267 + .../skills/project-context/SKILL.md | 40 +- .../codex/plugins/powercontext/README.md | 16 +- .../plugins/powercontext/hooks/bind_tools.py | 148 + .../plugins/powercontext/hooks/hooks.json | 24 + .../plugins/powercontext/hooks/recall.py | 10 +- .../powercontext/hooks/session_binding.py | 54 + .../powercontext/scripts/project_scope.py | 224 - .../powercontext/scripts/scope_binding.py | 205 + .../skills/project-context/SKILL.md | 86 +- .../dsh/plugins/powercontext/README.md | 5 +- .../dsh/plugins/powercontext/lib/index.js | 430 +- .../powercontext/openapi/powercontext.yaml | 4642 ----------------- .../dsh/plugins/powercontext/package.json | 8 +- .../dsh/plugins/powercontext/pnpm-lock.yaml | 69 +- .../plugins/powercontext/pnpm-workspace.yaml | 3 + .../powercontext/scripts/e2e-server.mjs | 5 +- .../powercontext/scripts/gen-operations.mjs | 69 - .../powercontext/scripts/openapi-ops.mjs | 128 - .../plugins/powercontext/scripts/prepare.mjs | 3 - .../powercontext/scripts/sync-openapi.mjs | 77 - .../dsh/plugins/powercontext/src/client.ts | 33 +- .../dsh/plugins/powercontext/src/commands.ts | 4 +- .../dsh/plugins/powercontext/src/index.ts | 4 +- .../dsh/plugins/powercontext/src/invoke.ts | 7 +- .../powercontext/src/operations.generated.ts | 103 +- .../dsh/plugins/powercontext/src/scope.ts | 100 +- .../dsh/plugins/powercontext/src/tools.ts | 2 +- .../plugins/powercontext/tests/client.spec.ts | 34 +- .../powercontext/tests/commands.spec.ts | 11 +- .../tests/e2e/call-through.spec.ts | 17 +- .../tests/e2e/unscoped-session.spec.ts | 54 +- .../powercontext/tests/gen-check.spec.ts | 42 - .../plugins/powercontext/tests/invoke.spec.ts | 51 +- .../tests/operations-coverage.spec.ts | 68 - .../tests/recall-fail-open.spec.ts | 13 +- .../plugins/powercontext/tests/scope.spec.ts | 85 +- .../plugins/powercontext/tests/tools.spec.ts | 2 +- integrations/hermes/README.md | 23 +- .../plugins/powercontext-command/__init__.py | 4 +- .../hermes/plugins/powercontext/README.md | 10 +- .../hermes/plugins/powercontext/cli.py | 4 +- .../hermes/plugins/powercontext/client.py | 21 + .../hermes/plugins/powercontext/commands.py | 45 +- .../plugins/powercontext/config_schema.py | 13 +- .../hermes/plugins/powercontext/helpers.py | 11 - .../hermes/plugins/powercontext/provider.py | 107 +- .../powercontext/skills/powercontext/SKILL.md | 2 +- .../hermes/plugins/powercontext/workstream.py | 102 - integrations/langchain/README.md | 5 +- .../src/powercontext_langchain/__init__.py | 4 +- .../src/powercontext_langchain/client.py | 25 +- .../src/powercontext_langchain/middleware.py | 30 +- .../src/powercontext_langchain/scope.py | 107 +- integrations/langgraph/README.md | 20 +- .../examples/agent_memory_roundtrip.py | 3 +- .../langgraph/examples/inspect_recall.py | 8 +- .../src/powercontext_langgraph/__init__.py | 4 +- .../src/powercontext_langgraph/client.py | 28 +- .../src/powercontext_langgraph/recall.py | 37 +- .../src/powercontext_langgraph/scope.py | 117 +- .../src/powercontext_langgraph/tools.py | 20 +- integrations/openclaw/README.md | 22 +- .../plugins/memory-powercontext/index.ts | 4 +- .../memory-powercontext/openclaw.plugin.json | 16 +- .../memory-powercontext/pnpm-workspace.yaml | 3 + .../scripts/configure-openclaw.py | 12 +- .../memory-powercontext/src/config.test.ts | 18 +- .../plugins/memory-powercontext/src/config.ts | 24 +- .../memory-powercontext/src/lifecycle.test.ts | 55 +- .../memory-powercontext/src/lifecycle.ts | 49 +- .../memory-powercontext/src/manager.test.ts | 32 +- .../memory-powercontext/src/manager.ts | 27 +- .../memory-powercontext/src/scope.test.ts | 82 + .../plugins/memory-powercontext/src/scope.ts | 92 + .../memory-powercontext/src/tools.test.ts | 35 + .../plugins/memory-powercontext/src/tools.ts | 29 +- .../opencode/plugins/powercontext/README.md | 4 +- .../plugins/powercontext/lib/index.js | 443 +- .../plugins/powercontext/package.json | 2 +- .../plugins/powercontext/pnpm-workspace.yaml | 3 + .../skills/project-context/SKILL.md | 2 +- .../plugins/powercontext/src/client.ts | 35 +- .../plugins/powercontext/src/index.ts | 49 +- .../plugins/powercontext/src/invoke.ts | 7 +- .../powercontext/src/operations.generated.ts | 103 +- .../plugins/powercontext/src/scope.ts | 86 +- .../plugins/powercontext/tests/client.spec.ts | 27 + .../plugins/powercontext/tests/plugin.spec.ts | 46 +- .../plugins/powercontext/tests/scope.spec.ts | 48 +- .../pi/plugins/powercontext/README.md | 6 +- .../powercontext/extensions/powercontext.ts | 12 +- .../pi/plugins/powercontext/package.json | 2 +- .../plugins/powercontext/pnpm-workspace.yaml | 3 + .../skills/project-context/SKILL.md | 2 +- .../pi/plugins/powercontext/src/client.ts | 43 +- .../pi/plugins/powercontext/src/invoke.ts | 7 +- .../powercontext/src/operations.generated.ts | 103 +- .../pi/plugins/powercontext/src/recall.ts | 13 +- .../pi/plugins/powercontext/src/scope.ts | 97 +- .../pi/plugins/powercontext/src/tools.ts | 2 +- .../plugins/powercontext/tests/client.spec.ts | 27 + .../powercontext/tests/commands.spec.ts | 10 +- .../powercontext/tests/extension.spec.ts | 40 +- .../plugins/powercontext/tests/invoke.spec.ts | 33 +- .../plugins/powercontext/tests/scope.spec.ts | 38 +- integrations/pydantic-ai/README.md | 9 +- .../powercontext_pydantic_ai/capability.py | 12 +- .../src/powercontext_pydantic_ai/scope.py | 111 +- .../src/powercontext_pydantic_ai/settings.py | 4 +- .../src/powercontext_pydantic_ai/toolset.py | 37 +- integrations/workbuddy/README.md | 12 +- .../workbuddy/plugins/powercontext/README.md | 7 +- ...scope.py => powercontext_scope_binding.py} | 4 +- .../hooks/workbuddy_powercontext_hook.py | 15 +- .../powercontext/scripts/project_scope.py | 231 - .../powercontext/scripts/workspace_scope.py | 269 + .../skills/project-context/SKILL.md | 44 +- 132 files changed, 3303 insertions(+), 7825 deletions(-) create mode 100644 e2e/bub/tests/test_bub_scope_binding.py create mode 100644 integrations/bub/src/powercontext_bub/scope.py delete mode 100644 integrations/claude-code/plugins/powercontext/scripts/project_scope.py create mode 100644 integrations/claude-code/plugins/powercontext/scripts/workspace_scope.py create mode 100644 integrations/codex/plugins/powercontext/hooks/bind_tools.py create mode 100644 integrations/codex/plugins/powercontext/hooks/session_binding.py delete mode 100644 integrations/codex/plugins/powercontext/scripts/project_scope.py create mode 100644 integrations/codex/plugins/powercontext/scripts/scope_binding.py delete mode 100644 integrations/dsh/plugins/powercontext/openapi/powercontext.yaml delete mode 100644 integrations/dsh/plugins/powercontext/scripts/gen-operations.mjs delete mode 100644 integrations/dsh/plugins/powercontext/scripts/openapi-ops.mjs delete mode 100644 integrations/dsh/plugins/powercontext/scripts/sync-openapi.mjs delete mode 100644 integrations/dsh/plugins/powercontext/tests/gen-check.spec.ts delete mode 100644 integrations/dsh/plugins/powercontext/tests/operations-coverage.spec.ts delete mode 100644 integrations/hermes/plugins/powercontext/workstream.py mode change 100755 => 100644 integrations/openclaw/plugins/memory-powercontext/scripts/configure-openclaw.py create mode 100644 integrations/openclaw/plugins/memory-powercontext/src/scope.test.ts create mode 100644 integrations/openclaw/plugins/memory-powercontext/src/scope.ts rename integrations/workbuddy/plugins/powercontext/hooks/{powercontext_project_scope.py => powercontext_scope_binding.py} (81%) delete mode 100644 integrations/workbuddy/plugins/powercontext/scripts/project_scope.py create mode 100644 integrations/workbuddy/plugins/powercontext/scripts/workspace_scope.py diff --git a/.github/workflows/build-artifacts.yml b/.github/workflows/build-artifacts.yml index bbc2124bb..2cf17bc38 100644 --- a/.github/workflows/build-artifacts.yml +++ b/.github/workflows/build-artifacts.yml @@ -256,34 +256,26 @@ jobs: python_executable = f"python{os.environ['PYTHON_VERSION']}" hooks_path = root / "hooks/hooks.json" hooks = json.loads(hooks_path.read_text()) - recall_hook = hooks["hooks"]["UserPromptSubmit"][0]["hooks"][0] - expected = ( - 'uv run --locked --quiet --project "${PLUGIN_ROOT}" ' - 'python "${PLUGIN_ROOT}/hooks/recall.py"' - ) - if recall_hook["command"] != expected: - raise SystemExit("unexpected Codex recall command") - recall_hook["command"] = ( - 'PYTHONPATH="${PLUGIN_ROOT}/vendor" ' - + python_executable - + ' "${PLUGIN_ROOT}/hooks/recall.py"' - ) + hook_scripts = { + "SessionStart": "session_binding.py", + "PreToolUse": "bind_tools.py", + "UserPromptSubmit": "recall.py", + } + for event, script in hook_scripts.items(): + hook = hooks["hooks"][event][0]["hooks"][0] + expected = ( + 'uv run --frozen --quiet --project "${PLUGIN_ROOT}" ' + f'python "${{PLUGIN_ROOT}}/hooks/{script}"' + ) + if hook["command"] != expected: + raise SystemExit(f"unexpected Codex {event} command") + hook["command"] = ( + 'PYTHONPATH="${PLUGIN_ROOT}/vendor" ' + + python_executable + + f' "${{PLUGIN_ROOT}}/hooks/{script}"' + ) hooks_path.write_text(json.dumps(hooks, indent=2) + "\n") - skill_path = root / "skills/project-context/SKILL.md" - skill = skill_path.read_text() - expected_skill = ( - 'uv run --locked --quiet --project "$PLUGIN_ROOT" python ' - '"$PLUGIN_ROOT/scripts/project_scope.py" --cwd "$PWD"' - ) - replacement_skill = ( - f'PYTHONPATH="$PLUGIN_ROOT/vendor" {python_executable} ' - '"$PLUGIN_ROOT/scripts/project_scope.py" --cwd "$PWD"' - ) - if skill.count(expected_skill) != 1: - raise SystemExit("unexpected project-context Skill command") - skill_path.write_text(skill.replace(expected_skill, replacement_skill)) - readme_path = root / "README.md" readme = readme_path.read_text() expected_readme = ( @@ -381,7 +373,7 @@ jobs: ( cd "$plugin_root" PYTHONPATH="$plugin_root/vendor" \ - "python${PYTHON_VERSION}" scripts/project_scope.py --cwd "$GITHUB_WORKSPACE" + "python${PYTHON_VERSION}" -m compileall -q hooks scripts ) - name: Create compressed artifact diff --git a/.licenserc.yaml b/.licenserc.yaml index 76e51257a..47dd00a1f 100644 --- a/.licenserc.yaml +++ b/.licenserc.yaml @@ -43,7 +43,9 @@ header: - '**/LICENSE' - 'NOTICE' - '**/LICENSE.oceanbase-design' - - '**/uv.lock' + - '**/*.lock' + - '**/*-lock.yaml' + - '**/*.lockb' - 'benchmark/locomo/dataset/**' - 'benchmark/locomo/results/**' - 'tox.ini' diff --git a/e2e/bub/src/powercontext_e2e/runner.py b/e2e/bub/src/powercontext_e2e/runner.py index c4d930de3..97c9c4f21 100644 --- a/e2e/bub/src/powercontext_e2e/runner.py +++ b/e2e/bub/src/powercontext_e2e/runner.py @@ -39,7 +39,7 @@ from harbor.models.trial.result import StepResult from powercontext.client import PowerContextClient from powercontext.client.settings import ClientSettings -from powercontext.http import ListMemoryEntriesRequest, PrepareContextRequest +from powercontext.http import CreateScopeRequest, ListMemoryEntriesRequest, PrepareContextRequest from .artifacts import write_artifacts from .catalog import E2ETask, MemoryEvaluationSpec, OutcomeEvaluationSpec @@ -217,30 +217,42 @@ async def run_task_group( else None ) run_id = _run_id(tasks) - scopes = {task.id: f"e2e:{run_id}:{task.id}" if runtime else f"e2e:{run_id}" for task in tasks} - runs = {task.id: TaskRun(task, run_id, scopes[task.id], datetime.now(UTC), MemorySnapshot()) for task in tasks} - invocation_scopes = ( - tuple(scopes[source.task.id] for source in runtime.sources for _ in source.runtime_steps) if runtime else () - ) - job_config = _job_config( - tasks[0], - run_id, - scopes[tasks[0].id], - output_dir, - settings, - runtime=runtime, - invocation_scopes=invocation_scopes, - ) harbor = HarborTrialObservation() step_results: tuple[StepResult, ...] = () trial_dir: Path | None = None execution_errors: list[str] = [] async with _powercontext_client() as client: + memory_tasks = tuple(task for task in tasks if isinstance(task.evaluation, MemoryEvaluationSpec)) + if memory_tasks: + await client.get_readiness() + started_at = datetime.now(UTC) + scopes = { + task.id: ( + await client.create_scope( + CreateScopeRequest( + title=f"E2E workload: {task.id}", + summary=f"Isolated Scope for the {task.id} workload in E2E run {run_id}.", + idempotency_key=f"e2e:{run_id}:{task.id}", + ) + ) + ).scope_id + for task in tasks + } + runs = {task.id: TaskRun(task, run_id, scopes[task.id], started_at, MemorySnapshot()) for task in tasks} + invocation_scopes = ( + tuple(scopes[source.task.id] for source in runtime.sources for _ in source.runtime_steps) if runtime else () + ) + job_config = _job_config( + tasks[0], + run_id, + scopes[tasks[0].id], + output_dir, + settings, + runtime=runtime, + invocation_scopes=invocation_scopes, + ) try: - memory_tasks = tuple(task for task in tasks if isinstance(task.evaluation, MemoryEvaluationSpec)) - if memory_tasks: - await client.get_readiness() for task in memory_tasks: run = runs[task.id] runs[task.id] = run._replace(memory_before=await memory_snapshot(client, run.scope_id)) diff --git a/e2e/bub/tests/test_bub_capture.py b/e2e/bub/tests/test_bub_capture.py index 828cab107..ef812975d 100644 --- a/e2e/bub/tests/test_bub_capture.py +++ b/e2e/bub/tests/test_bub_capture.py @@ -45,6 +45,10 @@ async def capture_content_source(self, request: Any) -> SimpleNamespace: captured_requests.append(request) return SimpleNamespace(position=1) + async def resolve_scope_binding(self, request: Any) -> SimpleNamespace: + assert request.explicit_scope_id == "test:scope" + return SimpleNamespace(scope_id="scp_00000000000000000000000000") + settings = PowerContextSettings( base_url="http://127.0.0.1:8000", scope_id="test:scope", @@ -73,6 +77,7 @@ async def capture_content_source(self, request: Any) -> SimpleNamespace: assert len(captured_requests) == 1 request = captured_requests[0] + assert request.scope_id == "scp_00000000000000000000000000" assert request.metadata["event"] == "tool_result" assert sensitive_value not in request.content assert "[REDACTED]" in request.content diff --git a/e2e/bub/tests/test_bub_scope_binding.py b/e2e/bub/tests/test_bub_scope_binding.py new file mode 100644 index 000000000..82040656e --- /dev/null +++ b/e2e/bub/tests/test_bub_scope_binding.py @@ -0,0 +1,137 @@ +# Copyright (c) 2026 OceanBase. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +from __future__ import annotations + +import asyncio +from pathlib import Path +from types import SimpleNamespace +from typing import Any, ClassVar + +from bub.hooks.interception import LlmCallRequest +from powercontext_bub import plugin as plugin_module +from powercontext_bub import tools as tools_module +from powercontext_bub.plugin import STATE_KEY, PowerContextPlugin, PowerContextSettings +from powercontext_bub.scope import workspace_binding_key + +RESOLVED_SCOPE_ID = "scp_00000000000000000000000000" + + +class RecordingClient: + calls: ClassVar[list[tuple[str, Any]]] = [] + scope_ids: ClassVar[list[str]] = [RESOLVED_SCOPE_ID] + + def __init__(self, base_url: str, *, timeout: float) -> None: + del base_url, timeout + + async def __aenter__(self) -> RecordingClient: + return self + + async def __aexit__(self, *exc_info: object) -> None: + del exc_info + + async def resolve_scope_binding(self, request: Any) -> SimpleNamespace: + self.calls.append(("resolve", request)) + index = len([name for name, _ in self.calls if name == "resolve"]) - 1 + return SimpleNamespace(scope_id=self.scope_ids[min(index, len(self.scope_ids) - 1)]) + + async def capture_content_source(self, request: Any) -> SimpleNamespace: + self.calls.append(("capture", request)) + return SimpleNamespace(position=1) + + async def prepare_context(self, request: Any) -> SimpleNamespace: + self.calls.append(("prepare", request)) + return SimpleNamespace( + content="remembered context", + content_bytes=18, + status=SimpleNamespace(value="ready"), + ) + + async def search_memory(self, request: Any) -> SimpleNamespace: + self.calls.append(("search", request)) + return SimpleNamespace(hits=[]) + + +def _plugin(monkeypatch, tmp_path: Path, *, capture_events: bool = False) -> PowerContextPlugin: + settings = PowerContextSettings( + base_url="http://127.0.0.1:8000", + scope_id="configured-scope", + capture_events=capture_events, + capture_checkpoint_every=100, + ) + monkeypatch.setattr(plugin_module, "ensure_config", lambda _: settings) + monkeypatch.setattr(plugin_module, "PowerContextClient", RecordingClient) + return PowerContextPlugin(SimpleNamespace(workspace=tmp_path)) + + +def test_workspace_binding_key_is_stable_and_opaque(tmp_path: Path) -> None: + key = workspace_binding_key(tmp_path) + equivalent_key = workspace_binding_key(tmp_path / ".") + + assert key is not None + assert key == equivalent_key + assert key.integration == "bub" + assert key.kind == "workspace" + assert str(tmp_path) not in key.external_id + + +def test_recall_and_capture_use_only_the_server_resolved_scope(monkeypatch, tmp_path: Path) -> None: + RecordingClient.calls.clear() + next_scope_id = "scp_10000000000000000000000000" + RecordingClient.scope_ids = [RESOLVED_SCOPE_ID, next_scope_id] + plugin = _plugin(monkeypatch, tmp_path, capture_events=True) + state = plugin.load_state(message=None, session_id="session-1") + state["session_id"] = "session-1" + + request = LlmCallRequest( + run_id="run-1", + model="test-model", + messages=[{"role": "user", "content": "What did we decide?"}], + ) + result = asyncio.run(plugin.before_llm_call(request, state)) + + assert result is not None + assert {call.scope_id for name, call in RecordingClient.calls if name in {"capture", "prepare"}} == { + RESOLVED_SCOPE_ID + } + resolve_requests = [call for name, call in RecordingClient.calls if name == "resolve"] + assert len(resolve_requests) == 1 + assert resolve_requests[0].explicit_scope_id == "configured-scope" + assert resolve_requests[0].binding_keys == state[STATE_KEY]["binding_keys"] + assert state[STATE_KEY]["scope_id"] == RESOLVED_SCOPE_ID + + asyncio.run(plugin.before_llm_call(request, state)) + + next_state = plugin.load_state(message=None, session_id="session-2") + next_state["session_id"] = "session-2" + asyncio.run(plugin.before_llm_call(request, next_state)) + assert {call.scope_id for name, call in RecordingClient.calls[-2:] if name in {"capture", "prepare"}} == { + next_scope_id + } + + +def test_tool_resolves_and_caches_the_real_scope_before_search(monkeypatch, tmp_path: Path) -> None: + RecordingClient.calls.clear() + RecordingClient.scope_ids = [RESOLVED_SCOPE_ID] + plugin = _plugin(monkeypatch, tmp_path) + state = plugin.load_state(message=None, session_id="session-1") + context = SimpleNamespace(state=state) + + result = asyncio.run(tools_module.search_memory.run(query="database", context=context)) + + assert result == "(no matching PowerContext memory)" + resolve_request = RecordingClient.calls[0][1] + assert resolve_request.explicit_scope_id == "configured-scope" + assert resolve_request.binding_keys == state[STATE_KEY]["binding_keys"] + assert RecordingClient.calls[1][1].scope_id == RESOLVED_SCOPE_ID diff --git a/integrations/agent-plugin/powercontext/skills/project-context/SKILL.md b/integrations/agent-plugin/powercontext/skills/project-context/SKILL.md index 9d08cf914..709faf5e4 100644 --- a/integrations/agent-plugin/powercontext/skills/project-context/SKILL.md +++ b/integrations/agent-plugin/powercontext/skills/project-context/SKILL.md @@ -15,19 +15,17 @@ corresponding tool call returns successfully. ## Resolve Scope -Before the first PowerContext tool call, choose one `scope_id` for the current -task and reuse it for all Memory and Handoff calls in that task. - -Prefer a project-scoped identifier that is stable across compatible agents. For -a GitHub repository, use the normalized repository identity when it is known: - -```text -git:github.com/owner/repository -``` - -If the user or host provides an explicit PowerContext scope, use that value. -When scope is ambiguous, ask the user which project scope should hold the -Memory or Handoff. +Before the first data-plane call, use `resolve_scope_binding` to obtain one +Server-owned Scope. Supply an explicit Scope only when the host or user selected +an existing one; otherwise let the Server use its durable binding or default. +Reuse the returned `scope_id` for the task. Never derive or invent a Scope ID +from a repository, directory, branch, Agent, or prompt. + +When the user explicitly establishes an independent result boundary, inspect +the current Scope, call `create_scope` with the established Parent and +references, then bind the host identity when the integration supports durable +binding. Creating or switching a Scope is a host action, not an implicit result +of an ordinary Memory or Handoff call. ## Read Memory diff --git a/integrations/bub/README.md b/integrations/bub/README.md index 88cf5805d..5fd6f0376 100644 --- a/integrations/bub/README.md +++ b/integrations/bub/README.md @@ -31,7 +31,7 @@ validated by Pydantic before the plugin starts. | Variable | Default | Purpose | | --- | --- | --- | | `POWERCONTEXT_BUB_BASE_URL` | `http://127.0.0.1:8000` | PowerContext Server URL | -| `POWERCONTEXT_BUB_SCOPE_ID` | workspace-derived | Durable scope shared by Bub sessions | +| `POWERCONTEXT_BUB_SCOPE_ID` | unset | Explicit Scope resolved and validated by the Server before use | | `POWERCONTEXT_BUB_TIMEOUT` | `10` | Client timeout in seconds | | `POWERCONTEXT_BUB_MAX_BYTES` | `8000` | Maximum prepared-context size | | `POWERCONTEXT_BUB_CAPTURE_EVENTS` | `false` | Capture completed Bub events as Content Sources | @@ -40,6 +40,11 @@ validated by Pydantic before the plugin starts. | `POWERCONTEXT_BUB_CAPTURE_LOG` | unset | Optional JSONL evidence path; records metadata but not event content | | `POWERCONTEXT_BUB_TRUST_TRANSPORT_SECURITY` | `false` | Vouch for a plaintext non-loopback `BASE_URL` on an operator-controlled network (for example a private Compose bridge); otherwise such URLs are refused | +The plugin never derives a Scope ID from the current directory, Git metadata, or a workspace path. It asks the Server +to resolve the configured explicit Scope first, then an opaque stable binding key derived from Bub's workspace identity, +and finally the Server default. Only the real Scope returned by the Server is cached and used for recall, capture, and +tools. + Captured tool arguments redact values under credential-like keys. Known credential environment values are also removed from serialized event content. Keep the PowerContext scope and optional capture log protected because normal tool output can still contain sensitive project data. diff --git a/integrations/bub/src/powercontext_bub/plugin.py b/integrations/bub/src/powercontext_bub/plugin.py index a963c0571..a8affb4da 100644 --- a/integrations/bub/src/powercontext_bub/plugin.py +++ b/integrations/bub/src/powercontext_bub/plugin.py @@ -37,6 +37,8 @@ from powercontext.client.capture import render_capture_event from powercontext.http import CaptureContentSourceRequest, FlushMemoryRequest, PrepareContextRequest +from .scope import resolve_scope_id, workspace_binding_key + STATE_KEY = "_powercontext" CONTEXT_MARKER = "PowerContext host-supplied context" CLIENT_ERRORS = (InvalidResponseError, ServerResponseError, TransportError) @@ -104,16 +106,21 @@ class PowerContextPlugin: def __init__(self, framework: Any) -> None: self.settings = ensure_config(PowerContextSettings) self.base_url = str(self.settings.base_url).rstrip("/") - self.scope_id = self.settings.scope_id or _workspace_scope(Path(framework.workspace)) + self._framework = framework + self._scope_lock = asyncio.Lock() self._capture_lock = asyncio.Lock() @hookimpl def load_state(self, message: Any, session_id: str) -> TurnState: del message, session_id + workspace_key = workspace_binding_key(getattr(self._framework, "workspace", None)) + binding_keys = [workspace_key] if workspace_key is not None else [] return { STATE_KEY: { "base_url": self.base_url, - "scope_id": self.scope_id, + "scope_id": None, + "explicit_scope_id": self.settings.scope_id, + "binding_keys": binding_keys, "timeout": self.settings.timeout, "trust_transport_security": self.settings.trust_transport_security, "capture_sequence": 0, @@ -132,6 +139,13 @@ def system_prompt(self, prompt: str | list[dict[str, Any]], state: TurnState) -> @hookimpl async def before_llm_call(self, request: LlmCallRequest, state: TurnState) -> LlmCallRequest | None: query = _latest_user_text(request.messages) + if not query: + return None + + scope_id = await self._scope_id(state) + if scope_id is None: + return None + capture_state = state[STATE_KEY] if self.settings.capture_events and query and not capture_state["prompt_captured"]: capture_state["prompt_captured"] = True @@ -145,10 +159,7 @@ async def before_llm_call(self, request: LlmCallRequest, state: TurnState) -> Ll if any(_contains_context_marker(message) for message in request.messages): return None - if not query: - return None - - prepared_content = await self._prepare_context(query, state) + prepared_content = await self._prepare_context(query, scope_id, state) if not prepared_content: return None @@ -206,9 +217,41 @@ def _client(self) -> AbstractAsyncContextManager[PowerContextClient]: trust_transport_security=self.settings.trust_transport_security, ) - async def _prepare_context(self, query: str, state: TurnState) -> str | None: + async def _scope_id(self, state: TurnState) -> str | None: + scope_state = state[STATE_KEY] + explicit_scope_id = scope_state["explicit_scope_id"] + binding_keys = scope_state["binding_keys"] + cached_scope_id = scope_state.get("scope_id") + if cached_scope_id is not None: + return cached_scope_id + + async with self._scope_lock: + cached_scope_id = scope_state.get("scope_id") + if cached_scope_id is not None: + return cached_scope_id + try: + async with self._client() as client: + resolved_scope_id = await resolve_scope_id( + client, + explicit_scope_id=explicit_scope_id, + binding_keys=binding_keys, + ) + except CLIENT_ERRORS as exc: + scope_state["scope_error"] = type(exc).__name__ + self._write_capture_record( + event="scope", + status="failed", + error=type(exc).__name__, + ) + return None + + scope_state["scope_id"] = resolved_scope_id + scope_state.pop("scope_error", None) + return resolved_scope_id + + async def _prepare_context(self, query: str, scope_id: str, state: TurnState) -> str | None: request = PrepareContextRequest( - scope_id=self.scope_id, + scope_id=scope_id, query=query, max_bytes=self.settings.max_bytes, ) @@ -241,15 +284,19 @@ async def _capture_event( payload: dict[str, Any], state: TurnState, ) -> None: + scope_id = await self._scope_id(state) + if scope_id is None: + return + async with self._capture_lock: capture_state = state[STATE_KEY] capture_state["capture_sequence"] += 1 sequence = capture_state["capture_sequence"] session_id = str(state.get("session_id", "unknown")) - source_id = _source_id(self.scope_id, session_id, sequence, event, run_id) + source_id = _source_id(scope_id, session_id, sequence, event, run_id) content = render_capture_event(event, sequence, payload, self.settings.capture_max_bytes) request = CaptureContentSourceRequest( - scope_id=self.scope_id, + scope_id=scope_id, source_id=source_id, content=content, metadata={ @@ -292,9 +339,13 @@ async def _flush_captured_sources(self, state: TurnState, *, final: bool) -> Non if target_position <= capture_state["flushed_position"]: return + scope_id = await self._scope_id(state) + if scope_id is None: + return + try: async with self._client() as client: - response = await client.flush_memory(FlushMemoryRequest(scope_id=self.scope_id)) + response = await client.flush_memory(FlushMemoryRequest(scope_id=scope_id)) except CLIENT_ERRORS as exc: self._write_capture_record( event="checkpoint", @@ -354,11 +405,6 @@ def _contains_context_marker(message: dict[str, Any]) -> bool: return isinstance(content, str) and CONTEXT_MARKER in content -def _workspace_scope(workspace: Path) -> str: - digest = hashlib.sha256(str(workspace.resolve()).encode()).hexdigest()[:20] - return f"bub:{digest}" - - def _source_id(scope_id: str, session_id: str, sequence: int, event: str, run_id: str) -> str: identity = "\0".join((scope_id, session_id, str(sequence), event, run_id)) return f"bub-event:{hashlib.sha256(identity.encode()).hexdigest()}" diff --git a/integrations/bub/src/powercontext_bub/scope.py b/integrations/bub/src/powercontext_bub/scope.py new file mode 100644 index 000000000..cef8d2a7c --- /dev/null +++ b/integrations/bub/src/powercontext_bub/scope.py @@ -0,0 +1,53 @@ +# Copyright (c) 2026 OceanBase. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +"""Resolve Bub workspaces to server-owned PowerContext Scopes.""" + +from __future__ import annotations + +import hashlib +from pathlib import Path + +from powercontext.client import PowerContextClient +from powercontext.http import ResolveScopeBindingRequest, ScopeBindingKey + + +def workspace_binding_key(workspace: str | Path | None) -> ScopeBindingKey | None: + """Return an opaque binding key for the workspace identity exposed by Bub.""" + + if workspace is None: + return None + workspace_identity = str(Path(workspace).expanduser().resolve()) + return ScopeBindingKey( + integration="bub", + kind="workspace", + external_id=hashlib.sha256(workspace_identity.encode()).hexdigest(), + ) + + +async def resolve_scope_id( + client: PowerContextClient, + *, + explicit_scope_id: str | None, + binding_keys: list[ScopeBindingKey], +) -> str: + """Resolve an explicit Scope or workspace binding on the server.""" + + scope = await client.resolve_scope_binding( + ResolveScopeBindingRequest( + explicit_scope_id=explicit_scope_id, + binding_keys=binding_keys, + ) + ) + return scope.scope_id diff --git a/integrations/bub/src/powercontext_bub/tools.py b/integrations/bub/src/powercontext_bub/tools.py index 556c688a2..0eca546ff 100644 --- a/integrations/bub/src/powercontext_bub/tools.py +++ b/integrations/bub/src/powercontext_bub/tools.py @@ -24,14 +24,17 @@ from pydantic import BaseModel, Field from powercontext.client import PowerContextClient -from powercontext.http import PrepareContextRequest, RememberMemoryRequest, SearchMemoryRequest +from powercontext.http import PrepareContextRequest, RememberMemoryRequest, ScopeBindingKey, SearchMemoryRequest from .plugin import STATE_KEY, open_client +from .scope import resolve_scope_id class ToolSettings(TypedDict): base_url: str - scope_id: str + scope_id: str | None + explicit_scope_id: str | None + binding_keys: list[ScopeBindingKey] timeout: float trust_transport_security: bool @@ -52,8 +55,9 @@ async def search_memory(param: SearchInput, *, context: Any) -> str: """Search durable PowerContext memory.""" settings = _settings(context) - request = SearchMemoryRequest(scope_id=settings["scope_id"], query=param.query, limit=param.limit) async with _client(settings) as client: + scope_id = await _scope_id(settings, client) + request = SearchMemoryRequest(scope_id=scope_id, query=param.query, limit=param.limit) response = await client.search_memory(request) if not response.hits: return "(no matching PowerContext memory)" @@ -77,13 +81,14 @@ async def remember_memory(param: RememberInput, *, context: Any) -> str: """Save one explicit durable memory for later agent sessions.""" settings = _settings(context) - request = RememberMemoryRequest( - scope_id=settings["scope_id"], - kind=param.kind, - text=param.text, - reason=param.reason, - ) async with _client(settings) as client: + scope_id = await _scope_id(settings, client) + request = RememberMemoryRequest( + scope_id=scope_id, + kind=param.kind, + text=param.text, + reason=param.reason, + ) response = await client.remember_memory(request) if response.entry is None: return "(PowerContext accepted the memory without an entry receipt)" @@ -95,8 +100,9 @@ async def prepare_context(query: str, *, context: Any) -> str: """Prepare a bounded PowerContext payload for a new question.""" settings = _settings(context) - request = PrepareContextRequest(scope_id=settings["scope_id"], query=query) async with _client(settings) as client: + scope_id = await _scope_id(settings, client) + request = PrepareContextRequest(scope_id=scope_id, query=query) response = await client.prepare_context(request) return response.content or "(no relevant PowerContext context)" @@ -112,3 +118,16 @@ def _client(settings: ToolSettings) -> AbstractAsyncContextManager[PowerContextC timeout=settings["timeout"], trust_transport_security=settings["trust_transport_security"], ) + + +async def _scope_id(settings: ToolSettings, client: PowerContextClient) -> str: + cached_scope_id = settings["scope_id"] + if cached_scope_id is not None: + return cached_scope_id + resolved_scope_id = await resolve_scope_id( + client, + explicit_scope_id=settings["explicit_scope_id"], + binding_keys=settings["binding_keys"], + ) + settings["scope_id"] = resolved_scope_id + return resolved_scope_id diff --git a/integrations/claude-code/README.md b/integrations/claude-code/README.md index 3ceae61ae..38b593e5f 100644 --- a/integrations/claude-code/README.md +++ b/integrations/claude-code/README.md @@ -12,9 +12,10 @@ The plugin is a client of a running PowerContext Server: - MCP exposes explicit Memory and Handoff operations; - Server and transport failures never block normal Claude Code work. -The plugin uses the same Git-derived project scope as the Codex integration, so -both agents can recall and maintain the same project context. It does not use a -`Stop` hook and does not capture Claude's final response in v1. +The plugin resolves the current Scope through the Server. An explicit Scope has +priority, followed by durable session and workspace bindings, then the Server's +default Scope. It does not use a `Stop` hook and does not capture Claude's final +response in v1. Validate the marketplace and plugin from a repository checkout: diff --git a/integrations/claude-code/plugins/powercontext/README.md b/integrations/claude-code/plugins/powercontext/README.md index 9ee0f107a..62faea6bd 100644 --- a/integrations/claude-code/plugins/powercontext/README.md +++ b/integrations/claude-code/plugins/powercontext/README.md @@ -7,9 +7,9 @@ Automatic recall and prompt capture run on `UserPromptSubmit`. The plugin never reads the Claude Code transcript or captures Claude's final response in v1. Prompt Sources are evidence and are never marked as `task-outcome` by the hook. -Project scope is resolved from an explicit override, the normalized Git origin, -or a hash of the resolved local project directory, in that order. The Git rule -matches the Codex plugin so both agents can use the same project Memory. +Scope is resolved by the Server from an explicit override, the current session +or workspace binding, and finally the Server default. Bindings let multiple +agents share the same Scope without deriving identities locally. The plugin defaults to `http://127.0.0.1:8000`. Its Hook and MCP transport share `POWERCONTEXT_CLAUDE_AUTHORIZATION` when optional bearer authentication is diff --git a/integrations/claude-code/plugins/powercontext/hooks/user_prompt_submit.py b/integrations/claude-code/plugins/powercontext/hooks/user_prompt_submit.py index 9916ae434..394b2802a 100644 --- a/integrations/claude-code/plugins/powercontext/hooks/user_prompt_submit.py +++ b/integrations/claude-code/plugins/powercontext/hooks/user_prompt_submit.py @@ -43,7 +43,7 @@ def override(method: _MethodT, /) -> _MethodT: from claude_code_settings import ClaudeCodePluginSettings # noqa: E402 from hooks import prepared_context as _prepared_context # noqa: E402 from hooks.diagnostics import should_emit as _should_emit_diagnostic # noqa: E402 -from scripts.project_scope import resolve_scope_id # noqa: E402 +from scripts.workspace_scope import resolve_scope_id # noqa: E402 _MAX_CONTEXT_BYTES = _prepared_context.MAX_CONTEXT_BYTES _InvalidResponseError = _prepared_context.InvalidPreparedContextResponse @@ -162,8 +162,13 @@ def main(settings: ClaudeCodePluginSettings | None = None) -> int: _write_hook_output(diagnostic_events=diagnostic_events) return 0 - scope_id = resolve_scope_id(cwd, configured_scope_id=settings.scope_id) http_deadline = monotonic() + settings.http_budget_seconds + scope_id = resolve_scope_id( + cwd, + session_id=_payload_identifier(payload, "session_id"), + settings=settings, + deadline=http_deadline, + ) context = None with suppress(Exception): context = _recall_context( diff --git a/integrations/claude-code/plugins/powercontext/scripts/project_scope.py b/integrations/claude-code/plugins/powercontext/scripts/project_scope.py deleted file mode 100644 index 19b2d7aac..000000000 --- a/integrations/claude-code/plugins/powercontext/scripts/project_scope.py +++ /dev/null @@ -1,224 +0,0 @@ -#!/usr/bin/env python3 -# Copyright (c) 2026 OceanBase. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -"""Derive a stable PowerContext scope for one project directory.""" - -from __future__ import annotations - -import argparse -import hashlib -import json -import os -import re -import subprocess -import sys -from collections.abc import Sequence -from contextlib import suppress -from pathlib import Path -from shutil import which -from urllib.parse import urlsplit - -_PLUGIN_ROOT = Path(__file__).resolve().parents[1] -sys.path.insert(0, str(_PLUGIN_ROOT)) - -from claude_code_settings import ClaudeCodePluginSettings # noqa: E402 - -_MAX_SCOPE_LENGTH = 256 -_SCP_REMOTE = re.compile(r"^(?:[^@/\s]+@)?(?P[^:/\s]+):(?P.+)$") -_WORKSPACE_STATE_SCHEMA = "powercontext.codex-workspace.v1" -_WORKSPACE_STATE_DIRECTORY = "powercontext" -_WORKSPACE_STATE_FILE = "codex-workspace.json" - - -def resolve_scope_id(cwd: str, *, configured_scope_id: str | None = None) -> str: - """Return the configured, workspace-bound, or derived scope for one checkout.""" - - if configured_scope_id: - return _bounded_explicit(configured_scope_id) - bound_scope_id = read_bound_scope_id(cwd) - if bound_scope_id is not None: - return bound_scope_id - return derive_scope_id(cwd) - - -def derive_scope_id(cwd: str, *, configured_scope_id: str | None = None) -> str: - """Return an explicit, remote-derived, or path-derived project scope.""" - - if configured_scope_id: - return _bounded_explicit(configured_scope_id) - root_value = _git_value(cwd, "rev-parse", "--show-toplevel") - project_root = Path(root_value or cwd).resolve(strict=False) - remote = _git_value(str(project_root), "config", "--get", "remote.origin.url") - normalized_remote = normalize_git_remote(remote) if remote else None - if normalized_remote: - return _bounded("git", normalized_remote) - return f"local:{hashlib.sha256(os.fsencode(project_root)).hexdigest()}" - - -def bind_workstream_scope(cwd: str, scope_id: str, /) -> str: - """Persist one shared Workstream scope in Git-private state.""" - - normalized_scope_id = _bounded_explicit(scope_id.strip()) - if not normalized_scope_id: - raise ValueError("Workstream scope must be non-empty") # noqa: TRY003 - state_path = _workspace_state_path(cwd) - if state_path is None: - raise ValueError("Workstream scope binding requires a Git workspace") # noqa: TRY003 - _write_workspace_state(state_path, normalized_scope_id) - return normalized_scope_id - - -def read_bound_scope_id(cwd: str, /) -> str | None: - """Read the shared Codex/Claude Workstream binding from Git-private state.""" - - state_path = _workspace_state_path(cwd) - if state_path is None: - return None - try: - payload = json.loads(state_path.read_text(encoding="utf-8")) - except (OSError, UnicodeError, json.JSONDecodeError): - return None - if not isinstance(payload, dict) or payload.get("schema") != _WORKSPACE_STATE_SCHEMA: - return None - scope_id = payload.get("scope_id") - if ( - not isinstance(scope_id, str) - or not scope_id - or scope_id != scope_id.strip() - or len(scope_id) > _MAX_SCOPE_LENGTH - ): - return None - return scope_id - - -def clear_workstream_scope(cwd: str, /) -> bool: - """Remove only the Git-private shared Workstream binding file.""" - - state_path = _workspace_state_path(cwd) - if state_path is None: - return False - try: - state_path.unlink() - except FileNotFoundError: - return False - return True - - -def normalize_git_remote(remote: str) -> str | None: - """Normalize common network remotes without retaining credentials.""" - - value = remote.strip() - if not value: - return None - scp_match = _SCP_REMOTE.fullmatch(value) - if scp_match and "://" not in value: - host = scp_match.group("host").lower() - path = _normalize_path(scp_match.group("path")) - return f"{host}/{path}" if path else None - parsed = urlsplit(value) - if parsed.scheme not in {"http", "https", "ssh", "git"} or parsed.hostname is None: - return None - host = parsed.hostname.lower() - if parsed.port is not None: - host = f"{host}:{parsed.port}" - path = _normalize_path(parsed.path) - return f"{host}/{path}" if path else None - - -def _normalize_path(path: str) -> str: - normalized = "/".join(part for part in path.replace("\\", "/").split("/") if part) - if normalized.endswith(".git"): - normalized = normalized[:-4] - return normalized.rstrip("/") - - -def _bounded(prefix: str, value: str) -> str: - candidate = f"{prefix}:{value}" - if len(candidate) <= _MAX_SCOPE_LENGTH: - return candidate - return f"{prefix}:sha256:{hashlib.sha256(value.encode()).hexdigest()}" - - -def _bounded_explicit(value: str) -> str: - if len(value) <= _MAX_SCOPE_LENGTH: - return value - return f"sha256:{hashlib.sha256(value.encode()).hexdigest()}" - - -def _workspace_state_path(cwd: str, /) -> Path | None: - git_directory = _git_value(cwd, "rev-parse", "--absolute-git-dir") - if git_directory is None: - return None - return Path(git_directory) / _WORKSPACE_STATE_DIRECTORY / _WORKSPACE_STATE_FILE - - -def _write_workspace_state(state_path: Path, scope_id: str, /) -> None: - state_path.parent.mkdir(mode=0o700, parents=True, exist_ok=True) - temporary_path = state_path.with_name(f".{state_path.name}.{os.getpid()}.tmp") - encoded = ( - json.dumps({"schema": _WORKSPACE_STATE_SCHEMA, "scope_id": scope_id}, separators=(",", ":")) + "\n" - ).encode() - descriptor: int | None = None - try: - descriptor = os.open(temporary_path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600) - os.write(descriptor, encoded) - os.fsync(descriptor) - os.close(descriptor) - descriptor = None - os.replace(temporary_path, state_path) - finally: - if descriptor is not None: - os.close(descriptor) - with suppress(FileNotFoundError): - temporary_path.unlink() - - -def _git_value(cwd: str, *arguments: str) -> str | None: - executable = which("git") - if executable is None: - return None - try: - completed = subprocess.run( # noqa: S603 - git executable and arguments are integration-owned. - [executable, *arguments], - cwd=cwd, - check=True, - capture_output=True, - text=True, - timeout=2, - ) - except (OSError, subprocess.SubprocessError): - return None - return completed.stdout.strip() or None - - -def main(argv: Sequence[str] | None = None) -> int: - parser = argparse.ArgumentParser() - parser.add_argument("--cwd", default=os.getcwd()) - action = parser.add_mutually_exclusive_group() - action.add_argument("--bind-workstream", metavar="SCOPE_ID") - action.add_argument("--clear-workstream", action="store_true") - arguments = parser.parse_args(argv) - if arguments.bind_workstream is not None: - print(bind_workstream_scope(arguments.cwd, arguments.bind_workstream)) - return 0 - if arguments.clear_workstream: - clear_workstream_scope(arguments.cwd) - settings = ClaudeCodePluginSettings.from_environment() - print(resolve_scope_id(arguments.cwd, configured_scope_id=settings.scope_id)) - return 0 - - -if __name__ == "__main__": - raise SystemExit(main()) diff --git a/integrations/claude-code/plugins/powercontext/scripts/workspace_scope.py b/integrations/claude-code/plugins/powercontext/scripts/workspace_scope.py new file mode 100644 index 000000000..994e7e825 --- /dev/null +++ b/integrations/claude-code/plugins/powercontext/scripts/workspace_scope.py @@ -0,0 +1,267 @@ +#!/usr/bin/env python3 +# Copyright (c) 2026 OceanBase. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +"""Resolve Claude Code identities through the PowerContext Scope service.""" + +from __future__ import annotations + +import argparse +import json +import os +import subprocess +import sys +from collections.abc import Mapping, Sequence +from hashlib import sha256 +from pathlib import Path +from shutil import which +from time import monotonic +from typing import Any, Protocol +from urllib.error import HTTPError +from urllib.request import HTTPRedirectHandler, Request, build_opener + +from typing_extensions import override + +_PLUGIN_ROOT = Path(__file__).resolve().parents[1] +sys.path.insert(0, str(_PLUGIN_ROOT)) + +from claude_code_settings import ClaudeCodePluginSettings # noqa: E402 + +_MAX_RESPONSE_BYTES = 1_048_576 +_READ_CHUNK_BYTES = 65_536 +_REQUEST_HEADERS = { + "Accept": "application/json", + "Content-Type": "application/json", + "User-Agent": "powercontext-claude-code-plugin/0.1.0", +} + + +class ScopeBindingError(RuntimeError): + """Raised when Claude Code cannot establish one current Scope.""" + + +class ScopeBindingSettings(Protocol): + """Settings required by the dependency-free binding client.""" + + server_url: str + authorization: str | None + scope_id: str | None + request_timeout_seconds: float + + +class _Response(Protocol): + status: int + + def __enter__(self) -> _Response: ... + + def __exit__(self, *args: object) -> object: ... + + def read(self, amount: int = -1) -> bytes: ... + + +class _RejectRedirects(HTTPRedirectHandler): + @override + def redirect_request( + self, + req: Request, + fp: object, + code: int, + msg: str, + headers: object, + newurl: str, + ) -> Request | None: + return None + + +_URL_OPENER = build_opener(_RejectRedirects) + + +def resolve_scope_id( + cwd: str, + *, + session_id: str | None, + settings: ScopeBindingSettings, + deadline: float, +) -> str: + """Resolve explicit, session, workspace, then server-default binding.""" + + response = _request_json( + "/v1/scope-bindings/resolve", + { + "explicit_scope_id": settings.scope_id, + "binding_keys": binding_keys(cwd, session_id=session_id), + }, + settings=settings, + deadline=deadline, + ) + scope_id = response.get("scope_id") + if not isinstance(scope_id, str) or not scope_id.strip() or scope_id != scope_id.strip(): + raise ScopeBindingError + return scope_id + + +def bind_scope( + cwd: str, + scope_id: str, + /, + *, + settings: ScopeBindingSettings, + deadline: float, +) -> str: + """Persist the workspace identity to one server-owned Scope.""" + + response = _request_json( + "/v1/scope-bindings", + {"key": workspace_binding_key(cwd), "scope_id": scope_id}, + settings=settings, + deadline=deadline, + method="PUT", + ) + resolved = response.get("scope_id") + if not isinstance(resolved, str) or resolved != scope_id: + raise ScopeBindingError + return resolved + + +def clear_scope_binding( + cwd: str, + /, + *, + settings: ScopeBindingSettings, + deadline: float, +) -> bool: + """Remove the durable workspace binding from the Scope service.""" + + response = _request_json( + "/v1/scope-bindings/clear", + {"key": workspace_binding_key(cwd)}, + settings=settings, + deadline=deadline, + ) + cleared = response.get("cleared") + if not isinstance(cleared, bool): + raise ScopeBindingError + return cleared + + +def binding_keys(cwd: str, *, session_id: str | None) -> list[dict[str, str]]: + keys: list[dict[str, str]] = [] + if session_id is not None: + keys.append(session_binding_key(session_id)) + keys.append(workspace_binding_key(cwd)) + return keys + + +def session_binding_key(session_id: str) -> dict[str, str]: + value = session_id.strip() + if not value or len(value) > 256: + raise ScopeBindingError + return {"integration": "claude-code", "kind": "session", "external_id": value} + + +def workspace_binding_key(cwd: str) -> dict[str, str]: + root_value = _git_value(cwd, "rev-parse", "--show-toplevel") + root = Path(root_value or cwd).resolve(strict=False) + return { + "integration": "claude-code", + "kind": "workspace", + "external_id": sha256(os.fsencode(root)).hexdigest(), + } + + +def _request_json( + path: str, + payload: Mapping[str, object], + *, + settings: ScopeBindingSettings, + deadline: float, + method: str = "POST", +) -> Mapping[str, object]: + remaining = deadline - monotonic() + if remaining <= 0: + raise ScopeBindingError + headers = dict(_REQUEST_HEADERS) + if settings.authorization is not None: + headers["Authorization"] = settings.authorization + request = Request( # noqa: S310 - settings validates the configured transport. + f"{settings.server_url}{path}", + data=json.dumps(payload, separators=(",", ":")).encode(), + headers=headers, + method=method, + ) + try: + with _URL_OPENER.open(request, timeout=min(settings.request_timeout_seconds, remaining)) as response: + if response.status < 200 or response.status >= 300: + raise ScopeBindingError + raw = _read_bounded(response) + except (HTTPError, OSError, TimeoutError) as error: + raise ScopeBindingError from error + try: + value: Any = json.loads(raw) + except (UnicodeDecodeError, json.JSONDecodeError) as error: + raise ScopeBindingError from error + if not isinstance(value, dict): + raise ScopeBindingError + return value + + +def _read_bounded(response: _Response) -> bytes: + chunks: list[bytes] = [] + size = 0 + while chunk := response.read(_READ_CHUNK_BYTES): + size += len(chunk) + if size > _MAX_RESPONSE_BYTES: + raise ScopeBindingError + chunks.append(chunk) + return b"".join(chunks) + + +def _git_value(cwd: str, *arguments: str) -> str | None: + executable = which("git") + if executable is None: + return None + try: + completed = subprocess.run( # noqa: S603 - git executable and arguments are integration-owned. + [executable, *arguments], + cwd=cwd, + check=True, + capture_output=True, + text=True, + timeout=2, + ) + except (OSError, subprocess.SubprocessError): + return None + return completed.stdout.strip() or None + + +def main(argv: Sequence[str] | None = None) -> int: + parser = argparse.ArgumentParser() + parser.add_argument("--cwd", default=os.getcwd()) + action = parser.add_mutually_exclusive_group() + action.add_argument("--bind-scope", metavar="SCOPE_ID") + action.add_argument("--clear-scope", action="store_true") + arguments = parser.parse_args(argv) + settings = ClaudeCodePluginSettings.from_environment() + deadline = monotonic() + settings.http_budget_seconds + if arguments.bind_scope is not None: + print(bind_scope(arguments.cwd, arguments.bind_scope, settings=settings, deadline=deadline)) + return 0 + if arguments.clear_scope: + clear_scope_binding(arguments.cwd, settings=settings, deadline=deadline) + print(resolve_scope_id(arguments.cwd, session_id=None, settings=settings, deadline=deadline)) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/integrations/claude-code/plugins/powercontext/skills/project-context/SKILL.md b/integrations/claude-code/plugins/powercontext/skills/project-context/SKILL.md index 7ce8a6341..5ff592f5b 100644 --- a/integrations/claude-code/plugins/powercontext/skills/project-context/SKILL.md +++ b/integrations/claude-code/plugins/powercontext/skills/project-context/SKILL.md @@ -18,36 +18,29 @@ to duplicate the current prompt. Ordinary prompt Sources are not task outcomes. Before the first memory tool call, run: ```bash -python3 "${CLAUDE_PLUGIN_ROOT}/scripts/project_scope.py" --cwd "$PWD" +python3 "${CLAUDE_PLUGIN_ROOT}/scripts/workspace_scope.py" --cwd "$PWD" ``` Reuse that exact `scope_id` for the task. -The resolver first honors an explicit plugin scope, then the same Git-private -Workstream binding used by Codex, and finally the normalized remote or project -path. When the user explicitly asks to bind the current checkout to a known -Handoff Report Workstream, run: +The Server resolves an explicit Scope first, then durable session and workspace +bindings, and finally its default Scope. When the user explicitly asks to bind +the current checkout to a known Scope, run: ```bash -python3 "${CLAUDE_PLUGIN_ROOT}/scripts/project_scope.py" \ - --cwd "$PWD" --bind-workstream "WORKSTREAM_SCOPE_ID" +python3 "${CLAUDE_PLUGIN_ROOT}/scripts/workspace_scope.py" \ + --cwd "$PWD" --bind-scope "SCOPE_ID" ``` -Then run the normal resolver command again and verify the same scope. The -binding is stored below the checkout's Git directory and is not committed. -Never infer one Workstream when multiple candidates remain consequential. - -Before a durable one-turn Handoff or a `latest` Continue without an exact -Workstream, call `select_handoff_workstream` when that MCP tool is available. -Clients with MCP elicitation can present a native picker; otherwise the tool -returns structured choices. On `selected`, bind the returned `scope_id` with -`--bind-workstream`, run the normal resolver again, and require the resolved -scope to match before any Handoff write. On `needs_selection`, present the -returned choices and call the tool again with the user's exact `project_id` and -`work_id`; never choose a fallback candidate silently. On `cancelled` or -`declined`, stop the Handoff flow. If the tool is unavailable or returns -`empty`, preserve the existing resolver behavior. The picker is read-only and -selecting work does not itself prepare or commit a Handoff. +Then run the normal resolver command again and verify the same Scope. The +binding is stored by PowerContext; the plugin never derives a Scope ID from a +Git remote or directory. Never infer a Scope when multiple candidates remain +consequential. + +Before a durable one-turn Handoff or a `latest` Continue, resolve the intended +Scope explicitly. If the current binding is not the intended boundary, ask the +user or host for the exact Scope ID, bind it, and verify the resolver result +before any Handoff write. Never infer a Scope from a report view. ## Read @@ -68,8 +61,7 @@ Handoff, a design discussion, or a preview request does not authorize a write. When the one-turn flow applies: -1. Select the Workstream when the picker is available, then resolve and verify - the exact scope using the commands above. +1. Resolve and verify the exact Scope using the commands above. 2. Inspect the current conversation and repository before writing. Ground the objective, branch and worktree state, changed files, checks, blockers, omissions, and next executable action without reading or including secrets. diff --git a/integrations/codex/plugins/powercontext/README.md b/integrations/codex/plugins/powercontext/README.md index 5d3822858..9bce5d501 100644 --- a/integrations/codex/plugins/powercontext/README.md +++ b/integrations/codex/plugins/powercontext/README.md @@ -51,13 +51,15 @@ The hook runtime is declared by the plugin's `pyproject.toml` and launched with `uv`; this keeps its `pydantic-settings` dependency isolated and reproducible. The hook uses a small synchronous standard-library HTTP adapter because Codex executes it as a short-lived process. It does not expose that adapter as an SDK. -The `project-context` Skill reuses the installed hook virtual environment when -deriving project scope, so a read-only Codex turn does not need to mutate the -`uv` cache. - -Set `POWERCONTEXT_CODEX_SCOPE_ID` to override automatic project scoping. By -default, the scope comes from the normalized Git remote, or from the project -path when no supported remote is available. +`SessionStart` fixes a durable binding from an explicit plugin Scope, an +existing Session binding, a workspace binding preference, or the Server's +default Scope. `UserPromptSubmit` uses that binding for recall and capture. +`PreToolUse` injects the same binding into PowerContext data-plane tools, so an +Agent-supplied `scope_id` cannot redirect a write. Repository and directory +identities are binding lookup inputs only; they never generate a Scope ID. + +Set `POWERCONTEXT_CODEX_SCOPE_ID` only when the host must explicitly bind every +request to one known Scope. `.mcp.json` is the single Server endpoint configuration consumed by Codex and the hook: the hook validates its PowerContext MCP URL and derives the HTTP API base by removing the final `/mcp` path segment. Change that file before diff --git a/integrations/codex/plugins/powercontext/hooks/bind_tools.py b/integrations/codex/plugins/powercontext/hooks/bind_tools.py new file mode 100644 index 000000000..5ea2ef434 --- /dev/null +++ b/integrations/codex/plugins/powercontext/hooks/bind_tools.py @@ -0,0 +1,148 @@ +#!/usr/bin/env python3 +# Copyright (c) 2026 OceanBase. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +"""Bind PowerContext MCP data-plane calls to the current Codex Session.""" + +from __future__ import annotations + +import json +import sys +from pathlib import Path +from time import monotonic +from typing import Any, cast + +_PLUGIN_ROOT = Path(__file__).resolve().parents[1] +sys.path.insert(0, str(_PLUGIN_ROOT)) + +from scripts.scope_binding import ( # noqa: E402 + ScopeBindingError, + binding_keys, + resolve_scope_id, + session_binding_key, +) +from settings import CodexPluginSettings # noqa: E402 + +_PREFIX = "mcp__powercontext__" +_CONTROL_OPERATIONS = frozenset({"set_scope_binding", "clear_scope_binding"}) +_CURRENT_SCOPE_OPERATIONS = frozenset({"resolve_scope_binding"}) +_HOST_OPERATIONS = frozenset({"create_scope", "get_scope", "list_scopes", "publish_artifact"}) +_SCOPE_BOUND_OPERATIONS = frozenset({ + "acknowledge_handoff", + "activate_handoff", + "approve_artifact_candidate", + "capture_content_source", + "commit_handoff", + "continue_handoff", + "create_work_contract", + "finalize_handoff", + "get_artifact_candidate", + "get_handoff_report", + "get_memory_entry", + "handoff_current_work", + "list_artifact_candidates", + "list_memory_entries", + "record_task_outcome", + "reject_artifact_candidate", + "remember_memory", + "retire_memory_entry", + "revise_artifact_candidate", + "revise_memory_entry", + "search_memory", +}) + + +def main(settings: CodexPluginSettings | None = None) -> int: + try: + payload = cast(dict[str, Any], json.load(sys.stdin)) + tool_name = payload.get("tool_name") + tool_input = payload.get("tool_input") + session_id = payload.get("session_id") + cwd = payload.get("cwd") + if ( + not isinstance(tool_name, str) + or not tool_name.startswith(_PREFIX) + or not isinstance(tool_input, dict) + or not isinstance(session_id, str) + or not isinstance(cwd, str) + ): + return 0 + operation = tool_name.removeprefix(_PREFIX) + if operation in _CONTROL_OPERATIONS: + updated = dict(tool_input) + updated["key"] = session_binding_key(session_id) + _allow(updated) + return 0 + if operation in _CURRENT_SCOPE_OPERATIONS: + settings = CodexPluginSettings() if settings is None else settings + _allow({ + "explicit_scope_id": settings.scope_id, + "binding_keys": binding_keys(cwd, session_id=session_id), + }) + return 0 + if operation in _HOST_OPERATIONS: + _allow(dict(tool_input)) + return 0 + if operation not in _SCOPE_BOUND_OPERATIONS: + return 0 + settings = CodexPluginSettings() if settings is None else settings + scope_id = resolve_scope_id( + cwd, + session_id=session_id, + settings=settings, + deadline=monotonic() + settings.http_budget_seconds, + ) + updated = dict(tool_input) + if operation == "get_handoff_report": + updated["selection"] = {"mode": "exact", "scope_ids": [scope_id]} + else: + updated["scope_id"] = scope_id + _allow(updated) + except (ScopeBindingError, ValueError, OSError, json.JSONDecodeError): + _deny() + return 0 + + +def _allow(updated_input: dict[str, object]) -> None: + json.dump( + { + "hookSpecificOutput": { + "hookEventName": "PreToolUse", + "permissionDecision": "allow", + "updatedInput": updated_input, + } + }, + sys.stdout, + separators=(",", ":"), + ) + sys.stdout.write("\n") + + +def _deny() -> None: + json.dump( + { + "hookSpecificOutput": { + "hookEventName": "PreToolUse", + "permissionDecision": "deny", + "permissionDecisionReason": "PowerContext could not resolve the current Scope binding.", + } + }, + sys.stdout, + separators=(",", ":"), + ) + sys.stdout.write("\n") + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/integrations/codex/plugins/powercontext/hooks/hooks.json b/integrations/codex/plugins/powercontext/hooks/hooks.json index fba24ad40..bd55336dc 100644 --- a/integrations/codex/plugins/powercontext/hooks/hooks.json +++ b/integrations/codex/plugins/powercontext/hooks/hooks.json @@ -1,6 +1,30 @@ { "description": "Recall relevant memory and capture the current Codex prompt as a Source.", "hooks": { + "SessionStart": [ + { + "hooks": [ + { + "type": "command", + "command": "uv run --frozen --quiet --project \"${PLUGIN_ROOT}\" python \"${PLUGIN_ROOT}/hooks/session_binding.py\"", + "timeout": 10, + "statusMessage": "Binding PowerContext" + } + ] + } + ], + "PreToolUse": [ + { + "matcher": "mcp__powercontext__.*", + "hooks": [ + { + "type": "command", + "command": "uv run --frozen --quiet --project \"${PLUGIN_ROOT}\" python \"${PLUGIN_ROOT}/hooks/bind_tools.py\"", + "timeout": 10 + } + ] + } + ], "UserPromptSubmit": [ { "hooks": [ diff --git a/integrations/codex/plugins/powercontext/hooks/recall.py b/integrations/codex/plugins/powercontext/hooks/recall.py index 8d4748ff9..f3f27148b 100644 --- a/integrations/codex/plugins/powercontext/hooks/recall.py +++ b/integrations/codex/plugins/powercontext/hooks/recall.py @@ -37,7 +37,7 @@ from hooks import prepared_context as _prepared_context # noqa: E402 from hooks.diagnostics import should_emit as _should_emit_diagnostic # noqa: E402 -from scripts.project_scope import resolve_scope_id # noqa: E402 +from scripts.scope_binding import resolve_scope_id # noqa: E402 from settings import CodexPluginSettings # noqa: E402 _MAX_CONTEXT_BYTES = _prepared_context.MAX_CONTEXT_BYTES @@ -157,7 +157,13 @@ def main(settings: CodexPluginSettings | None = None) -> int: _emit_context_event("skipped", diagnostic_events=diagnostic_events) _write_hook_output(diagnostic_events=diagnostic_events) return 0 - scope_id = resolve_scope_id(cwd, configured_scope_id=settings.scope_id) + session_id = _payload_identifier(payload, "session_id", "conversation_id", "thread_id") + scope_id = resolve_scope_id( + cwd, + session_id=session_id, + settings=settings, + deadline=http_deadline, + ) context = _recall_context( prompt, scope_id, diff --git a/integrations/codex/plugins/powercontext/hooks/session_binding.py b/integrations/codex/plugins/powercontext/hooks/session_binding.py new file mode 100644 index 000000000..a8174fd79 --- /dev/null +++ b/integrations/codex/plugins/powercontext/hooks/session_binding.py @@ -0,0 +1,54 @@ +#!/usr/bin/env python3 +# Copyright (c) 2026 OceanBase. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +"""Fix one Codex Session binding without blocking Session startup.""" + +from __future__ import annotations + +import json +import sys +from pathlib import Path +from time import monotonic +from typing import Any, cast + +_PLUGIN_ROOT = Path(__file__).resolve().parents[1] +sys.path.insert(0, str(_PLUGIN_ROOT)) + +from scripts.scope_binding import ScopeBindingError, resolve_scope_id # noqa: E402 +from settings import CodexPluginSettings # noqa: E402 + + +def main(settings: CodexPluginSettings | None = None) -> int: + try: + payload = cast(dict[str, Any], json.load(sys.stdin)) + session_id = payload.get("session_id") + cwd = payload.get("cwd") + if not isinstance(session_id, str) or not isinstance(cwd, str): + return 0 + settings = CodexPluginSettings() if settings is None else settings + resolve_scope_id( + cwd, + session_id=session_id, + settings=settings, + deadline=monotonic() + settings.http_budget_seconds, + persist_session=True, + ) + except (ScopeBindingError, ValueError, OSError, json.JSONDecodeError): + return 0 + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/integrations/codex/plugins/powercontext/scripts/project_scope.py b/integrations/codex/plugins/powercontext/scripts/project_scope.py deleted file mode 100644 index 0de5e9e44..000000000 --- a/integrations/codex/plugins/powercontext/scripts/project_scope.py +++ /dev/null @@ -1,224 +0,0 @@ -#!/usr/bin/env python3 -# Copyright (c) 2026 OceanBase. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -"""Derive a stable PowerContext scope for one project directory.""" - -from __future__ import annotations - -import argparse -import hashlib -import json -import os -import re -import subprocess -import sys -from collections.abc import Sequence -from contextlib import suppress -from pathlib import Path -from shutil import which -from urllib.parse import urlsplit - -_PLUGIN_ROOT = Path(__file__).resolve().parents[1] -sys.path.insert(0, str(_PLUGIN_ROOT)) - -from settings import CodexPluginSettings # noqa: E402 - -_MAX_SCOPE_LENGTH = 256 -_SCP_REMOTE = re.compile(r"^(?:[^@/\s]+@)?(?P[^:/\s]+):(?P.+)$") -_WORKSPACE_STATE_SCHEMA = "powercontext.codex-workspace.v1" -_WORKSPACE_STATE_DIRECTORY = "powercontext" -_WORKSPACE_STATE_FILE = "codex-workspace.json" - - -def resolve_scope_id(cwd: str, *, configured_scope_id: str | None = None) -> str: - """Return the configured, workspace-bound, or derived scope for one checkout.""" - - if configured_scope_id: - return _bounded_explicit(configured_scope_id) - bound_scope_id = read_bound_scope_id(cwd) - if bound_scope_id is not None: - return bound_scope_id - return derive_scope_id(cwd) - - -def derive_scope_id(cwd: str, *, configured_scope_id: str | None = None) -> str: - """Return an explicit, remote-derived, or path-derived project scope.""" - - if configured_scope_id: - return _bounded_explicit(configured_scope_id) - root_value = _git_value(cwd, "rev-parse", "--show-toplevel") - project_root = Path(root_value or cwd).resolve(strict=False) - remote = _git_value(str(project_root), "config", "--get", "remote.origin.url") - normalized_remote = normalize_git_remote(remote) if remote else None - if normalized_remote: - return _bounded("git", normalized_remote) - return f"local:{hashlib.sha256(os.fsencode(project_root)).hexdigest()}" - - -def bind_workstream_scope(cwd: str, scope_id: str, /) -> str: - """Persist one Workstream scope in Git-private state for later Codex sessions.""" - - normalized_scope_id = _bounded_explicit(scope_id.strip()) - if not normalized_scope_id: - raise ValueError("Workstream scope must be non-empty") # noqa: TRY003 - state_path = _workspace_state_path(cwd) - if state_path is None: - raise ValueError("Workstream scope binding requires a Git workspace") # noqa: TRY003 - _write_workspace_state(state_path, normalized_scope_id) - return normalized_scope_id - - -def read_bound_scope_id(cwd: str, /) -> str | None: - """Read a valid Workstream scope binding without trusting arbitrary state fields.""" - - state_path = _workspace_state_path(cwd) - if state_path is None: - return None - try: - payload = json.loads(state_path.read_text(encoding="utf-8")) - except (OSError, UnicodeError, json.JSONDecodeError): - return None - if not isinstance(payload, dict) or payload.get("schema") != _WORKSPACE_STATE_SCHEMA: - return None - scope_id = payload.get("scope_id") - if ( - not isinstance(scope_id, str) - or not scope_id - or scope_id != scope_id.strip() - or len(scope_id) > _MAX_SCOPE_LENGTH - ): - return None - return scope_id - - -def clear_workstream_scope(cwd: str, /) -> bool: - """Remove only the Git-private Codex Workstream binding file.""" - - state_path = _workspace_state_path(cwd) - if state_path is None: - return False - try: - state_path.unlink() - except FileNotFoundError: - return False - return True - - -def normalize_git_remote(remote: str) -> str | None: - """Normalize common network remotes without retaining credentials.""" - - value = remote.strip() - if not value: - return None - scp_match = _SCP_REMOTE.fullmatch(value) - if scp_match and "://" not in value: - host = scp_match.group("host").lower() - path = _normalize_path(scp_match.group("path")) - return f"{host}/{path}" if path else None - parsed = urlsplit(value) - if parsed.scheme not in {"http", "https", "ssh", "git"} or parsed.hostname is None: - return None - host = parsed.hostname.lower() - if parsed.port is not None: - host = f"{host}:{parsed.port}" - path = _normalize_path(parsed.path) - return f"{host}/{path}" if path else None - - -def _normalize_path(path: str) -> str: - normalized = "/".join(part for part in path.replace("\\", "/").split("/") if part) - if normalized.endswith(".git"): - normalized = normalized[:-4] - return normalized.rstrip("/") - - -def _bounded(prefix: str, value: str) -> str: - candidate = f"{prefix}:{value}" - if len(candidate) <= _MAX_SCOPE_LENGTH: - return candidate - return f"{prefix}:sha256:{hashlib.sha256(value.encode()).hexdigest()}" - - -def _bounded_explicit(value: str) -> str: - if len(value) <= _MAX_SCOPE_LENGTH: - return value - return f"sha256:{hashlib.sha256(value.encode()).hexdigest()}" - - -def _workspace_state_path(cwd: str, /) -> Path | None: - git_directory = _git_value(cwd, "rev-parse", "--absolute-git-dir") - if git_directory is None: - return None - return Path(git_directory) / _WORKSPACE_STATE_DIRECTORY / _WORKSPACE_STATE_FILE - - -def _write_workspace_state(state_path: Path, scope_id: str, /) -> None: - state_path.parent.mkdir(mode=0o700, parents=True, exist_ok=True) - temporary_path = state_path.with_name(f".{state_path.name}.{os.getpid()}.tmp") - encoded = ( - json.dumps({"schema": _WORKSPACE_STATE_SCHEMA, "scope_id": scope_id}, separators=(",", ":")) + "\n" - ).encode() - descriptor: int | None = None - try: - descriptor = os.open(temporary_path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600) - os.write(descriptor, encoded) - os.fsync(descriptor) - os.close(descriptor) - descriptor = None - os.replace(temporary_path, state_path) - finally: - if descriptor is not None: - os.close(descriptor) - with suppress(FileNotFoundError): - temporary_path.unlink() - - -def _git_value(cwd: str, *arguments: str) -> str | None: - executable = which("git") - if executable is None: - return None - try: - completed = subprocess.run( # noqa: S603 - git executable and arguments are integration-owned. - [executable, *arguments], - cwd=cwd, - check=True, - capture_output=True, - text=True, - timeout=2, - ) - except (OSError, subprocess.SubprocessError): - return None - return completed.stdout.strip() or None - - -def main(argv: Sequence[str] | None = None) -> int: - parser = argparse.ArgumentParser() - parser.add_argument("--cwd", default=os.getcwd()) - action = parser.add_mutually_exclusive_group() - action.add_argument("--bind-workstream", metavar="SCOPE_ID") - action.add_argument("--clear-workstream", action="store_true") - arguments = parser.parse_args(argv) - if arguments.bind_workstream is not None: - print(bind_workstream_scope(arguments.cwd, arguments.bind_workstream)) - return 0 - if arguments.clear_workstream: - clear_workstream_scope(arguments.cwd) - settings = CodexPluginSettings() - print(resolve_scope_id(arguments.cwd, configured_scope_id=settings.scope_id)) - return 0 - - -if __name__ == "__main__": - raise SystemExit(main()) diff --git a/integrations/codex/plugins/powercontext/scripts/scope_binding.py b/integrations/codex/plugins/powercontext/scripts/scope_binding.py new file mode 100644 index 000000000..d7d5bf468 --- /dev/null +++ b/integrations/codex/plugins/powercontext/scripts/scope_binding.py @@ -0,0 +1,205 @@ +#!/usr/bin/env python3 +# Copyright (c) 2026 OceanBase. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +"""Resolve Codex external identities through the PowerContext Scope service.""" + +from __future__ import annotations + +import json +import os +import subprocess +import sys +from collections.abc import Mapping +from hashlib import sha256 +from pathlib import Path +from shutil import which +from time import monotonic +from typing import Any, Protocol +from urllib.error import HTTPError +from urllib.request import HTTPRedirectHandler, Request, build_opener + +from typing_extensions import override + +_PLUGIN_ROOT = Path(__file__).resolve().parents[1] +sys.path.insert(0, str(_PLUGIN_ROOT)) + +from settings import CodexPluginSettings # noqa: E402 + +_MAX_RESPONSE_BYTES = 1_048_576 +_READ_CHUNK_BYTES = 65_536 +_REQUEST_HEADERS = { + "Accept": "application/json", + "Content-Type": "application/json", + "User-Agent": "powercontext-codex-plugin/0.3.0", +} + + +class ScopeBindingError(RuntimeError): + """Raised when the integration cannot establish one current Scope.""" + + +class _Response(Protocol): + fp: object + status: int + + def __enter__(self) -> _Response: ... + + def __exit__(self, *args: object) -> object: ... + + def read(self, amount: int = -1) -> bytes: ... + + +class _RejectRedirects(HTTPRedirectHandler): + @override + def redirect_request( + self, + req: Request, + fp: object, + code: int, + msg: str, + headers: object, + newurl: str, + ) -> Request | None: + return None + + +_URL_OPENER = build_opener(_RejectRedirects) + + +def resolve_scope_id( + cwd: str, + *, + session_id: str | None, + settings: CodexPluginSettings, + deadline: float, + persist_session: bool = False, +) -> str: + """Resolve explicit, session, workspace, then default binding in that order.""" + + keys = binding_keys(cwd, session_id=session_id) + response = _post_json( + "/v1/scope-bindings/resolve", + { + "explicit_scope_id": settings.scope_id, + "binding_keys": keys, + }, + settings=settings, + deadline=deadline, + ) + scope_id = response.get("scope_id") + if not isinstance(scope_id, str) or not scope_id.strip() or scope_id != scope_id.strip(): + raise ScopeBindingError + if persist_session and session_id is not None and settings.scope_id is None: + _post_json( + "/v1/scope-bindings", + { + "key": session_binding_key(session_id), + "scope_id": scope_id, + }, + settings=settings, + deadline=deadline, + method="PUT", + ) + return scope_id + + +def binding_keys(cwd: str, *, session_id: str | None) -> list[dict[str, str]]: + keys: list[dict[str, str]] = [] + if session_id is not None: + keys.append(session_binding_key(session_id)) + keys.append(workspace_binding_key(cwd)) + return keys + + +def session_binding_key(session_id: str) -> dict[str, str]: + value = session_id.strip() + if not value or len(value) > 256: + raise ScopeBindingError + return {"integration": "codex", "kind": "session", "external_id": value} + + +def workspace_binding_key(cwd: str) -> dict[str, str]: + root_value = _git_value(cwd, "rev-parse", "--show-toplevel") + root = Path(root_value or cwd).resolve(strict=False) + external_id = sha256(os.fsencode(root)).hexdigest() + return {"integration": "codex", "kind": "workspace", "external_id": external_id} + + +def _post_json( + path: str, + payload: Mapping[str, object], + *, + settings: CodexPluginSettings, + deadline: float, + method: str = "POST", +) -> Mapping[str, object]: + remaining = deadline - monotonic() + if remaining <= 0: + raise ScopeBindingError + headers = dict(_REQUEST_HEADERS) + if settings.authorization is not None: + headers["Authorization"] = settings.authorization.get_secret_value() + request = Request( # noqa: S310 - settings validates the configured transport. + f"{settings.server_url}{path}", + data=json.dumps(payload, separators=(",", ":")).encode(), + headers=headers, + method=method, + ) + try: + with _URL_OPENER.open( + request, + timeout=min(settings.request_timeout_seconds, remaining), + ) as response: + if response.status < 200 or response.status >= 300: + raise ScopeBindingError + raw = _read_bounded(response) + except (HTTPError, OSError, TimeoutError) as error: + raise ScopeBindingError from error + try: + value: Any = json.loads(raw) + except (UnicodeDecodeError, json.JSONDecodeError) as error: + raise ScopeBindingError from error + if not isinstance(value, dict): + raise ScopeBindingError + return value + + +def _read_bounded(response: _Response) -> bytes: + chunks: list[bytes] = [] + size = 0 + while chunk := response.read(_READ_CHUNK_BYTES): + size += len(chunk) + if size > _MAX_RESPONSE_BYTES: + raise ScopeBindingError + chunks.append(chunk) + return b"".join(chunks) + + +def _git_value(cwd: str, *arguments: str) -> str | None: + executable = which("git") + if executable is None: + return None + try: + completed = subprocess.run( # noqa: S603 - executable and arguments are integration-owned. + [executable, *arguments], + cwd=cwd, + check=True, + capture_output=True, + text=True, + timeout=2, + ) + except (OSError, subprocess.SubprocessError): + return None + return completed.stdout.strip() or None diff --git a/integrations/codex/plugins/powercontext/skills/project-context/SKILL.md b/integrations/codex/plugins/powercontext/skills/project-context/SKILL.md index 0ba151417..194b0f250 100644 --- a/integrations/codex/plugins/powercontext/skills/project-context/SKILL.md +++ b/integrations/codex/plugins/powercontext/skills/project-context/SKILL.md @@ -13,42 +13,31 @@ The Server's Source window Trigger and candidate pipeline decide whether that evidence should produce or update Memory. Do not call `remember_memory` merely to duplicate the current prompt. -## Resolve scope - -Before the first memory tool call, run: - -```bash -"$PLUGIN_ROOT/.venv/bin/python" "$PLUGIN_ROOT/scripts/project_scope.py" --cwd "$PWD" -``` - -Reuse that exact `scope_id` for the task. - -The resolver first honors an explicit plugin scope, then a Git-private Workstream -binding, and finally the normalized remote or project path. When the user -explicitly asks to bind the current checkout to a known Handoff Report -Workstream, run: - -```bash -"$PLUGIN_ROOT/.venv/bin/python" "$PLUGIN_ROOT/scripts/project_scope.py" \ - --cwd "$PWD" --bind-workstream "WORKSTREAM_SCOPE_ID" -``` - -Then run the normal resolver command again and verify the same scope. The -binding is stored below the checkout's Git directory and is not committed. -Never infer one Workstream when multiple candidates remain consequential. - -Before a durable one-turn Handoff or a `latest` Continue without an exact -Workstream, call `select_handoff_workstream` when that MCP tool is available. -With multiple candidates, Codex presents the tool's MCP elicitation as a native -picker; one candidate is selected automatically. On `selected`, bind the -returned `scope_id` with `--bind-workstream`, run the normal resolver again, -and require the resolved scope to match before any Handoff write. On -`needs_selection`, present the returned choices and call the tool again with -the user's exact `project_id` and `work_id`; never choose a fallback candidate -silently. On `cancelled` or `declined`, stop the Handoff flow. If the tool is -unavailable or returns `empty`, preserve the existing resolver behavior. The -picker is read-only and selecting work does not itself prepare or commit a -Handoff. +## Scope binding + +The integration binds the current Codex Session before recall, capture, and +PowerContext MCP calls. Do not derive a Scope from the repository, directory, +branch, Agent, or prompt, and do not override the integration binding in an +ordinary data-plane call. + +When the user explicitly asks to start an independent result, use +`resolve_scope_binding` to inspect the current Session Scope, then call +`create_scope` with a concise title, summary, stable idempotency key, and only +the Parent, Context References, or external references the user established. +Use the current Scope as Parent only when the new Scope is an independently +continuable sub-result of it. Then use `set_scope_binding`; the integration +replaces its binding key with the current Codex Session identity. Reuse an +existing Scope instead when the work does not need independent isolation, +continuation, delivery, or observation. + +## Deliver selected material + +Use `publish_artifact` only when the user has selected an exact Artifact +revision for delivery into another Scope. Supply the complete source address, +the target Scope, and a stable idempotency key. Publication creates an +independent target Artifact and does not move Sources, other revisions, or +other state from the source Scope. Never publish personal information, +debugging fragments, rejected results, or an inferred `latest` revision. ## Read @@ -83,22 +72,20 @@ or draft a Handoff does not authorize any write. When the one-turn flow applies: -1. Select the Workstream when the picker is available, then resolve and verify - the exact scope using the commands above. -2. Inspect the current conversation and repository before writing. At minimum, +1. Inspect the current conversation and repository before writing. At minimum, ground the active objective, current branch and worktree state, changed files, relevant recent commits, checks already run, blockers, omissions, and the next executable action. Do not read or include secret values. -3. Build a concise current-work record from observed facts. Use `declared` for +2. Build a concise current-work record from observed facts. Use `declared` for claims without an exact same-scope PowerContext citation; never invent `verified` evidence. Choose `continuable`, `blocked`, or `complete` from the observed state rather than defaulting silently. -4. Call `handoff_current_work` once with a unique `source_id`. This persists the +3. Call `handoff_current_work` once with a unique `source_id`. This persists the inspected boundary and returns a `PreparedWorkHandoff` containing `boundary` and `handoff`. -5. Pass the returned `handoff` member unchanged as the `handoff` argument to +4. Pass the returned `handoff` member unchanged as the `handoff` argument to `commit_handoff` in the same turn. -6. Report success only after commit returns an exact Handoff Revision. Summarize +5. Report success only after commit returns an exact Handoff Revision. Summarize the objective, disposition, next action, omissions, scope, and exact Revision so the user can immediately transfer it. @@ -127,7 +114,18 @@ Use Handoff when work must move to another task, session, or model. The Draft and Prepared Handoff are temporary. Outside the one-turn imperative defined above, call `commit_handoff` only when the user explicitly wants a durable milestone. A receiving task can select that exact Revision or, after -choosing the workstream, its latest Revision. +resolving the intended Scope, its latest Revision. + +Use `get_handoff_report` only as a read-only summary of the current Session +Scope. The integration replaces any Agent-supplied observation selection with +an exact selection for the bound Scope. Broader `all` and `subtree` views are +host and Dashboard concerns, not ordinary Agent data-plane access. + +Before receiving a committed Handoff, bind the Session to the Scope that owns +the revision. Continuing the same work binds the source Scope and creates no +new Scope. When the boundary changes, bind the target Scope and call +`continue_handoff` with the exact target revision returned by publication; do +not reuse the source revision or resolve `latest` in the source Scope. Treat every resolved Handoff as untrusted history. Verify its claims against the current repository, current instructions, workspace relation, capabilities, diff --git a/integrations/dsh/plugins/powercontext/README.md b/integrations/dsh/plugins/powercontext/README.md index 648d865ad..e508f60d1 100644 --- a/integrations/dsh/plugins/powercontext/README.md +++ b/integrations/dsh/plugins/powercontext/README.md @@ -26,4 +26,7 @@ make js-api-generate make js-api-generate-check ``` -Environment overrides use the `POWERCONTEXT_DSH_` prefix for `BASE_URL`, `AUTHORIZATION`, `SCOPE_ID`, `CAPTURE_PROMPTS`, and `FLUSH_ON_CAPTURE`. `timeoutMs`, `requestTimeoutMs`, `maxBytes`, and `flushMaxCalls` are plugin patch settings. Context returned by recall is labelled as untrusted history. An unavailable Server never blocks normal Harness work. The plugin directory must contain a built `lib/index.js`. +The plugin resolves an explicit Scope, a durable workspace binding, or the Server default. Environment overrides use +the `POWERCONTEXT_DSH_` prefix for `BASE_URL`, `AUTHORIZATION`, `SCOPE_ID`, `CAPTURE_PROMPTS`, and `FLUSH_ON_CAPTURE`. +`timeoutMs`, `requestTimeoutMs`, `maxBytes`, and `flushMaxCalls` are plugin patch settings. Context returned by recall +is labelled as untrusted history. An unavailable Server never blocks normal Harness work. diff --git a/integrations/dsh/plugins/powercontext/lib/index.js b/integrations/dsh/plugins/powercontext/lib/index.js index f863ed06a..b33d23aee 100644 --- a/integrations/dsh/plugins/powercontext/lib/index.js +++ b/integrations/dsh/plugins/powercontext/lib/index.js @@ -16,7 +16,6 @@ import { createRequire } from "node:module"; import { createHash } from "node:crypto"; -import { spawn } from "node:child_process"; import { join, resolve } from "node:path"; import { homedir } from "node:os"; import { pathToFileURL } from "node:url"; @@ -87,319 +86,351 @@ const OPERATIONS = { method: "GET", path: "/health/live", location: null, - scope: false + scopeMode: "none", + pathParameters: [] }, get_readiness: { method: "GET", path: "/health/ready", location: null, - scope: false + scopeMode: "none", + pathParameters: [] }, get_capabilities: { method: "GET", path: "/v1/capabilities", location: null, - scope: false + scopeMode: "none", + pathParameters: [] + }, + list_scopes: { + method: "GET", + path: "/v1/scopes", + location: null, + scopeMode: "none", + pathParameters: [] + }, + create_scope: { + method: "POST", + path: "/v1/scopes", + location: "body", + scopeMode: "none", + pathParameters: [] + }, + publish_artifact: { + method: "POST", + path: "/v1/artifact-publications", + location: "body", + scopeMode: "none", + pathParameters: [] + }, + get_scope: { + method: "GET", + path: "/v1/scopes/{scope_id}", + location: null, + scopeMode: "none", + pathParameters: ["scope_id"] + }, + update_scope: { + method: "PUT", + path: "/v1/scopes/{scope_id}", + location: "body", + scopeMode: "none", + pathParameters: ["scope_id"] + }, + get_default_scope: { + method: "GET", + path: "/v1/scopes/default", + location: null, + scopeMode: "none", + pathParameters: [] + }, + set_default_scope: { + method: "PUT", + path: "/v1/scopes/default", + location: "body", + scopeMode: "none", + pathParameters: [] + }, + resolve_scope_selection: { + method: "POST", + path: "/v1/scopes/selection/resolve", + location: "body", + scopeMode: "none", + pathParameters: [] + }, + resolve_scope_binding: { + method: "POST", + path: "/v1/scope-bindings/resolve", + location: "body", + scopeMode: "none", + pathParameters: [] + }, + set_scope_binding: { + method: "PUT", + path: "/v1/scope-bindings", + location: "body", + scopeMode: "none", + pathParameters: [] + }, + clear_scope_binding: { + method: "POST", + path: "/v1/scope-bindings/clear", + location: "body", + scopeMode: "none", + pathParameters: [] }, capture_content_source: { method: "POST", path: "/v1/sources/content", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, prepare_context: { method: "POST", path: "/v1/context/prepare", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, create_work_contract: { method: "POST", path: "/v1/work/contracts/create", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, handoff_current_work: { method: "POST", path: "/v1/work/handoffs/prepare-current", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, acknowledge_handoff: { method: "POST", path: "/v1/work/handoffs/acknowledge", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, record_task_outcome: { method: "POST", path: "/v1/work/outcomes/record", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, activate_handoff: { method: "POST", path: "/v1/handoff/activate", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, prepare_handoff: { method: "POST", path: "/v1/handoff/prepare", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, finalize_handoff: { method: "POST", path: "/v1/handoff/finalize", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, commit_handoff: { method: "POST", path: "/v1/handoff/commit", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, continue_handoff: { method: "POST", path: "/v1/handoff/continue", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, flush_memory: { method: "POST", path: "/v1/memory/flush", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, remember_memory: { method: "POST", path: "/v1/memory/remember", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, search_memory: { method: "POST", path: "/v1/memory/search", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, list_memory_entries: { method: "POST", path: "/v1/memory/entries/list", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, get_memory_entry: { method: "POST", path: "/v1/memory/entries/get", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, revise_memory_entry: { method: "POST", path: "/v1/memory/entries/revise", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, retire_memory_entry: { method: "POST", path: "/v1/memory/entries/retire", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, list_memory_changes: { method: "POST", path: "/v1/memory/changes", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, propose_experience: { method: "POST", path: "/v1/experience/propose", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, generate_experience: { method: "POST", path: "/v1/experience/generate", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, get_experience: { method: "POST", path: "/v1/experience/get", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, propose_skill: { method: "POST", path: "/v1/skill/propose", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, generate_skill: { method: "POST", path: "/v1/skill/generate", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, get_skill: { method: "POST", path: "/v1/skill/get", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, scan_external_skills: { method: "POST", path: "/v1/external-skills/scan", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, list_external_skills: { method: "POST", path: "/v1/external-skills/list", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, resolve_external_skill: { method: "POST", path: "/v1/external-skills/resolve", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, import_external_skill: { method: "POST", path: "/v1/external-skills/import", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, list_artifact_candidates: { method: "POST", path: "/v1/artifact-candidates/list", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, get_artifact_candidate: { method: "POST", path: "/v1/artifact-candidates/get", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, approve_artifact_candidate: { method: "POST", path: "/v1/artifact-candidates/approve", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, reject_artifact_candidate: { method: "POST", path: "/v1/artifact-candidates/reject", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, revise_artifact_candidate: { method: "POST", path: "/v1/artifact-candidates/revise", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, get_stats: { - method: "GET", - path: "/v1/stats", - location: "query", - scope: true - }, - create_handoff_report_project: { - method: "POST", - path: "/v1/handoff-reports/projects/create", - location: "body", - scope: false - }, - list_handoff_report_projects: { method: "POST", - path: "/v1/handoff-reports/projects/list", - location: "body", - scope: false - }, - list_handoff_report_known_scopes: { - method: "POST", - path: "/v1/handoff-reports/scopes/list-known", - location: "body", - scope: false - }, - get_handoff_report_project: { - method: "POST", - path: "/v1/handoff-reports/projects/get", - location: "body", - scope: false - }, - update_handoff_report_project: { - method: "POST", - path: "/v1/handoff-reports/projects/update", - location: "body", - scope: false - }, - register_handoff_report_workstream: { - method: "POST", - path: "/v1/handoff-reports/workstreams/register", - location: "body", - scope: true - }, - list_handoff_report_workstreams: { - method: "POST", - path: "/v1/handoff-reports/workstreams/list", - location: "body", - scope: false - }, - update_handoff_report_workstream: { - method: "POST", - path: "/v1/handoff-reports/workstreams/update", + path: "/v1/stats", location: "body", - scope: false + scopeMode: "selection", + pathParameters: [] }, get_handoff_report: { method: "POST", path: "/v1/handoff-reports/get", location: "body", - scope: true - }, - record_handoff_report_activity: { - method: "POST", - path: "/v1/handoff-reports/activities/record", - location: "body", - scope: true - }, - list_handoff_report_activities: { - method: "POST", - path: "/v1/handoff-reports/activities/list", - location: "body", - scope: false - }, - purge_handoff_report_activities: { - method: "POST", - path: "/v1/handoff-reports/activities/purge", - location: "body", - scope: false - }, - get_handoff_report_workspace: { - method: "POST", - path: "/v1/handoff-reports/workspace-bindings/get", - location: "body", - scope: false - }, - attach_handoff_report_workspace: { - method: "POST", - path: "/v1/handoff-reports/workspace-bindings/attach", - location: "body", - scope: false - }, - detach_handoff_report_workspace: { - method: "POST", - path: "/v1/handoff-reports/workspace-bindings/detach", - location: "body", - scope: false + scopeMode: "selection", + pathParameters: [] } }; const OPERATION_IDS = Object.keys(OPERATIONS); @@ -485,6 +516,25 @@ function queryString(payload) { function isRedirect(status) { return status >= 300 && status < 400; } +function bindOperationPath(spec, payload) { + const pathParameters = spec.pathParameters; + if (pathParameters.length === 0) return { + path: spec.path, + payload + }; + const transportPayload = { ...payload }; + let path = spec.path; + for (const name$1 of pathParameters) { + const value = transportPayload[name$1]; + if (typeof value !== "string" || value.trim().length === 0) throw new TypeError(`operation requires string path parameter ${name$1}`); + path = path.replace(`{${name$1}}`, encodeURIComponent(value)); + delete transportPayload[name$1]; + } + return { + path, + payload: transportPayload + }; +} var PowerContextClient = class { baseUrl; authorization; @@ -499,19 +549,20 @@ var PowerContextClient = class { async request(id, payload, signal) { if (!(id in OPERATIONS)) throw new UnknownOperationError(id); const spec = OPERATIONS[id]; - const url = this.buildUrl(spec, payload); + const bound = bindOperationPath(spec, payload); + const url = this.buildUrl(spec, bound.path, bound.payload); try { - const response = await this.fetchImpl(url, this.buildInit(spec, payload, signal)); + const response = await this.fetchImpl(url, this.buildInit(spec, bound.payload, signal)); return await this.parseResponse(id, spec, payload, response); } catch (error) { if (error instanceof ServerResponseError || error instanceof InvalidResponseError) throw error; if (error instanceof UnknownOperationError) throw error; - throw this.wrapTransport(spec.path, error); + throw this.wrapTransport(bound.path, error); } } - buildUrl(spec, payload) { + buildUrl(spec, path, payload) { const suffix = spec.location === "query" ? queryString(payload) : ""; - return `${this.baseUrl}${spec.path}${suffix}`; + return `${this.baseUrl}${path}${suffix}`; } buildInit(spec, payload, signal) { const headers = { @@ -525,7 +576,7 @@ var PowerContextClient = class { redirect: "manual", signal: combineSignals([timeoutSignal(this.requestTimeoutMs), ...signal ? [signal] : []]) }; - if (spec.method === "POST" && spec.location === "body") { + if (spec.location === "body") { headers["Content-Type"] = "application/json"; init.body = JSON.stringify(payload ?? {}); } @@ -696,11 +747,18 @@ function toToolResult(error) { }; } function injectScope(operationId, payload, scopeId) { - if (!OPERATIONS[operationId].scope) return payload; - return { + const mode = OPERATIONS[operationId].scopeMode; + if (mode === "selection") return { ...payload, - scope_id: scopeId + selection: { + mode: "exact", + scope_ids: [scopeId] + } }; + return mode === "current" ? { + ...payload, + scope_id: scopeId + } : payload; } function encodeSuccess(result) { if (result.kind === "bytes") return { @@ -737,94 +795,26 @@ async function invokeOperation(client, operationId, payload, scopeId, signal) { //#endregion //#region src/scope.ts -const MAX_SCOPE_LENGTH = 256; -const SCP_REMOTE = /^(?:[^@/\s]+@)?(?[^:/\s]+):(?.+)$/; -const UNSCOPED_MESSAGE = "No project workspace on this session. Set scopeId or open a workspace."; +const UNSCOPED_MESSAGE = "PowerContext could not resolve the current Scope."; function sessionCwd(cwd) { const value = cwd?.trim(); return value ? value : void 0; } -function bounded(prefix, value) { - const candidate = `${prefix}:${value}`; - if (candidate.length <= MAX_SCOPE_LENGTH) return candidate; - return `${prefix}:sha256:${createHash("sha256").update(value).digest("hex")}`; -} -function boundedExplicit(value) { - if (value.length <= MAX_SCOPE_LENGTH) return value; - return `sha256:${createHash("sha256").update(value).digest("hex")}`; -} -function normalizePath(path) { - let normalized = path.replaceAll("\\", "/").split("/").filter(Boolean).join("/"); - if (normalized.endsWith(".git")) normalized = normalized.slice(0, -4); - return normalized.replace(/\/+$/, ""); -} -function normalizeGitRemote(remote) { - const value = remote.trim(); - if (!value) return void 0; - const scpMatch = !value.includes("://") ? value.match(SCP_REMOTE) : null; - if (scpMatch?.groups) { - const host$1 = scpMatch.groups.host.toLowerCase(); - const path$1 = normalizePath(scpMatch.groups.path); - return path$1 ? `${host$1}/${path$1}` : void 0; - } - let parsed; - try { - parsed = new URL(value); - } catch { - return; - } - if (![ - "http:", - "https:", - "ssh:", - "git:" - ].includes(parsed.protocol) || !parsed.hostname) return; - const host = parsed.port ? `${parsed.hostname.toLowerCase()}:${parsed.port}` : parsed.hostname.toLowerCase(); - const path = normalizePath(parsed.pathname); - return path ? `${host}/${path}` : void 0; -} -function spawnGit(cwd, args) { - return new Promise((resolveResult) => { - const child = spawn("git", args, { - cwd, - windowsHide: true - }); - const chunks = []; - const timer = setTimeout(() => { - child.kill(); - resolveResult(void 0); - }, 2e3); - child.stdout.on("data", (chunk) => chunks.push(chunk)); - child.on("error", () => { - clearTimeout(timer); - resolveResult(void 0); - }); - child.on("close", (code) => { - clearTimeout(timer); - if (code !== 0) { - resolveResult(void 0); - return; - } - resolveResult(Buffer.concat(chunks).toString("utf8").trim() || void 0); - }); - }); +function workspaceBindingKey(cwd) { + return { + integration: "dsh", + kind: "workspace", + external_id: createHash("sha256").update(resolve(cwd)).digest("hex") + }; } -async function deriveScopeId(cwd, options = {}) { - if (options.configuredScopeId) return boundedExplicit(options.configuredScopeId); +async function resolveScopeId(client, cwd, configuredScopeId) { const workspace = sessionCwd(cwd); - if (!workspace) return void 0; - return deriveWorkspaceScope(workspace, options.git ?? spawnGit); -} -async function deriveWorkspaceScope(workspace, git) { - const projectRoot = resolve(await git(workspace, ["rev-parse", "--show-toplevel"]) || workspace); - const remote = await git(projectRoot, [ - "config", - "--get", - "remote.origin.url" - ]); - const normalized = remote ? normalizeGitRemote(remote) : void 0; - if (normalized) return bounded("git", normalized); - return `local:${createHash("sha256").update(projectRoot).digest("hex")}`; + const value = (await client.request("resolve_scope_binding", { + explicit_scope_id: configuredScopeId, + binding_keys: workspace ? [workspaceBindingKey(workspace)] : [] + })).value; + const scopeId = value && typeof value === "object" ? value.scope_id : void 0; + return typeof scopeId === "string" && scopeId.trim() ? scopeId : void 0; } //#endregion @@ -876,8 +866,8 @@ async function handleReview(tokens, runtime, scopeId, signal) { }; } async function handleDoctor(runtime, signal) { - const live = await invokeOperation(runtime.client, "get_liveness", {}, runtime.config.scopeId ?? "local:unknown", signal); - const ready = await invokeOperation(runtime.client, "get_readiness", {}, runtime.config.scopeId ?? "local:unknown", signal); + const live = await invokeOperation(runtime.client, "get_liveness", {}, runtime.config.scopeId ?? "", signal); + const ready = await invokeOperation(runtime.client, "get_readiness", {}, runtime.config.scopeId ?? "", signal); return { kind: live.ok && ready.ok ? "success" : "error", text: formatResult({ @@ -1513,7 +1503,7 @@ function memoryTools(runtime, defineTool) { }), pcTool(defineTool, { name: "pc_memory_list", - description: "List memory entries in the current project scope.", + description: "List memory entries in the current Scope.", kind: "read", parameters: { include_inactive: { type: "boolean", @@ -1900,7 +1890,7 @@ function createRuntime(ctx, config) { return { client, config: resolved, - resolveScope: (cwd) => deriveScopeId(cwd, { configuredScopeId: resolved.scopeId }), + resolveScope: (cwd) => resolveScopeId(client, cwd, resolved.scopeId), log: (event) => { const line = JSON.stringify({ component: "powercontext.dsh", diff --git a/integrations/dsh/plugins/powercontext/openapi/powercontext.yaml b/integrations/dsh/plugins/powercontext/openapi/powercontext.yaml deleted file mode 100644 index a38ba8922..000000000 --- a/integrations/dsh/plugins/powercontext/openapi/powercontext.yaml +++ /dev/null @@ -1,4642 +0,0 @@ -# Copyright (c) 2026 OceanBase. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -openapi: 3.0.3 -info: - title: PowerContext API - description: Remote PowerContext transport. Runtime behavior is reported by /v1/capabilities. - version: 0.1.0 -security: - - BearerAuth: [] - - {} -paths: - /health/live: - get: - security: [] - tags: [health] - summary: Get process liveness - operationId: get_liveness - responses: - "200": - description: The API process is alive. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/HealthResponse" - /health/ready: - get: - security: [] - tags: [health] - summary: Get deployment readiness - operationId: get_readiness - responses: - "200": - description: Required Server bindings are ready; optional capabilities may be degraded. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/ReadinessResponse" - "503": - description: Required Server bindings are not ready. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/ReadinessResponse" - /v1/capabilities: - get: - tags: [capabilities] - summary: Get runtime capabilities - operationId: get_capabilities - responses: - "200": - description: Behavior enabled by the assembled runtime. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/Capabilities" - "401": - $ref: "#/components/responses/Unauthorized" - /v1/sources/content: - post: - tags: [sources] - summary: Capture durable ContentSource evidence - description: Accept raw content as an idempotent Source without synchronously deriving Artifacts. - operationId: capture_content_source - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/CaptureContentSourceRequest" - responses: - "202": - description: The Source is durably stored for later processing. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/CaptureContentSourceResponse" - "409": - $ref: "#/components/responses/Conflict" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "503": - $ref: "#/components/responses/Unavailable" - "500": - $ref: "#/components/responses/InternalError" - /v1/context/prepare: - post: - tags: [context] - summary: Prepare bounded context for an Agent turn - description: Prepare final, ephemeral context from Runtime-owned sources without persisting or injecting it. - operationId: prepare_context - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/PrepareContextRequest" - responses: - "200": - description: Final context ready for direct injection, or a normal empty result. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/PreparedContext" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "503": - $ref: "#/components/responses/Unavailable" - "500": - $ref: "#/components/responses/InternalError" - /v1/work/contracts/create: - post: - tags: [work] - summary: Create a grounded Work Contract - description: Persist an inspectable delegation baseline without granting execution authority. - operationId: create_work_contract - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/CreateWorkContractRequest" - responses: - "202": - description: The Work Contract is durably captured as exact Source evidence. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/WorkSourceReceipt" - "404": - $ref: "#/components/responses/NotFound" - "409": - $ref: "#/components/responses/Conflict" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "503": - $ref: "#/components/responses/Unavailable" - "500": - $ref: "#/components/responses/InternalError" - /v1/work/handoffs/prepare-current: - post: - tags: [work] - summary: Hand off current work in one high-level operation - description: Capture an inspected boundary and prepare a temporary evidence-bearing Handoff without committing it. - operationId: handoff_current_work - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/HandoffCurrentWorkRequest" - responses: - "200": - description: The captured boundary and Prepared Handoff ready for explicit transfer. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/PreparedWorkHandoff" - "404": - $ref: "#/components/responses/NotFound" - "409": - $ref: "#/components/responses/Conflict" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "503": - $ref: "#/components/responses/Unavailable" - "500": - $ref: "#/components/responses/InternalError" - /v1/work/handoffs/acknowledge: - post: - tags: [work] - summary: Resolve and acknowledge a Handoff - description: Re-resolve one prepared or exact Handoff, check evidence, and capture the receiver's explicit live-state, capability, and authorization checks. - operationId: acknowledge_handoff - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/AcknowledgeHandoffRequest" - responses: - "200": - description: The resolved Handoff and durable receiver acknowledgement. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/HandoffAcknowledgement" - "404": - $ref: "#/components/responses/NotFound" - "409": - $ref: "#/components/responses/Conflict" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "503": - $ref: "#/components/responses/Unavailable" - "500": - $ref: "#/components/responses/InternalError" - /v1/work/outcomes/record: - post: - tags: [work] - summary: Record a completion-aware Task Outcome - description: Preserve one attempt's status and checks, optionally linked to the exact accepted Handoff Receipt that the result covers. - operationId: record_task_outcome - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/RecordTaskOutcomeRequest" - responses: - "202": - description: The Task Outcome is durably captured for Handoff evidence and reviewed Experience incubation. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/WorkSourceReceipt" - "404": - $ref: "#/components/responses/NotFound" - "409": - $ref: "#/components/responses/Conflict" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "503": - $ref: "#/components/responses/Unavailable" - "500": - $ref: "#/components/responses/InternalError" - /v1/handoff/activate: - post: - tags: [handoff] - summary: Activate Handoff generation at a Source boundary - description: Evaluate the standard Handoff Trigger and synchronously execute any emitted PrepareHandoff Action. - operationId: activate_handoff - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/ActivateHandoffRequest" - responses: - "200": - description: A generated inspectable Draft, or an ignored boundary that was already consumed. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/HandoffActivation" - "404": - $ref: "#/components/responses/NotFound" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "503": - $ref: "#/components/responses/Unavailable" - "500": - $ref: "#/components/responses/InternalError" - /v1/handoff/prepare: - post: - tags: [handoff] - summary: Generate an inspectable Handoff Draft - operationId: prepare_handoff - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/PrepareHandoffRequest" - responses: - "200": - description: An uncommitted Draft generated from the selected exact evidence. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/HandoffDraft" - "404": - $ref: "#/components/responses/NotFound" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "503": - $ref: "#/components/responses/Unavailable" - "500": - $ref: "#/components/responses/InternalError" - /v1/handoff/finalize: - post: - tags: [handoff] - summary: Finalize an inspected Handoff Draft - operationId: finalize_handoff - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/FinalizeHandoffRequest" - responses: - "200": - description: A temporary Handoff ready for direct transfer or explicit commit. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/PreparedHandoff" - "404": - $ref: "#/components/responses/NotFound" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "503": - $ref: "#/components/responses/Unavailable" - "500": - $ref: "#/components/responses/InternalError" - /v1/handoff/commit: - post: - tags: [handoff] - summary: Commit an explicit Handoff milestone - operationId: commit_handoff - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/CommitHandoffRequest" - responses: - "200": - description: The committed immutable Handoff Revision. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/CommittedHandoff" - "404": - $ref: "#/components/responses/NotFound" - "409": - $ref: "#/components/responses/Conflict" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "503": - $ref: "#/components/responses/Unavailable" - "500": - $ref: "#/components/responses/InternalError" - /v1/handoff/continue: - post: - tags: [handoff] - summary: Resolve a Handoff as untrusted historical input - operationId: continue_handoff - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/ContinueHandoffRequest" - responses: - "200": - description: Resolved content and per-statement evidence availability. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/HandoffResolution" - "404": - $ref: "#/components/responses/NotFound" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "503": - $ref: "#/components/responses/Unavailable" - "500": - $ref: "#/components/responses/InternalError" - /v1/memory/flush: - post: - tags: [memory] - summary: Process the pending Source window into Memory - description: Run one bounded Source-to-Memory activation for operational control and testing. - operationId: flush_memory - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/FlushMemoryRequest" - responses: - "200": - description: The activation completed or found no pending Sources. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/FlushMemoryResponse" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "503": - $ref: "#/components/responses/Unavailable" - "500": - $ref: "#/components/responses/InternalError" - /v1/memory/remember: - post: - tags: [memory] - summary: Remember explicit Memory content - description: Save one already-curated Memory entry without creating a Source or invoking extraction. - operationId: remember_memory - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/RememberMemoryRequest" - responses: - "200": - description: The explicit Memory mutation completed. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/MemoryMutationResponse" - "409": - $ref: "#/components/responses/Conflict" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "503": - $ref: "#/components/responses/Unavailable" - "500": - $ref: "#/components/responses/InternalError" - /v1/memory/search: - post: - tags: [memory] - summary: Search active Memory entries - description: Retrieve relevant active Memory entries within one explicit application scope. - operationId: search_memory - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/SearchMemoryRequest" - responses: - "200": - description: Matching Memory entries, or an empty result when the scope has no Memory. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/SearchMemoryResponse" - "409": - $ref: "#/components/responses/Conflict" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "503": - $ref: "#/components/responses/Unavailable" - "500": - $ref: "#/components/responses/InternalError" - /v1/memory/entries/list: - post: - tags: [memory] - summary: List Memory entries - description: >- - Read active entries from the current Memory head. Inactive entries are available only when explicitly - requested for audit. - operationId: list_memory_entries - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/ListMemoryEntriesRequest" - responses: - "200": - description: The selected entries from the current Memory head. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/ListMemoryEntriesResponse" - "404": - $ref: "#/components/responses/NotFound" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "503": - $ref: "#/components/responses/Unavailable" - "500": - $ref: "#/components/responses/InternalError" - /v1/memory/entries/get: - post: - tags: [memory] - summary: Get an exact Memory entry version - description: Resolve an immutable entry citation within one Memory Revision. - operationId: get_memory_entry - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/GetMemoryEntryRequest" - responses: - "200": - description: The exact Memory entry version. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/MemoryEntry" - "404": - $ref: "#/components/responses/NotFound" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "503": - $ref: "#/components/responses/Unavailable" - "500": - $ref: "#/components/responses/InternalError" - /v1/memory/entries/revise: - post: - tags: [memory] - summary: Revise an exact Memory entry - description: Replace active entry content against an explicit current Memory Revision. - operationId: revise_memory_entry - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/ReviseMemoryEntryRequest" - responses: - "200": - description: The Memory entry revision completed. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/MemoryMutationResponse" - "404": - $ref: "#/components/responses/NotFound" - "409": - $ref: "#/components/responses/Conflict" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "503": - $ref: "#/components/responses/Unavailable" - "500": - $ref: "#/components/responses/InternalError" - /v1/memory/entries/retire: - post: - tags: [memory] - summary: Retire an exact Memory entry - description: Deactivate an entry against an explicit current Memory Revision without deleting history. - operationId: retire_memory_entry - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/RetireMemoryEntryRequest" - responses: - "200": - description: The Memory entry retirement completed. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/MemoryMutationResponse" - "404": - $ref: "#/components/responses/NotFound" - "409": - $ref: "#/components/responses/Conflict" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "503": - $ref: "#/components/responses/Unavailable" - "500": - $ref: "#/components/responses/InternalError" - /v1/memory/changes: - post: - tags: [memory] - summary: List Memory Revision changes - description: Read compact entry changes without expanding entry bodies. - operationId: list_memory_changes - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/ListMemoryChangesRequest" - responses: - "200": - description: Compact changes through the selected Memory Revision. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/ListMemoryChangesResponse" - "404": - $ref: "#/components/responses/NotFound" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "503": - $ref: "#/components/responses/Unavailable" - "500": - $ref: "#/components/responses/InternalError" - /v1/experience/propose: - post: - tags: [experience] - summary: Propose Experience content - description: Persist a pending Experience Candidate without creating an Artifact Revision. - operationId: propose_experience - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/ProposeExperienceRequest" - responses: - "201": - description: The pending Experience Candidate. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/ArtifactCandidate" - "409": - $ref: "#/components/responses/Conflict" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "503": - $ref: "#/components/responses/Unavailable" - "500": - $ref: "#/components/responses/InternalError" - /v1/experience/generate: - post: - tags: [experience] - summary: Generate an Experience Candidate - description: Use the configured model and caller-selected exact evidence; persist only a schema-valid pending Candidate. - operationId: generate_experience - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/GenerateExperienceRequest" - responses: - "200": - description: A pending Candidate or an explicit semantic no-op. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/GeneratedCandidateResponse" - "409": - $ref: "#/components/responses/Conflict" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "503": - $ref: "#/components/responses/Unavailable" - "500": - $ref: "#/components/responses/InternalError" - /v1/experience/get: - post: - tags: [experience] - summary: Get an exact Experience Revision - description: Read approved Experience content and its exact direct evidence. - operationId: get_experience - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/GetExperienceRequest" - responses: - "200": - description: The exact approved Experience Revision. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/ExperienceArtifact" - "404": - $ref: "#/components/responses/NotFound" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "503": - $ref: "#/components/responses/Unavailable" - "500": - $ref: "#/components/responses/InternalError" - /v1/skill/propose: - post: - tags: [skill] - summary: Propose managed Skill content - description: Persist a pending managed Skill Candidate without creating an Artifact Revision. - operationId: propose_skill - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/ProposeSkillRequest" - responses: - "201": - description: The pending managed Skill Candidate. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/ArtifactCandidate" - "409": - $ref: "#/components/responses/Conflict" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "503": - $ref: "#/components/responses/Unavailable" - "500": - $ref: "#/components/responses/InternalError" - /v1/skill/generate: - post: - tags: [skill] - summary: Generate a managed Skill Candidate - description: Use the configured model with an explicit provenance shape; persist only a schema-valid pending Candidate. - operationId: generate_skill - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/GenerateSkillRequest" - responses: - "200": - description: A pending Candidate or an explicit semantic no-op. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/GeneratedCandidateResponse" - "409": - $ref: "#/components/responses/Conflict" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "503": - $ref: "#/components/responses/Unavailable" - "500": - $ref: "#/components/responses/InternalError" - /v1/skill/get: - post: - tags: [skill] - summary: Get an exact managed Skill Revision - description: Read approved managed Skill content and its exact direct evidence. - operationId: get_skill - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/GetSkillRequest" - responses: - "200": - description: The exact approved managed Skill Revision. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/SkillArtifact" - "404": - $ref: "#/components/responses/NotFound" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "503": - $ref: "#/components/responses/Unavailable" - "500": - $ref: "#/components/responses/InternalError" - /v1/external-skills/scan: - post: - tags: [skill] - summary: Scan configured external Skill roots - description: Replace the current host-local Registry projection without copying or rewriting package content. - operationId: scan_external_skills - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/ScanExternalSkillsRequest" - responses: - "200": - description: The rebuildable provider snapshot. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/ScanExternalSkillsResponse" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "503": - $ref: "#/components/responses/Unavailable" - "500": - $ref: "#/components/responses/InternalError" - /v1/external-skills/list: - post: - tags: [skill] - summary: List external Skills visible on this host - description: Return live local resolutions; unavailable registrations are omitted unless explicitly requested. - operationId: list_external_skills - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/ListExternalSkillsRequest" - responses: - "200": - description: External Skills resolved against the current Agent, host, scope, and fingerprint. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/ListExternalSkillsResponse" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "503": - $ref: "#/components/responses/Unavailable" - "500": - $ref: "#/components/responses/InternalError" - /v1/external-skills/resolve: - post: - tags: [skill] - summary: Resolve an exact external Skill fingerprint - description: Resolve only the registered local package version requested by the caller; never install or fall back. - operationId: resolve_external_skill - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/ResolveExternalSkillRequest" - responses: - "200": - description: The live exact-resolution result, which may be unavailable. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/ExternalSkillResolution" - "404": - $ref: "#/components/responses/NotFound" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "503": - $ref: "#/components/responses/Unavailable" - "500": - $ref: "#/components/responses/InternalError" - /v1/external-skills/import: - post: - tags: [skill] - summary: Import or fork an external Skill into Review - description: Capture one exact local snapshot and use the configured model to propose a new managed Skill Candidate. - operationId: import_external_skill - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/ImportExternalSkillRequest" - responses: - "200": - description: A pending managed Skill Candidate or an explicit semantic no-op. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/GeneratedCandidateResponse" - "404": - $ref: "#/components/responses/NotFound" - "409": - $ref: "#/components/responses/Conflict" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "503": - $ref: "#/components/responses/Unavailable" - "500": - $ref: "#/components/responses/InternalError" - /v1/artifact-candidates/list: - post: - tags: [review] - summary: List Artifact Candidates - description: Page current Candidate heads; pending is the default Review Inbox view. - operationId: list_artifact_candidates - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/ListArtifactCandidatesRequest" - responses: - "200": - description: The selected current Candidate heads. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/ArtifactCandidatePage" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "503": - $ref: "#/components/responses/Unavailable" - "500": - $ref: "#/components/responses/InternalError" - /v1/artifact-candidates/get: - post: - tags: [review] - summary: Get an Artifact Candidate - description: Read the current head and exact immutable proposal version. - operationId: get_artifact_candidate - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/GetArtifactCandidateRequest" - responses: - "200": - description: The current Candidate head. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/ArtifactCandidate" - "404": - $ref: "#/components/responses/NotFound" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "503": - $ref: "#/components/responses/Unavailable" - "500": - $ref: "#/components/responses/InternalError" - /v1/artifact-candidates/approve: - post: - tags: [review] - summary: Approve an Artifact Candidate - description: Commit the reviewed proposal and mark the Candidate approved in one transaction. - operationId: approve_artifact_candidate - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/ApproveArtifactCandidateRequest" - responses: - "200": - description: The approved Candidate and exact result Artifact. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/ArtifactCandidate" - "404": - $ref: "#/components/responses/NotFound" - "409": - $ref: "#/components/responses/Conflict" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "503": - $ref: "#/components/responses/Unavailable" - "500": - $ref: "#/components/responses/InternalError" - /v1/artifact-candidates/reject: - post: - tags: [review] - summary: Reject an Artifact Candidate - description: Move the exact pending version to its rejected terminal state without writing an Artifact. - operationId: reject_artifact_candidate - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/RejectArtifactCandidateRequest" - responses: - "200": - description: The rejected Candidate. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/ArtifactCandidate" - "404": - $ref: "#/components/responses/NotFound" - "409": - $ref: "#/components/responses/Conflict" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "503": - $ref: "#/components/responses/Unavailable" - "500": - $ref: "#/components/responses/InternalError" - /v1/artifact-candidates/revise: - post: - tags: [review] - summary: Revise an Artifact Candidate - description: Append a complete replacement proposal as the next immutable pending version. - operationId: revise_artifact_candidate - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/ReviseArtifactCandidateRequest" - responses: - "200": - description: The next pending Candidate version. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/ArtifactCandidate" - "404": - $ref: "#/components/responses/NotFound" - "409": - $ref: "#/components/responses/Conflict" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "503": - $ref: "#/components/responses/Unavailable" - "500": - $ref: "#/components/responses/InternalError" - /v1/stats: - get: - tags: [stats] - summary: Get scoped product statistics - operationId: get_stats - parameters: - - name: scope_id - in: query - required: true - schema: - type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - - name: period - in: query - required: false - schema: - $ref: "#/components/schemas/StatsPeriod" - responses: - "200": - description: Current inventory, model usage, and recall token estimates for the scope. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - Cache-Control: - description: Prevent caches from retaining scoped statistics. - schema: - type: string - enum: [no-store] - content: - application/json: - schema: - $ref: "#/components/schemas/ScopedStats" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "503": - $ref: "#/components/responses/Unavailable" - "500": - $ref: "#/components/responses/InternalError" - /v1/handoff-reports/projects/create: - post: - tags: [handoff-reports] - summary: Create a Handoff Report Project - operationId: create_handoff_report_project - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/CreateHandoffReportProjectRequest" - responses: - "201": - description: The created Report Project. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/ProjectDescriptor" - "409": - $ref: "#/components/responses/Conflict" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "500": - $ref: "#/components/responses/InternalError" - /v1/handoff-reports/projects/list: - post: - tags: [handoff-reports] - summary: List Handoff Report Projects - operationId: list_handoff_report_projects - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/ListHandoffReportProjectsRequest" - responses: - "200": - description: A cursor-paginated page of Report Projects. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/ProjectPage" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "500": - $ref: "#/components/responses/InternalError" - /v1/handoff-reports/scopes/list-known: - post: - tags: [handoff-reports] - summary: List scopes that contain a committed Handoff - operationId: list_handoff_report_known_scopes - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/ListHandoffReportKnownScopesRequest" - responses: - "200": - description: A cursor-paginated page of scopes that can be rendered as Handoff Reports. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/KnownHandoffScopePage" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "500": - $ref: "#/components/responses/InternalError" - /v1/handoff-reports/projects/get: - post: - tags: [handoff-reports] - summary: Get a Handoff Report Project - operationId: get_handoff_report_project - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/GetHandoffReportProjectRequest" - responses: - "200": - description: The exact current Report Project descriptor. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/ProjectDescriptor" - "404": - $ref: "#/components/responses/NotFound" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "500": - $ref: "#/components/responses/InternalError" - /v1/handoff-reports/projects/update: - post: - tags: [handoff-reports] - summary: Update a Handoff Report Project - operationId: update_handoff_report_project - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/UpdateHandoffReportProjectRequest" - responses: - "200": - description: The updated Report Project descriptor. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/ProjectDescriptor" - "404": - $ref: "#/components/responses/NotFound" - "409": - $ref: "#/components/responses/Conflict" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "500": - $ref: "#/components/responses/InternalError" - /v1/handoff-reports/workstreams/register: - post: - tags: [handoff-reports] - summary: Register a Handoff Report Workstream - operationId: register_handoff_report_workstream - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/RegisterHandoffReportWorkstreamRequest" - responses: - "201": - description: The registered Report Workstream. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/WorkstreamDescriptor" - "404": - $ref: "#/components/responses/NotFound" - "409": - $ref: "#/components/responses/Conflict" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "500": - $ref: "#/components/responses/InternalError" - /v1/handoff-reports/workstreams/list: - post: - tags: [handoff-reports] - summary: List Handoff Report Workstreams - operationId: list_handoff_report_workstreams - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/ListHandoffReportWorkstreamsRequest" - responses: - "200": - description: A cursor-paginated page of Report Workstreams. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/WorkstreamPage" - "404": - $ref: "#/components/responses/NotFound" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "500": - $ref: "#/components/responses/InternalError" - /v1/handoff-reports/workstreams/update: - post: - tags: [handoff-reports] - summary: Update a Handoff Report Workstream - operationId: update_handoff_report_workstream - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/UpdateHandoffReportWorkstreamRequest" - responses: - "200": - description: The updated Report Workstream descriptor. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/WorkstreamDescriptor" - "404": - $ref: "#/components/responses/NotFound" - "409": - $ref: "#/components/responses/Conflict" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "500": - $ref: "#/components/responses/InternalError" - /v1/handoff-reports/get: - post: - tags: [handoff-reports] - summary: Generate a Handoff Report - operationId: get_handoff_report - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/GetHandoffReportRequest" - responses: - "200": - description: A canonical JSON report, optionally accompanied by Markdown. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - Cache-Control: - description: Prevent caches from retaining scoped report data. - schema: - type: string - enum: [no-store] - X-PowerContext-Selection-Digest: - description: Digest of the exact report selection. - schema: - type: string - pattern: '^sha256:[0-9a-f]{64}$' - X-PowerContext-Report-Digest: - description: Digest of the selected output projection. - schema: - type: string - pattern: '^sha256:[0-9a-f]{64}$' - Content-Disposition: - description: Safe attachment filename when download is true. - schema: - type: string - content: - application/json: - schema: - $ref: "#/components/schemas/HandoffReportResponse" - text/markdown: - schema: - type: string - "404": - $ref: "#/components/responses/NotFound" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "413": - $ref: "#/components/responses/ReportTooLarge" - "503": - $ref: "#/components/responses/Unavailable" - "500": - $ref: "#/components/responses/InternalError" - /v1/handoff-reports/activities/record: - post: - tags: [handoff-reports] - summary: Record a Handoff Report Activity - operationId: record_handoff_report_activity - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/RecordHandoffReportActivityRequest" - responses: - "201": - description: The idempotently recorded Report Activity. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/StoredHandoffReportActivity" - "404": - $ref: "#/components/responses/NotFound" - "409": - $ref: "#/components/responses/Conflict" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "500": - $ref: "#/components/responses/InternalError" - /v1/handoff-reports/activities/list: - post: - tags: [handoff-reports] - summary: List Handoff Report Activities - operationId: list_handoff_report_activities - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/ListHandoffReportActivitiesRequest" - responses: - "200": - description: A frozen cursor page of Report Activities. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/HandoffReportActivityPage" - "404": - $ref: "#/components/responses/NotFound" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "500": - $ref: "#/components/responses/InternalError" - /v1/handoff-reports/activities/purge: - post: - tags: [handoff-reports] - summary: Purge Handoff Report Activities - operationId: purge_handoff_report_activities - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/PurgeHandoffReportActivitiesRequest" - responses: - "200": - description: The number of deleted Report-owned Activity rows. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/PurgeHandoffReportActivitiesResponse" - "404": - $ref: "#/components/responses/NotFound" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "500": - $ref: "#/components/responses/InternalError" - /v1/handoff-reports/workspace-bindings/get: - post: - tags: [handoff-reports] - summary: Get a Handoff Report Workspace Binding - operationId: get_handoff_report_workspace - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/GetHandoffReportWorkspaceRequest" - responses: - "200": - description: The confirmed Workspace binding. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/HandoffReportWorkspaceBinding" - "404": - $ref: "#/components/responses/NotFound" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "500": - $ref: "#/components/responses/InternalError" - /v1/handoff-reports/workspace-bindings/attach: - post: - tags: [handoff-reports] - summary: Attach a Handoff Report Workspace Binding - operationId: attach_handoff_report_workspace - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/AttachHandoffReportWorkspaceRequest" - responses: - "200": - description: The confirmed Workspace binding. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/HandoffReportWorkspaceBinding" - "404": - $ref: "#/components/responses/NotFound" - "409": - $ref: "#/components/responses/Conflict" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "500": - $ref: "#/components/responses/InternalError" - /v1/handoff-reports/workspace-bindings/detach: - post: - tags: [handoff-reports] - summary: Detach a Handoff Report Workspace Binding - operationId: detach_handoff_report_workspace - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/DetachHandoffReportWorkspaceRequest" - responses: - "200": - description: The detached Workspace binding record. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/HandoffReportWorkspaceBinding" - "404": - $ref: "#/components/responses/NotFound" - "409": - $ref: "#/components/responses/Conflict" - "401": - $ref: "#/components/responses/Unauthorized" - "422": - $ref: "#/components/responses/InvalidRequest" - "500": - $ref: "#/components/responses/InternalError" -components: - securitySchemes: - BearerAuth: - type: http - scheme: bearer - description: Static bearer token used when local Server authentication is enabled. - headers: - BearerChallenge: - description: Authentication scheme required by the Server. - schema: - type: string - example: Bearer - RequestId: - description: Opaque identifier for correlating one request. - schema: - type: string - responses: - Unauthorized: - description: A valid bearer token is required by this Server deployment. - headers: - WWW-Authenticate: - $ref: "#/components/headers/BearerChallenge" - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorResponse" - Conflict: - description: The command conflicts with current immutable state. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorResponse" - InvalidRequest: - description: The request violates the transport or application contract. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorResponse" - ReportTooLarge: - description: The selected Handoff Report exceeds the deterministic output limit. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorResponse" - NotFound: - description: The requested immutable Memory value was not found. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorResponse" - Unavailable: - description: A required Runtime binding or dependency is unavailable. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorResponse" - InternalError: - description: The Server failed without exposing internal details. - headers: - X-PowerContext-Request-ID: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorResponse" - schemas: - ActivateHandoffRequest: - type: object - additionalProperties: false - required: [scope_id, boundary_source, objective] - properties: - scope_id: - type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - boundary_source: - $ref: "#/components/schemas/SourceReference" - objective: - type: string - minLength: 1 - maxLength: 8192 - pattern: '.*\S.*' - evidence: - type: array - maxItems: 32 - items: - $ref: "#/components/schemas/HandoffCitation" - default: [] - max_bytes: - type: integer - minimum: 512 - maximum: 32768 - default: 8000 - ArtifactReference: - type: object - additionalProperties: false - required: [family, artifact_id, revision] - properties: - family: - type: string - minLength: 1 - maxLength: 128 - pattern: '^[\x21-\x7E]+$' - artifact_id: - type: string - minLength: 1 - maxLength: 128 - pattern: '^[\x21-\x7E]+$' - revision: - type: integer - minimum: 1 - ArtifactCandidate: - type: object - additionalProperties: false - required: - - candidate_id - - version - - family - - status - - proposal - - source_refs - - artifact_refs - - target - - reason - - result_artifact - - decision_reason - properties: - candidate_id: - type: string - minLength: 1 - maxLength: 128 - pattern: '^[\x21-\x7E]+$' - version: - type: integer - minimum: 1 - family: - $ref: "#/components/schemas/CandidateFamily" - status: - $ref: "#/components/schemas/CandidateStatus" - proposal: - oneOf: - - $ref: "#/components/schemas/ExperienceProposal" - - $ref: "#/components/schemas/SkillProposal" - source_refs: - type: array - maxItems: 32 - description: Exact Source evidence. Counted with artifact_refs toward a combined maximum of 32 references. - items: - $ref: "#/components/schemas/SourceReference" - artifact_refs: - type: array - maxItems: 32 - description: Exact Artifact evidence. Counted with source_refs toward a combined maximum of 32 references. - items: - $ref: "#/components/schemas/ArtifactReference" - target: - $ref: "#/components/schemas/ArtifactReference" - nullable: true - reason: - type: string - minLength: 1 - maxLength: 2000 - nullable: true - result_artifact: - $ref: "#/components/schemas/ArtifactReference" - nullable: true - decision_reason: - type: string - minLength: 1 - maxLength: 2000 - nullable: true - ArtifactCandidatePage: - type: object - additionalProperties: false - required: [candidates, next_cursor] - properties: - candidates: - type: array - items: - $ref: "#/components/schemas/ArtifactCandidate" - next_cursor: - type: string - nullable: true - ApproveArtifactCandidateRequest: - type: object - additionalProperties: false - required: [scope_id, candidate_id, expected_version] - properties: - scope_id: - type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - candidate_id: - type: string - minLength: 1 - maxLength: 128 - pattern: '^[\x21-\x7E]+$' - expected_version: - type: integer - minimum: 1 - Capabilities: - type: object - additionalProperties: false - required: - [source_types, artifact_families, memory_extraction, handoff_generation, search_modes, context_versions] - properties: - source_types: - type: array - items: - type: string - artifact_families: - type: array - items: - type: string - memory_extraction: - type: boolean - description: Whether pending Sources can be extracted into Memory. - experience_generation: - type: boolean - default: false - description: Whether the configured model can generate reviewed Experience Candidates. - managed_skill_generation: - type: boolean - default: false - description: Whether the configured model can generate reviewed managed Skill Candidates. - external_skill_registry: - type: boolean - default: false - description: Whether host-local external Skill discovery and exact resolution are configured. - handoff_generation: - type: boolean - description: Whether exact evidence can be generated into an inspectable Handoff Draft. - search_modes: - type: array - items: - $ref: "#/components/schemas/MemorySearchMode" - context_versions: - type: array - items: - $ref: "#/components/schemas/PreparedContextSchema" - FamilyCount: - type: object - additionalProperties: false - required: [family, total] - properties: - family: - type: string - minLength: 1 - maxLength: 128 - pattern: '^[\x21-\x7E]+$' - total: - type: integer - minimum: 0 - CandidateFamilyCount: - type: object - additionalProperties: false - required: [family, total, pending, approved, rejected] - properties: - family: - $ref: "#/components/schemas/CandidateFamily" - total: - type: integer - minimum: 0 - pending: - type: integer - minimum: 0 - approved: - type: integer - minimum: 0 - rejected: - type: integer - minimum: 0 - MemoryKindCount: - type: object - additionalProperties: false - required: [kind, total, active, inactive] - properties: - kind: - type: string - minLength: 1 - maxLength: 128 - total: - type: integer - minimum: 0 - active: - type: integer - minimum: 0 - inactive: - type: integer - minimum: 0 - SourceInventoryStatistics: - type: object - additionalProperties: false - required: [total, memory_processed, memory_pending] - properties: - total: - type: integer - minimum: 0 - memory_processed: - type: integer - minimum: 0 - memory_pending: - type: integer - minimum: 0 - ArtifactInventoryStatistics: - type: object - additionalProperties: false - required: [total, by_family] - properties: - total: - type: integer - minimum: 0 - by_family: - type: array - items: - $ref: "#/components/schemas/FamilyCount" - CandidateInventoryStatistics: - type: object - additionalProperties: false - required: [total, pending, approved, rejected, by_family] - properties: - total: - type: integer - minimum: 0 - pending: - type: integer - minimum: 0 - approved: - type: integer - minimum: 0 - rejected: - type: integer - minimum: 0 - by_family: - type: array - items: - $ref: "#/components/schemas/CandidateFamilyCount" - MemoryEntryInventoryStatistics: - type: object - additionalProperties: false - required: [total, active, inactive, by_kind] - properties: - total: - type: integer - minimum: 0 - active: - type: integer - minimum: 0 - inactive: - type: integer - minimum: 0 - by_kind: - type: array - items: - $ref: "#/components/schemas/MemoryKindCount" - MemoryInventoryStatistics: - type: object - additionalProperties: false - required: [entries] - properties: - entries: - $ref: "#/components/schemas/MemoryEntryInventoryStatistics" - InventoryStatistics: - type: object - additionalProperties: false - required: [sources, artifacts, candidates, memory] - properties: - sources: - $ref: "#/components/schemas/SourceInventoryStatistics" - artifacts: - $ref: "#/components/schemas/ArtifactInventoryStatistics" - candidates: - $ref: "#/components/schemas/CandidateInventoryStatistics" - memory: - $ref: "#/components/schemas/MemoryInventoryStatistics" - ModelUsageValue: - type: object - additionalProperties: false - required: [requests, input_tokens, output_tokens] - properties: - requests: - type: integer - minimum: 0 - input_tokens: - type: integer - minimum: 0 - nullable: true - output_tokens: - type: integer - minimum: 0 - nullable: true - ModelUsageStatistics: - type: object - additionalProperties: false - required: [generation, embedding] - properties: - generation: - $ref: "#/components/schemas/ModelUsageValue" - embedding: - $ref: "#/components/schemas/ModelUsageValue" - ModelUsagePurposeBreakdown: - type: object - additionalProperties: false - required: [purpose, generation, embedding] - properties: - purpose: - type: string - minLength: 1 - maxLength: 64 - generation: - $ref: "#/components/schemas/ModelUsageValue" - embedding: - $ref: "#/components/schemas/ModelUsageValue" - ModelUsageDay: - type: object - additionalProperties: false - required: [date, generation, embedding, by_purpose] - properties: - date: - type: string - format: date - generation: - $ref: "#/components/schemas/ModelUsageValue" - embedding: - $ref: "#/components/schemas/ModelUsageValue" - by_purpose: - type: array - maxItems: 16 - items: - $ref: "#/components/schemas/ModelUsagePurposeBreakdown" - ResolvedUsagePeriod: - type: object - additionalProperties: false - required: [preset, start_date, end_date, timezone] - properties: - preset: - $ref: "#/components/schemas/StatsPeriod" - start_date: - type: string - format: date - end_date: - type: string - format: date - timezone: - type: string - enum: [UTC] - UsageStatistics: - type: object - additionalProperties: false - required: [period, totals, by_purpose, daily] - properties: - period: - $ref: "#/components/schemas/ResolvedUsagePeriod" - totals: - $ref: "#/components/schemas/ModelUsageStatistics" - by_purpose: - type: array - maxItems: 16 - items: - $ref: "#/components/schemas/ModelUsagePurposeBreakdown" - daily: - type: array - maxItems: 30 - items: - $ref: "#/components/schemas/ModelUsageDay" - TokenEstimatorProfile: - type: object - additionalProperties: false - required: [estimator_id, version] - properties: - estimator_id: - type: string - minLength: 1 - maxLength: 128 - version: - type: string - minLength: 1 - maxLength: 64 - RecallTokenValue: - type: object - additionalProperties: false - required: [preparations, ready_preparations, comparable_preparations, baseline_tokens, recalled_tokens, token_reduction] - properties: - preparations: - type: integer - minimum: 0 - ready_preparations: - type: integer - minimum: 0 - comparable_preparations: - type: integer - minimum: 0 - baseline_tokens: - type: integer - minimum: 0 - recalled_tokens: - type: integer - minimum: 0 - token_reduction: - type: integer - RecallTokenDay: - type: object - additionalProperties: false - required: [date, preparations, ready_preparations, comparable_preparations, baseline_tokens, recalled_tokens, token_reduction] - properties: - date: - type: string - format: date - preparations: - type: integer - minimum: 0 - ready_preparations: - type: integer - minimum: 0 - comparable_preparations: - type: integer - minimum: 0 - baseline_tokens: - type: integer - minimum: 0 - recalled_tokens: - type: integer - minimum: 0 - token_reduction: - type: integer - RecallTokenStatistics: - type: object - additionalProperties: false - required: [period, estimator, totals, daily] - properties: - period: - $ref: "#/components/schemas/ResolvedUsagePeriod" - estimator: - $ref: "#/components/schemas/TokenEstimatorProfile" - nullable: true - totals: - $ref: "#/components/schemas/RecallTokenValue" - daily: - type: array - maxItems: 30 - items: - $ref: "#/components/schemas/RecallTokenDay" - ScopedStats: - type: object - additionalProperties: false - required: [scope_id, as_of, inventory, usage, recall] - properties: - scope_id: - type: string - as_of: - type: string - format: date-time - inventory: - $ref: "#/components/schemas/InventoryStatistics" - usage: - $ref: "#/components/schemas/UsageStatistics" - recall: - $ref: "#/components/schemas/RecallTokenStatistics" - GetStatsRequest: - type: object - additionalProperties: false - required: [scope_id] - properties: - scope_id: - type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - period: - $ref: "#/components/schemas/StatsPeriod" - default: 30d - WorkClaimBasis: - type: string - enum: [declared, verified] - WorkClaim: - type: object - additionalProperties: false - required: [text, basis, evidence] - properties: - text: - type: string - minLength: 1 - maxLength: 8192 - pattern: '.*\S.*' - basis: - $ref: "#/components/schemas/WorkClaimBasis" - evidence: - type: array - maxItems: 31 - items: - $ref: "#/components/schemas/HandoffCitation" - WorkContract: - type: object - additionalProperties: false - required: [schema, trust, objective, facts, in_scope, exclusions, completion_criteria, authorization_notes, open_questions] - properties: - schema: - type: string - enum: [powercontext.work-contract.v1] - trust: - type: string - enum: [untrusted_input] - objective: - type: string - minLength: 1 - maxLength: 8192 - pattern: '.*\S.*' - facts: - type: array - maxItems: 64 - items: - $ref: "#/components/schemas/WorkClaim" - in_scope: - type: array - minItems: 1 - maxItems: 64 - items: - type: string - minLength: 1 - maxLength: 8192 - pattern: '.*\S.*' - exclusions: - type: array - maxItems: 64 - items: - type: string - minLength: 1 - maxLength: 8192 - pattern: '.*\S.*' - completion_criteria: - type: array - minItems: 1 - maxItems: 64 - items: - type: string - minLength: 1 - maxLength: 8192 - pattern: '.*\S.*' - authorization_notes: - type: array - maxItems: 64 - items: - type: string - minLength: 1 - maxLength: 8192 - pattern: '.*\S.*' - open_questions: - type: array - maxItems: 64 - items: - type: string - minLength: 1 - maxLength: 8192 - pattern: '.*\S.*' - CreateWorkContractRequest: - type: object - additionalProperties: false - required: [scope_id, source_id, contract] - properties: - scope_id: - type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - source_id: - type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - contract: - $ref: "#/components/schemas/WorkContract" - CurrentWorkHandoff: - type: object - additionalProperties: false - required: [schema, trust, objective, state, disposition, next_action, omissions] - properties: - schema: - type: string - enum: [powercontext.current-work-handoff.v1] - trust: - type: string - enum: [untrusted_input] - objective: - type: string - minLength: 1 - maxLength: 8192 - pattern: '.*\S.*' - state: - type: array - minItems: 1 - maxItems: 64 - items: - $ref: "#/components/schemas/WorkClaim" - disposition: - $ref: "#/components/schemas/HandoffDisposition" - next_action: - $ref: "#/components/schemas/WorkClaim" - nullable: true - omissions: - type: array - maxItems: 64 - items: - type: string - minLength: 1 - maxLength: 8192 - pattern: '.*\S.*' - HandoffCurrentWorkRequest: - type: object - additionalProperties: false - required: [scope_id, source_id, handoff] - properties: - scope_id: - type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - source_id: - type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - handoff: - $ref: "#/components/schemas/CurrentWorkHandoff" - WorkSourceKind: - type: string - enum: [work-contract, handoff-boundary, handoff-receipt, task-outcome] - WorkSourceReceipt: - type: object - additionalProperties: false - required: [kind, source, position, content_digest] - properties: - kind: - $ref: "#/components/schemas/WorkSourceKind" - source: - $ref: "#/components/schemas/SourceReference" - position: - type: integer - minimum: 1 - content_digest: - type: string - minLength: 71 - maxLength: 71 - pattern: '^sha256:[0-9a-f]{64}$' - PreparedWorkHandoff: - type: object - additionalProperties: false - required: [boundary, handoff] - properties: - boundary: - $ref: "#/components/schemas/WorkSourceReceipt" - handoff: - $ref: "#/components/schemas/PreparedHandoff" - HandoffReceiptStatus: - type: string - enum: [accepted, needs_clarification, declined] - HandoffAcknowledgementSelection: - type: string - enum: [prepared, exact] - LiveStateCheckStatus: - type: string - enum: [confirmed, mismatch, not_checked] - ReceiverReadinessCheckStatus: - type: string - enum: [confirmed, insufficient, not_checked] - ReceiverChecks: - type: object - additionalProperties: false - description: Untrusted receiver self-attestation kept separate from citation availability. All three values must be confirmed when status is accepted. - required: [live_state, capability, authorization] - properties: - live_state: - $ref: "#/components/schemas/LiveStateCheckStatus" - capability: - $ref: "#/components/schemas/ReceiverReadinessCheckStatus" - authorization: - $ref: "#/components/schemas/ReceiverReadinessCheckStatus" - AcknowledgeHandoffRequest: - type: object - additionalProperties: false - required: [scope_id, source_id, receiver, status, selection] - properties: - scope_id: - type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - source_id: - type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - receiver: - type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - status: - $ref: "#/components/schemas/HandoffReceiptStatus" - selection: - $ref: "#/components/schemas/HandoffAcknowledgementSelection" - receiver_checks: - $ref: "#/components/schemas/ReceiverChecks" - nullable: true - prepared: - $ref: "#/components/schemas/PreparedHandoff" - nullable: true - revision: - $ref: "#/components/schemas/ArtifactReference" - nullable: true - message: - type: string - minLength: 1 - maxLength: 8192 - pattern: '.*\S.*' - nullable: true - HandoffAcknowledgement: - type: object - additionalProperties: false - required: [resolution, receipt] - properties: - resolution: - $ref: "#/components/schemas/HandoffResolution" - receipt: - $ref: "#/components/schemas/WorkSourceReceipt" - TaskOutcomeStatus: - type: string - enum: [succeeded, partial, blocked, failed, cancelled, unknown] - TaskCheckStatus: - type: string - enum: [passed, failed, skipped, timed_out, unavailable, cancelled, unknown] - TaskCheck: - type: object - additionalProperties: false - required: [name, status, basis, evidence] - properties: - name: - type: string - minLength: 1 - maxLength: 8192 - pattern: '.*\S.*' - status: - $ref: "#/components/schemas/TaskCheckStatus" - details: - type: string - minLength: 1 - maxLength: 8192 - pattern: '.*\S.*' - nullable: true - basis: - $ref: "#/components/schemas/WorkClaimBasis" - evidence: - type: array - maxItems: 32 - items: - $ref: "#/components/schemas/HandoffCitation" - TaskOutcome: - type: object - additionalProperties: false - required: [schema, trust, objective, status, summary, observations, checks, produced_artifacts, remaining_work] - properties: - schema: - type: string - enum: [powercontext.task-outcome.v1] - trust: - type: string - enum: [untrusted_observation] - objective: - type: string - minLength: 1 - maxLength: 8192 - pattern: '.*\S.*' - status: - $ref: "#/components/schemas/TaskOutcomeStatus" - summary: - type: string - minLength: 1 - maxLength: 8192 - pattern: '.*\S.*' - handoff_receipt_ref: - $ref: "#/components/schemas/SourceReference" - nullable: true - observations: - type: array - minItems: 1 - maxItems: 64 - items: - $ref: "#/components/schemas/WorkClaim" - checks: - type: array - maxItems: 64 - items: - $ref: "#/components/schemas/TaskCheck" - produced_artifacts: - type: array - maxItems: 32 - items: - $ref: "#/components/schemas/ArtifactReference" - remaining_work: - type: array - maxItems: 64 - items: - type: string - minLength: 1 - maxLength: 8192 - pattern: '.*\S.*' - RecordTaskOutcomeRequest: - type: object - additionalProperties: false - required: [scope_id, source_id, outcome] - properties: - scope_id: - type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - source_id: - type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - outcome: - $ref: "#/components/schemas/TaskOutcome" - CaptureContentSourceRequest: - type: object - additionalProperties: false - required: [scope_id, source_id, content] - properties: - scope_id: - type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - source_id: - type: string - minLength: 1 - maxLength: 256 - content: - type: string - minLength: 1 - maxLength: 200000 - metadata: - type: object - additionalProperties: true - nullable: true - CaptureContentSourceResponse: - type: object - additionalProperties: false - required: [status, source, position] - properties: - status: - $ref: "#/components/schemas/CaptureStatus" - source: - $ref: "#/components/schemas/SourceReference" - position: - type: integer - minimum: 1 - CommitHandoffRequest: - type: object - additionalProperties: false - required: [scope_id, handoff] - properties: - scope_id: - type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - handoff: - $ref: "#/components/schemas/PreparedHandoff" - CommittedHandoff: - type: object - additionalProperties: false - required: [reference, content, source_refs, artifact_refs] - properties: - reference: - $ref: "#/components/schemas/ArtifactReference" - content: - $ref: "#/components/schemas/HandoffContent" - source_refs: - type: array - items: - $ref: "#/components/schemas/SourceReference" - artifact_refs: - type: array - items: - $ref: "#/components/schemas/ArtifactReference" - ContinueHandoffRequest: - type: object - additionalProperties: false - required: [scope_id, selection] - properties: - scope_id: - type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - selection: - $ref: "#/components/schemas/HandoffSelection" - prepared: - $ref: "#/components/schemas/PreparedHandoff" - nullable: true - revision: - $ref: "#/components/schemas/ArtifactReference" - nullable: true - FinalizeHandoffRequest: - type: object - additionalProperties: false - required: [scope_id, draft] - properties: - scope_id: - type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - draft: - $ref: "#/components/schemas/HandoffDraft" - HandoffArtifactCitation: - type: object - additionalProperties: false - required: [kind, artifact_ref] - properties: - kind: - type: string - enum: [artifact] - artifact_ref: - $ref: "#/components/schemas/ArtifactReference" - HandoffActivation: - type: object - additionalProperties: false - required: [status, boundary_source, previous_position, current_position, draft] - properties: - status: - $ref: "#/components/schemas/HandoffActivationStatus" - boundary_source: - $ref: "#/components/schemas/SourceReference" - previous_position: - type: integer - minimum: 0 - current_position: - type: integer - minimum: 0 - draft: - $ref: "#/components/schemas/HandoffDraft" - nullable: true - HandoffCitation: - oneOf: - - $ref: "#/components/schemas/HandoffSourceCitation" - - $ref: "#/components/schemas/HandoffArtifactCitation" - - $ref: "#/components/schemas/HandoffMemoryCitation" - discriminator: - propertyName: kind - mapping: - source: "#/components/schemas/HandoffSourceCitation" - artifact: "#/components/schemas/HandoffArtifactCitation" - memory: "#/components/schemas/HandoffMemoryCitation" - HandoffContent: - type: object - additionalProperties: false - required: [schema, objective, state, disposition, next_action, omissions] - properties: - schema: - $ref: "#/components/schemas/HandoffSchema" - objective: - type: string - minLength: 1 - maxLength: 8192 - pattern: '.*\S.*' - state: - type: array - minItems: 1 - maxItems: 64 - items: - $ref: "#/components/schemas/HandoffStatement" - disposition: - $ref: "#/components/schemas/HandoffDisposition" - next_action: - $ref: "#/components/schemas/HandoffStatement" - nullable: true - omissions: - type: array - maxItems: 64 - items: - $ref: "#/components/schemas/HandoffOmission" - HandoffDraft: - type: object - additionalProperties: false - required: [objective, state, disposition, next_action, omissions] - properties: - objective: - type: string - minLength: 1 - maxLength: 8192 - pattern: '.*\S.*' - state: - type: array - minItems: 1 - maxItems: 64 - items: - $ref: "#/components/schemas/HandoffStatement" - disposition: - $ref: "#/components/schemas/HandoffDisposition" - next_action: - $ref: "#/components/schemas/HandoffStatement" - nullable: true - omissions: - type: array - maxItems: 64 - items: - $ref: "#/components/schemas/HandoffOmission" - HandoffEvidenceCheck: - type: object - additionalProperties: false - required: [claim, state_index, status, unavailable_evidence] - properties: - claim: - $ref: "#/components/schemas/HandoffClaim" - state_index: - type: integer - minimum: 0 - nullable: true - status: - $ref: "#/components/schemas/HandoffEvidenceStatus" - unavailable_evidence: - type: array - maxItems: 32 - items: - $ref: "#/components/schemas/HandoffCitation" - HandoffMemoryCitation: - type: object - additionalProperties: false - required: [kind, memory_citation] - properties: - kind: - type: string - enum: [memory] - memory_citation: - $ref: "#/components/schemas/MemoryCitation" - HandoffOmission: - type: object - additionalProperties: false - required: [text, citation] - properties: - text: - type: string - minLength: 1 - maxLength: 8192 - pattern: '.*\S.*' - citation: - $ref: "#/components/schemas/HandoffCitation" - nullable: true - HandoffResolution: - type: object - additionalProperties: false - required: - [trust, status, scope_id, content, selection, selected_revision, current_revision, evidence_checks] - properties: - trust: - type: string - enum: [untrusted_history] - status: - $ref: "#/components/schemas/HandoffResolutionStatus" - scope_id: - type: string - content: - $ref: "#/components/schemas/HandoffContent" - nullable: true - selection: - $ref: "#/components/schemas/HandoffSelection" - nullable: true - selected_revision: - $ref: "#/components/schemas/ArtifactReference" - nullable: true - current_revision: - $ref: "#/components/schemas/ArtifactReference" - nullable: true - evidence_checks: - type: array - maxItems: 65 - items: - $ref: "#/components/schemas/HandoffEvidenceCheck" - HandoffSourceCitation: - type: object - additionalProperties: false - required: [kind, source_ref] - properties: - kind: - type: string - enum: [source] - source_ref: - $ref: "#/components/schemas/SourceReference" - HandoffStatement: - type: object - additionalProperties: false - required: [text, citations] - properties: - text: - type: string - minLength: 1 - maxLength: 8192 - pattern: '.*\S.*' - citations: - type: array - minItems: 1 - maxItems: 32 - items: - $ref: "#/components/schemas/HandoffCitation" - PrepareHandoffRequest: - type: object - additionalProperties: false - required: [scope_id, objective, evidence] - properties: - scope_id: - type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - objective: - type: string - minLength: 1 - maxLength: 8192 - pattern: '.*\S.*' - evidence: - type: array - minItems: 1 - maxItems: 32 - items: - $ref: "#/components/schemas/HandoffCitation" - max_bytes: - type: integer - minimum: 512 - maximum: 32768 - default: 8000 - PreparedHandoff: - type: object - additionalProperties: false - required: [schema, scope_id, base, content] - properties: - schema: - $ref: "#/components/schemas/PreparedHandoffSchema" - scope_id: - type: string - base: - $ref: "#/components/schemas/ArtifactReference" - nullable: true - content: - $ref: "#/components/schemas/HandoffContent" - PreparedContext: - type: object - additionalProperties: false - required: [schema, status, content, content_bytes] - properties: - schema: - $ref: "#/components/schemas/PreparedContextSchema" - status: - $ref: "#/components/schemas/PreparedContextStatus" - content: - type: string - nullable: true - content_bytes: - type: integer - minimum: 0 - EntryChange: - type: object - additionalProperties: false - required: [op, entry_id, from_entry_version_id, to_entry_version_id, reason] - properties: - op: - $ref: "#/components/schemas/EntryChangeOperation" - entry_id: - type: string - minLength: 1 - maxLength: 128 - pattern: '^[\x21-\x7E]+$' - from_entry_version_id: - type: string - minLength: 1 - maxLength: 128 - pattern: '^[\x21-\x7E]+$' - nullable: true - to_entry_version_id: - type: string - minLength: 1 - maxLength: 128 - pattern: '^[\x21-\x7E]+$' - nullable: true - reason: - type: string - nullable: true - ExperienceArtifact: - type: object - additionalProperties: false - required: [artifact, content, source_refs, artifact_refs] - properties: - artifact: - $ref: "#/components/schemas/ArtifactReference" - content: - $ref: "#/components/schemas/ExperienceProposal" - source_refs: - type: array - items: - $ref: "#/components/schemas/SourceReference" - artifact_refs: - type: array - items: - $ref: "#/components/schemas/ArtifactReference" - ExperienceProposal: - type: object - additionalProperties: false - required: [situation, action, outcome, lesson] - properties: - situation: - type: string - minLength: 1 - maxLength: 8000 - pattern: '.*\S.*' - action: - type: string - minLength: 1 - maxLength: 8000 - pattern: '.*\S.*' - outcome: - type: string - minLength: 1 - maxLength: 8000 - pattern: '.*\S.*' - lesson: - type: string - minLength: 1 - maxLength: 8000 - pattern: '.*\S.*' - SkillArtifact: - type: object - additionalProperties: false - required: [artifact, content, source_refs, artifact_refs] - properties: - artifact: - $ref: "#/components/schemas/ArtifactReference" - content: - $ref: "#/components/schemas/SkillProposal" - source_refs: - type: array - items: - $ref: "#/components/schemas/SourceReference" - artifact_refs: - type: array - items: - $ref: "#/components/schemas/ArtifactReference" - SkillProposal: - type: object - additionalProperties: false - required: [name, description, instructions, validation] - properties: - name: - type: string - minLength: 1 - maxLength: 128 - pattern: '^\S(?:.*\S)?$' - description: - type: string - minLength: 1 - maxLength: 2000 - pattern: '^\S(?:.*\S)?$' - instructions: - type: string - minLength: 1 - maxLength: 32000 - pattern: '.*\S.*' - validation: - type: array - minItems: 1 - maxItems: 32 - items: - $ref: "#/components/schemas/SkillValidationItem" - SkillValidationItem: - type: string - minLength: 1 - maxLength: 2000 - pattern: '^\S(?:.*\S)?$' - ExternalSkillRegistration: - type: object - additionalProperties: false - required: - - external_skill_id - - provider - - agent_kind - - host_id - - installation_scope - - locator - - fingerprint - - name - - description - properties: - external_skill_id: - type: string - minLength: 1 - maxLength: 128 - pattern: '^[\x21-\x7E]+$' - provider: - type: string - enum: [codex, claude_code] - agent_kind: - type: string - enum: [codex, claude_code] - host_id: - type: string - minLength: 1 - maxLength: 128 - pattern: '^\S(?:.*\S)?$' - installation_scope: - $ref: "#/components/schemas/ExternalSkillInstallationScope" - locator: - type: string - minLength: 1 - maxLength: 2000 - pattern: '^\S(?:.*\S)?$' - description: Host-local locator; not a cross-Agent or cross-host contract. - fingerprint: - type: string - pattern: '^[0-9a-f]{64}$' - name: - type: string - minLength: 1 - maxLength: 128 - pattern: '^\S(?:.*\S)?$' - description: - type: string - minLength: 1 - maxLength: 2000 - pattern: '^\S(?:.*\S)?$' - ExternalSkillResolution: - type: object - additionalProperties: false - required: [registration, status, entrypoint] - properties: - registration: - $ref: "#/components/schemas/ExternalSkillRegistration" - status: - $ref: "#/components/schemas/ExternalSkillResolutionStatus" - entrypoint: - type: string - nullable: true - description: Host-local SKILL.md path; present only when the exact fingerprint is available. - ScanExternalSkillsResponse: - type: object - additionalProperties: false - required: [registrations, skipped] - properties: - registrations: - type: array - items: - $ref: "#/components/schemas/ExternalSkillRegistration" - skipped: - type: integer - minimum: 0 - ListExternalSkillsResponse: - type: object - additionalProperties: false - required: [skills] - properties: - skills: - type: array - items: - $ref: "#/components/schemas/ExternalSkillResolution" - ErrorDetail: - type: object - additionalProperties: false - required: [code, message, details] - properties: - code: - type: string - message: - type: string - details: - type: object - additionalProperties: true - nullable: true - ErrorResponse: - type: object - additionalProperties: false - required: [error] - properties: - error: - $ref: "#/components/schemas/ErrorDetail" - FlushMemoryRequest: - type: object - additionalProperties: false - required: [scope_id] - properties: - scope_id: - type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - FlushMemoryResponse: - type: object - additionalProperties: false - required: [status, previous_cursor, current_cursor, high_watermark, processed_source_count] - properties: - status: - $ref: "#/components/schemas/FlushStatus" - previous_cursor: - type: integer - minimum: 0 - current_cursor: - type: integer - minimum: 0 - high_watermark: - type: integer - minimum: 0 - processed_source_count: - type: integer - minimum: 0 - memory: - $ref: "#/components/schemas/ArtifactReference" - nullable: true - GetMemoryEntryRequest: - type: object - additionalProperties: false - required: [scope_id, citation] - properties: - scope_id: - type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - citation: - $ref: "#/components/schemas/MemoryCitation" - GetArtifactCandidateRequest: - type: object - additionalProperties: false - required: [scope_id, candidate_id] - properties: - scope_id: - type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - candidate_id: - type: string - minLength: 1 - maxLength: 128 - pattern: '^[\x21-\x7E]+$' - GetExperienceRequest: - type: object - additionalProperties: false - required: [scope_id, artifact] - properties: - scope_id: - type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - artifact: - $ref: "#/components/schemas/ArtifactReference" - GetSkillRequest: - type: object - additionalProperties: false - required: [scope_id, artifact] - properties: - scope_id: - type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - artifact: - $ref: "#/components/schemas/ArtifactReference" - CreateHandoffReportProjectRequest: - type: object - additionalProperties: false - required: [project_key, title] - properties: - project_key: - type: string - minLength: 1 - maxLength: 64 - title: - type: string - minLength: 1 - maxLength: 256 - description: - type: string - maxLength: 2000 - nullable: true - default_locale: - $ref: "#/components/schemas/ReportLocale" - default: zh-CN - timezone: - type: string - minLength: 1 - maxLength: 256 - default: UTC - ListHandoffReportProjectsRequest: - type: object - additionalProperties: false - properties: - cursor: - type: string - nullable: true - limit: - type: integer - minimum: 1 - maximum: 100 - default: 50 - include_archived: - type: boolean - default: false - GetHandoffReportProjectRequest: - type: object - additionalProperties: false - required: [project_id] - properties: - project_id: - type: string - minLength: 1 - maxLength: 256 - UpdateHandoffReportProjectRequest: - type: object - additionalProperties: false - required: [project, expected_version] - properties: - project: - $ref: "#/components/schemas/ProjectDescriptor" - expected_version: - type: integer - minimum: 1 - RegisterHandoffReportWorkstreamRequest: - type: object - additionalProperties: false - required: [project_id, scope_id, title, kind] - properties: - project_id: - type: string - minLength: 1 - maxLength: 256 - scope_id: - type: string - minLength: 1 - maxLength: 256 - key: - type: string - minLength: 1 - maxLength: 64 - nullable: true - title: - type: string - minLength: 1 - maxLength: 256 - kind: - $ref: "#/components/schemas/WorkstreamKind" - catalog_state: - $ref: "#/components/schemas/ReportCatalogState" - default: included - external_refs: - type: array - maxItems: 32 - items: - $ref: "#/components/schemas/HandoffReportExternalReference" - default: [] - labels: - type: array - maxItems: 32 - items: - type: string - minLength: 1 - maxLength: 128 - default: [] - ListHandoffReportWorkstreamsRequest: - type: object - additionalProperties: false - required: [project_id] - properties: - project_id: - type: string - minLength: 1 - maxLength: 256 - cursor: - type: string - nullable: true - limit: - type: integer - minimum: 1 - maximum: 100 - default: 50 - include_archived: - type: boolean - default: false - UpdateHandoffReportWorkstreamRequest: - type: object - additionalProperties: false - required: [workstream, expected_version] - properties: - workstream: - $ref: "#/components/schemas/WorkstreamDescriptor" - expected_version: - type: integer - minimum: 1 - GetHandoffReportRequest: - type: object - additionalProperties: false - required: [scope_id] - properties: - scope_id: - type: string - minLength: 1 - maxLength: 256 - project_id: - type: string - minLength: 1 - maxLength: 256 - nullable: true - deprecated: true - description: Retained for wire compatibility and ignored when generating a scope report. - locale: - $ref: "#/components/schemas/ReportLocale" - nullable: true - include_evidence_checks: - type: boolean - default: true - format: - $ref: "#/components/schemas/ReportFormat" - default: markdown - include_archived: - type: boolean - default: false - download: - type: boolean - default: false - period: - $ref: "#/components/schemas/HandoffReportPeriodRequest" - nullable: true - ListHandoffReportKnownScopesRequest: - type: object - additionalProperties: false - properties: - cursor: - type: string - nullable: true - limit: - type: integer - minimum: 1 - maximum: 100 - default: 50 - KnownHandoffScope: - type: object - additionalProperties: false - required: [scope_id] - properties: - scope_id: - type: string - minLength: 1 - maxLength: 256 - KnownHandoffScopePage: - type: object - additionalProperties: false - required: [items] - properties: - items: - type: array - items: - $ref: "#/components/schemas/KnownHandoffScope" - next_cursor: - type: string - nullable: true - HandoffReportPeriodRequest: - type: object - additionalProperties: false - required: [start, end] - properties: - start: - type: string - format: date-time - end: - type: string - format: date-time - timezone: - type: string - minLength: 1 - maxLength: 256 - nullable: true - compare_to_previous_period: - type: boolean - default: false - HandoffReportResponse: - type: object - additionalProperties: false - required: [format, report, markdown, selection_digest, report_digest] - properties: - format: - $ref: "#/components/schemas/ReportFormat" - report: - type: object - additionalProperties: true - nullable: true - markdown: - type: string - nullable: true - selection_digest: - type: string - pattern: '^sha256:[0-9a-f]{64}$' - report_digest: - type: string - pattern: '^sha256:[0-9a-f]{64}$' - ReportActivitySource: - type: string - enum: [handoff_observation, git_commit, git_worktree, coding_session, other] - ReportTimeBasis: - type: string - enum: [source_reported, host_observed, first_seen, current_only, unknown] - HandoffReportActivityAgent: - type: object - additionalProperties: false - properties: - provider: - type: string - minLength: 1 - maxLength: 64 - nullable: true - label: - type: string - minLength: 1 - maxLength: 128 - nullable: true - HandoffReportActivityVcsContext: - type: object - additionalProperties: false - properties: - branch: - type: string - minLength: 1 - maxLength: 256 - nullable: true - head_revision: - type: string - minLength: 1 - maxLength: 256 - nullable: true - RecordHandoffReportActivityRequest: - type: object - additionalProperties: false - required: [project_id, source, source_event_id, time_basis] - properties: - project_id: - type: string - minLength: 1 - maxLength: 256 - scope_id: - type: string - minLength: 1 - maxLength: 256 - nullable: true - source: - $ref: "#/components/schemas/ReportActivitySource" - source_event_id: - type: string - minLength: 1 - maxLength: 256 - source_ref: - $ref: "#/components/schemas/HandoffReportExternalReference" - nullable: true - occurred_at: - type: string - format: date-time - nullable: true - time_basis: - $ref: "#/components/schemas/ReportTimeBasis" - title: - type: string - minLength: 1 - maxLength: 256 - nullable: true - summary: - type: string - minLength: 1 - maxLength: 2000 - nullable: true - agent: - $ref: "#/components/schemas/HandoffReportActivityAgent" - nullable: true - session_id: - type: string - minLength: 1 - maxLength: 256 - nullable: true - vcs_context: - $ref: "#/components/schemas/HandoffReportActivityVcsContext" - nullable: true - evidence_refs: - type: array - maxItems: 32 - items: - $ref: "#/components/schemas/HandoffReportExternalReference" - default: [] - HandoffReportActivity: - type: object - additionalProperties: false - required: [schema, event_id, project_id, scope_id, source, source_event_id, source_ref, occurred_at, observed_at, time_basis, title, summary, agent, session_id, vcs_context, evidence_refs, trust] - properties: - schema: - type: string - enum: [powercontext.handoff-report-activity.v1] - event_id: - type: string - minLength: 1 - maxLength: 256 - project_id: - type: string - minLength: 1 - maxLength: 256 - scope_id: - type: string - minLength: 1 - maxLength: 256 - nullable: true - source: - $ref: "#/components/schemas/ReportActivitySource" - source_event_id: - type: string - minLength: 1 - maxLength: 256 - source_ref: - $ref: "#/components/schemas/HandoffReportExternalReference" - nullable: true - occurred_at: - type: string - format: date-time - nullable: true - observed_at: - type: string - format: date-time - time_basis: - $ref: "#/components/schemas/ReportTimeBasis" - title: - type: string - minLength: 1 - maxLength: 256 - nullable: true - summary: - type: string - minLength: 1 - maxLength: 2000 - nullable: true - agent: - $ref: "#/components/schemas/HandoffReportActivityAgent" - nullable: true - session_id: - type: string - minLength: 1 - maxLength: 256 - nullable: true - vcs_context: - $ref: "#/components/schemas/HandoffReportActivityVcsContext" - nullable: true - evidence_refs: - type: array - maxItems: 32 - items: - $ref: "#/components/schemas/HandoffReportExternalReference" - trust: - type: string - enum: [untrusted_observation] - StoredHandoffReportActivity: - type: object - additionalProperties: false - required: [cursor, event] - properties: - cursor: - type: integer - minimum: 1 - event: - $ref: "#/components/schemas/HandoffReportActivity" - ListHandoffReportActivitiesRequest: - type: object - additionalProperties: false - required: [project_id] - properties: - project_id: - type: string - minLength: 1 - maxLength: 256 - period_start: - type: string - format: date-time - nullable: true - period_end: - type: string - format: date-time - nullable: true - sources: - type: array - maxItems: 5 - items: - $ref: "#/components/schemas/ReportActivitySource" - nullable: true - after_cursor: - type: integer - minimum: 0 - default: 0 - through_cursor: - type: integer - minimum: 0 - nullable: true - limit: - type: integer - minimum: 1 - maximum: 100 - default: 50 - HandoffReportActivityPage: - type: object - additionalProperties: false - required: [items, next_cursor, high_watermark] - properties: - items: - type: array - maxItems: 100 - items: - $ref: "#/components/schemas/HandoffReportActivity" - next_cursor: - type: integer - minimum: 1 - nullable: true - high_watermark: - type: integer - minimum: 0 - PurgeHandoffReportActivitiesRequest: - type: object - additionalProperties: false - required: [project_id, observed_before] - properties: - project_id: - type: string - minLength: 1 - maxLength: 256 - observed_before: - type: string - format: date-time - PurgeHandoffReportActivitiesResponse: - type: object - additionalProperties: false - required: [deleted_count] - properties: - deleted_count: - type: integer - minimum: 0 - HandoffReportRepositoryRef: - type: object - additionalProperties: false - required: [provider, repository_id, normalized_remote, subpath] - properties: - provider: - type: string - enum: [github, gitlab, local, other] - repository_id: - type: string - minLength: 1 - maxLength: 256 - nullable: true - normalized_remote: - type: string - minLength: 1 - maxLength: 2048 - nullable: true - subpath: - type: string - minLength: 1 - maxLength: 1024 - nullable: true - HandoffReportWorkspaceBinding: - type: object - additionalProperties: false - required: [schema, workspace_instance_id, project_id, repository_ref, state, confirmed_at, version] - properties: - schema: - type: string - enum: [powercontext.workspace-binding.v1] - workspace_instance_id: - type: string - minLength: 1 - maxLength: 256 - project_id: - type: string - minLength: 1 - maxLength: 256 - repository_ref: - $ref: "#/components/schemas/HandoffReportRepositoryRef" - state: - type: string - enum: [confirmed, detached] - confirmed_at: - type: string - format: date-time - version: - type: integer - minimum: 1 - GetHandoffReportWorkspaceRequest: - type: object - additionalProperties: false - required: [workspace_instance_id] - properties: - workspace_instance_id: - type: string - minLength: 1 - maxLength: 256 - AttachHandoffReportWorkspaceRequest: - type: object - additionalProperties: false - required: [workspace_instance_id, project_id, repository_ref, expected_version] - properties: - workspace_instance_id: - type: string - minLength: 1 - maxLength: 256 - project_id: - type: string - minLength: 1 - maxLength: 256 - repository_ref: - $ref: "#/components/schemas/HandoffReportRepositoryRef" - expected_version: - type: integer - minimum: 1 - nullable: true - DetachHandoffReportWorkspaceRequest: - type: object - additionalProperties: false - required: [workspace_instance_id, expected_version] - properties: - workspace_instance_id: - type: string - minLength: 1 - maxLength: 256 - expected_version: - type: integer - minimum: 1 - ProjectDescriptor: - type: object - additionalProperties: false - required: [schema, project_id, project_key, title, description, default_locale, timezone, catalog_state, version] - properties: - schema: - type: string - enum: [powercontext.project.v1] - project_id: - type: string - minLength: 1 - maxLength: 256 - project_key: - type: string - minLength: 1 - maxLength: 64 - title: - type: string - minLength: 1 - maxLength: 256 - description: - type: string - maxLength: 2000 - nullable: true - default_locale: - $ref: "#/components/schemas/ReportLocale" - timezone: - type: string - minLength: 1 - maxLength: 256 - catalog_state: - $ref: "#/components/schemas/ReportCatalogState" - version: - type: integer - minimum: 1 - ProjectPage: - type: object - additionalProperties: false - required: [items, next_cursor] - properties: - items: - type: array - maxItems: 100 - items: - $ref: "#/components/schemas/ProjectDescriptor" - next_cursor: - type: string - nullable: true - WorkstreamDescriptor: - type: object - additionalProperties: false - required: [schema, scope_id, project_id, key, title, kind, catalog_state, external_refs, labels, version] - properties: - schema: - type: string - enum: [powercontext.workstream.v1] - scope_id: - type: string - minLength: 1 - maxLength: 256 - project_id: - type: string - minLength: 1 - maxLength: 256 - key: - type: string - maxLength: 64 - nullable: true - title: - type: string - minLength: 1 - maxLength: 256 - kind: - $ref: "#/components/schemas/WorkstreamKind" - catalog_state: - $ref: "#/components/schemas/ReportCatalogState" - external_refs: - type: array - maxItems: 32 - items: - $ref: "#/components/schemas/HandoffReportExternalReference" - labels: - type: array - maxItems: 32 - items: - type: string - minLength: 1 - maxLength: 128 - version: - type: integer - minimum: 1 - WorkstreamPage: - type: object - additionalProperties: false - required: [items, next_cursor] - properties: - items: - type: array - maxItems: 100 - items: - $ref: "#/components/schemas/WorkstreamDescriptor" - next_cursor: - type: string - nullable: true - HandoffReportExternalReference: - type: object - additionalProperties: false - required: [kind, provider, external_id, url] - properties: - kind: - type: string - enum: [issue, task, pull_request, branch, feature, release, program, other] - provider: - type: string - minLength: 1 - maxLength: 64 - external_id: - type: string - minLength: 1 - maxLength: 256 - url: - type: string - maxLength: 2048 - nullable: true - ReportLocale: - type: string - enum: [zh-CN, en] - ReportFormat: - type: string - enum: [json, markdown] - ReportCatalogState: - type: string - enum: [included, archived] - WorkstreamKind: - type: string - enum: [feature, bug, refactor, operations, research, other] - HealthResponse: - type: object - additionalProperties: false - required: [status] - properties: - status: - type: string - ListMemoryChangesRequest: - type: object - additionalProperties: false - required: [scope_id] - properties: - scope_id: - type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - since_revision: - type: integer - minimum: 0 - nullable: true - description: >- - Exclusive lower bound; 0 requests complete history from Revision 1. - Positive nonexistent revisions are errors. - ListMemoryChangesResponse: - type: object - additionalProperties: false - required: [revisions] - properties: - memory: - $ref: "#/components/schemas/ArtifactReference" - nullable: true - revisions: - type: array - items: - $ref: "#/components/schemas/MemoryRevisionChanges" - ListMemoryEntriesRequest: - type: object - additionalProperties: false - required: [scope_id] - properties: - scope_id: - type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - include_inactive: - type: boolean - default: false - description: Include inactive entries from the current Memory head for explicit audit. - ListMemoryEntriesResponse: - type: object - additionalProperties: false - required: [entries] - properties: - memory: - $ref: "#/components/schemas/ArtifactReference" - nullable: true - entries: - type: array - items: - $ref: "#/components/schemas/MemoryEntry" - ListArtifactCandidatesRequest: - type: object - additionalProperties: false - required: [scope_id] - properties: - scope_id: - type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - status: - $ref: "#/components/schemas/CandidateStatus" - default: pending - family: - $ref: "#/components/schemas/CandidateFamily" - nullable: true - cursor: - type: string - minLength: 1 - maxLength: 128 - nullable: true - limit: - type: integer - minimum: 1 - maximum: 100 - default: 50 - ListExternalSkillsRequest: - type: object - additionalProperties: false - required: [scope_id] - properties: - scope_id: - type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - include_unavailable: - type: boolean - default: false - MemoryEntry: - type: object - additionalProperties: false - required: - - citation - - version - - kind - - text - - state - - source_refs - - artifact_refs - properties: - citation: - $ref: "#/components/schemas/MemoryCitation" - version: - type: integer - minimum: 1 - kind: - type: string - text: - type: string - state: - $ref: "#/components/schemas/MemoryEntryState" - source_refs: - type: array - items: - $ref: "#/components/schemas/SourceReference" - artifact_refs: - type: array - items: - $ref: "#/components/schemas/ArtifactReference" - MemoryMutationResponse: - type: object - additionalProperties: false - required: [memory] - properties: - memory: - $ref: "#/components/schemas/ArtifactReference" - entry: - $ref: "#/components/schemas/MemoryEntry" - nullable: true - MemoryCitation: - type: object - additionalProperties: false - required: [memory_ref, entry_id, entry_version_id] - properties: - memory_ref: - $ref: "#/components/schemas/ArtifactReference" - entry_id: - type: string - minLength: 1 - maxLength: 128 - pattern: '^[\x21-\x7E]+$' - entry_version_id: - type: string - minLength: 1 - maxLength: 128 - pattern: '^[\x21-\x7E]+$' - MemoryRevisionChanges: - type: object - additionalProperties: false - required: [memory_ref, changes] - properties: - memory_ref: - $ref: "#/components/schemas/ArtifactReference" - changes: - type: array - items: - $ref: "#/components/schemas/EntryChange" - PrepareContextRequest: - type: object - additionalProperties: false - required: [scope_id, query] - properties: - scope_id: - type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - query: - type: string - minLength: 1 - maxLength: 8192 - pattern: '.*\S.*' - max_bytes: - type: integer - minimum: 512 - maximum: 32768 - default: 8000 - ProposeExperienceRequest: - type: object - additionalProperties: false - required: [scope_id, proposal, source_refs, artifact_refs] - properties: - scope_id: - type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - proposal: - $ref: "#/components/schemas/ExperienceProposal" - source_refs: - type: array - maxItems: 32 - description: Exact Source evidence. Counted with artifact_refs toward a combined maximum of 32 references. - items: - $ref: "#/components/schemas/SourceReference" - artifact_refs: - type: array - maxItems: 32 - description: Exact Artifact evidence. Counted with source_refs toward a combined maximum of 32 references. - items: - $ref: "#/components/schemas/ArtifactReference" - target: - $ref: "#/components/schemas/ArtifactReference" - nullable: true - reason: - type: string - minLength: 1 - maxLength: 2000 - nullable: true - GenerateExperienceRequest: - type: object - additionalProperties: false - required: [scope_id, source_refs, artifact_refs] - properties: - scope_id: - type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - source_refs: - type: array - maxItems: 32 - description: Exact Source evidence. Counted with artifact_refs toward a combined maximum of 32 references. - items: - $ref: "#/components/schemas/SourceReference" - artifact_refs: - type: array - maxItems: 32 - description: Exact Artifact evidence. Counted with source_refs toward a combined maximum of 32 references. - items: - $ref: "#/components/schemas/ArtifactReference" - target: - $ref: "#/components/schemas/ArtifactReference" - nullable: true - reason: - type: string - minLength: 1 - maxLength: 2000 - nullable: true - ProposeSkillRequest: - type: object - additionalProperties: false - required: [scope_id, proposal, source_refs, artifact_refs] - properties: - scope_id: - type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - proposal: - $ref: "#/components/schemas/SkillProposal" - source_refs: - type: array - maxItems: 32 - description: Exact Source evidence. Counted with artifact_refs toward a combined maximum of 32 references. - items: - $ref: "#/components/schemas/SourceReference" - artifact_refs: - type: array - maxItems: 32 - description: Exact Artifact evidence. Counted with source_refs toward a combined maximum of 32 references. - items: - $ref: "#/components/schemas/ArtifactReference" - target: - $ref: "#/components/schemas/ArtifactReference" - nullable: true - reason: - type: string - minLength: 1 - maxLength: 2000 - nullable: true - SkillGenerationOrigin: - type: string - enum: [experience, source, usage] - description: The operation-specific direct provenance shape required for managed Skill generation. - GenerateSkillRequest: - type: object - additionalProperties: false - required: [scope_id, origin, source_refs, artifact_refs] - properties: - scope_id: - type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - origin: - $ref: "#/components/schemas/SkillGenerationOrigin" - source_refs: - type: array - maxItems: 32 - description: Exact Source evidence. Counted with artifact_refs toward a combined maximum of 32 references. - items: - $ref: "#/components/schemas/SourceReference" - artifact_refs: - type: array - maxItems: 32 - description: Exact Artifact evidence. Counted with source_refs toward a combined maximum of 32 references. - items: - $ref: "#/components/schemas/ArtifactReference" - target: - $ref: "#/components/schemas/ArtifactReference" - nullable: true - reason: - type: string - minLength: 1 - maxLength: 2000 - nullable: true - GeneratedCandidateStatus: - type: string - enum: [pending, no_op] - GeneratedCandidateResponse: - type: object - additionalProperties: false - required: [status, candidate] - properties: - status: - $ref: "#/components/schemas/GeneratedCandidateStatus" - candidate: - $ref: "#/components/schemas/ArtifactCandidate" - nullable: true - ReadinessResponse: - type: object - additionalProperties: false - required: [status, checks] - properties: - status: - $ref: "#/components/schemas/ReadinessStatus" - checks: - type: object - additionalProperties: - type: string - ReadinessStatus: - type: string - enum: [ready, degraded, not_ready] - RememberMemoryRequest: - type: object - additionalProperties: false - required: [scope_id, kind, text] - properties: - scope_id: - type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - kind: - type: string - minLength: 1 - maxLength: 128 - text: - type: string - minLength: 1 - description: Must not exceed 8192 UTF-8 bytes after normalization. - reason: - type: string - maxLength: 512 - nullable: true - expected_revision: - type: integer - minimum: 1 - nullable: true - RetireMemoryEntryRequest: - type: object - additionalProperties: false - required: [scope_id, citation] - properties: - scope_id: - type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - citation: - $ref: "#/components/schemas/MemoryCitation" - reason: - type: string - maxLength: 512 - nullable: true - RejectArtifactCandidateRequest: - type: object - additionalProperties: false - required: [scope_id, candidate_id, expected_version, reason] - properties: - scope_id: - type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - candidate_id: - type: string - minLength: 1 - maxLength: 128 - pattern: '^[\x21-\x7E]+$' - expected_version: - type: integer - minimum: 1 - reason: - type: string - minLength: 1 - maxLength: 2000 - pattern: '.*\S.*' - ReviseArtifactCandidateRequest: - type: object - additionalProperties: false - required: [scope_id, candidate_id, expected_version, proposal, source_refs, artifact_refs] - properties: - scope_id: - type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - candidate_id: - type: string - minLength: 1 - maxLength: 128 - pattern: '^[\x21-\x7E]+$' - expected_version: - type: integer - minimum: 1 - proposal: - oneOf: - - $ref: "#/components/schemas/ExperienceProposal" - - $ref: "#/components/schemas/SkillProposal" - source_refs: - type: array - maxItems: 32 - description: Exact Source evidence. Counted with artifact_refs toward a combined maximum of 32 references. - items: - $ref: "#/components/schemas/SourceReference" - artifact_refs: - type: array - maxItems: 32 - description: Exact Artifact evidence. Counted with source_refs toward a combined maximum of 32 references. - items: - $ref: "#/components/schemas/ArtifactReference" - target: - $ref: "#/components/schemas/ArtifactReference" - nullable: true - reason: - type: string - minLength: 1 - maxLength: 2000 - nullable: true - ReviseMemoryEntryRequest: - type: object - additionalProperties: false - required: [scope_id, citation, kind, text] - properties: - scope_id: - type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - citation: - $ref: "#/components/schemas/MemoryCitation" - kind: - type: string - minLength: 1 - maxLength: 128 - text: - type: string - minLength: 1 - description: Must not exceed 8192 UTF-8 bytes after normalization. - reason: - type: string - maxLength: 512 - nullable: true - SearchMemoryHit: - type: object - additionalProperties: false - required: [citation, text, score, matched_by] - properties: - citation: - $ref: "#/components/schemas/MemoryCitation" - text: - type: string - score: - type: number - minimum: 0 - maximum: 1 - matched_by: - type: array - items: - $ref: "#/components/schemas/MemoryMatchedBy" - SearchMemoryRequest: - type: object - additionalProperties: false - required: [scope_id, query] - properties: - scope_id: - type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - query: - type: string - minLength: 1 - maxLength: 8192 - limit: - type: integer - minimum: 1 - maximum: 50 - default: 10 - mode: - $ref: "#/components/schemas/MemorySearchMode" - default: auto - ScanExternalSkillsRequest: - type: object - additionalProperties: false - required: [scope_id] - properties: - scope_id: - type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - ResolveExternalSkillRequest: - type: object - additionalProperties: false - required: [scope_id, external_skill_id, fingerprint] - properties: - scope_id: - type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - external_skill_id: - type: string - minLength: 1 - maxLength: 128 - pattern: '^[\x21-\x7E]+$' - fingerprint: - type: string - pattern: '^[0-9a-f]{64}$' - ExternalSkillImportMode: - type: string - enum: [import, fork] - ImportExternalSkillRequest: - type: object - additionalProperties: false - required: [scope_id, external_skill_id, fingerprint, mode] - properties: - scope_id: - type: string - minLength: 1 - maxLength: 256 - pattern: '.*\S.*' - external_skill_id: - type: string - minLength: 1 - maxLength: 128 - pattern: '^[\x21-\x7E]+$' - fingerprint: - type: string - pattern: '^[0-9a-f]{64}$' - description: Exact package fingerprint captured into Source lineage. - mode: - $ref: "#/components/schemas/ExternalSkillImportMode" - reason: - type: string - minLength: 1 - maxLength: 2000 - nullable: true - SearchMemoryResponse: - type: object - additionalProperties: false - required: [hits] - properties: - memory: - $ref: "#/components/schemas/ArtifactReference" - nullable: true - mode: - $ref: "#/components/schemas/MemoryUsedSearchMode" - nullable: true - hits: - type: array - items: - $ref: "#/components/schemas/SearchMemoryHit" - SourceReference: - type: object - additionalProperties: false - required: [name, source_id] - properties: - name: - type: string - description: Stable Source type. - source_id: - type: string - CaptureStatus: - type: string - enum: [accepted] - StatsPeriod: - type: string - enum: [today, 7d, 30d] - CandidateFamily: - type: string - enum: [experience, skill] - ExternalSkillInstallationScope: - type: string - enum: [user, project, plugin] - ExternalSkillResolutionStatus: - type: string - enum: [available, unavailable] - CandidateStatus: - type: string - enum: [pending, approved, rejected] - PreparedContextSchema: - type: string - enum: [powercontext.prepared-context.v1] - PreparedContextStatus: - type: string - enum: [ready, empty] - EntryChangeOperation: - type: string - enum: [add, revise, deactivate, reactivate] - FlushStatus: - type: string - enum: [idle, processed] - MemoryEntryState: - type: string - enum: [active, inactive] - MemoryMatchedBy: - type: string - enum: [fts, vector] - MemorySearchMode: - type: string - enum: [auto, fts, vector, hybrid] - MemoryUsedSearchMode: - type: string - enum: [fts, vector, hybrid] - HandoffClaim: - type: string - enum: [state, next_action] - HandoffActivationStatus: - type: string - enum: [generated, ignored] - HandoffDisposition: - type: string - enum: [continuable, blocked, complete] - HandoffEvidenceStatus: - type: string - enum: [available, unavailable] - HandoffResolutionStatus: - type: string - enum: [empty, resolved] - HandoffSchema: - type: string - enum: [powercontext.handoff.v1] - HandoffSelection: - type: string - enum: [prepared, exact, latest] - PreparedHandoffSchema: - type: string - enum: [powercontext.prepared-handoff.v1] diff --git a/integrations/dsh/plugins/powercontext/package.json b/integrations/dsh/plugins/powercontext/package.json index 2f9106225..47de3ff45 100644 --- a/integrations/dsh/plugins/powercontext/package.json +++ b/integrations/dsh/plugins/powercontext/package.json @@ -31,10 +31,7 @@ } }, "scripts": { - "sync:openapi": "node scripts/sync-openapi.mjs", - "gen": "node scripts/gen-operations.mjs", - "gen:check": "node scripts/gen-operations.mjs --check", - "build": "node scripts/gen-operations.mjs && tsdown && node scripts/normalize-build-output.mjs", + "build": "tsdown && node scripts/normalize-build-output.mjs", "prepare": "node scripts/prepare.mjs", "test": "vitest run --exclude=tests/e2e/**", "test:e2e": "vitest run tests/e2e", @@ -86,8 +83,7 @@ "@types/node": "^24.3.0", "tsdown": "^0.16.2", "typescript": "^5.9.2", - "vitest": "^3.2.4", - "yaml": "^2.9.0" + "vitest": "^3.2.4" }, "engines": { "node": ">=20" diff --git a/integrations/dsh/plugins/powercontext/pnpm-lock.yaml b/integrations/dsh/plugins/powercontext/pnpm-lock.yaml index d4785028e..f31e21334 100644 --- a/integrations/dsh/plugins/powercontext/pnpm-lock.yaml +++ b/integrations/dsh/plugins/powercontext/pnpm-lock.yaml @@ -1,17 +1,3 @@ -# Copyright (c) 2026 OceanBase. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - lockfileVersion: '9.0' settings: @@ -36,10 +22,7 @@ importers: version: 5.9.3 vitest: specifier: ^3.2.4 - version: 3.2.7(@types/node@24.13.3)(yaml@2.9.0) - yaml: - specifier: ^2.9.0 - version: 2.9.0 + version: 3.2.7(@types/node@24.13.3) packages: @@ -262,7 +245,6 @@ packages: engines: {node: ^22.20 || ^24.12 || >=25} cpu: [x64] os: [linux] - libc: [glibc] '@napi-rs/wasm-runtime@1.2.3': resolution: {integrity: sha512-UMduMbqO5s5zF2NkNacMT/yK5Y5QiKvWr2+50bzIIxFDwVJ2h49b+oyjaCGPhJxd2/gC2x39EHv/gHVuu36x2Q==} @@ -345,70 +327,60 @@ packages: engines: {node: ^20.19.0 || >=22.12.0} cpu: [arm64] os: [linux] - libc: [glibc] '@rolldown/binding-linux-arm64-gnu@1.0.0-rc.17': resolution: {integrity: sha512-e6usGaHKW5BMNZOymS1UcEYGowQMWcgZ71Z17Sl/h2+ZziNJ1a9n3Zvcz6LdRyIW5572wBCTH/Z+bKuZouGk9Q==} engines: {node: ^20.19.0 || >=22.12.0} cpu: [arm64] os: [linux] - libc: [glibc] '@rolldown/binding-linux-arm64-musl@1.0.0-beta.52': resolution: {integrity: sha512-ENLmSQCWqSA/+YN45V2FqTIemg7QspaiTjlm327eUAMeOLdqmSOVVyrQexJGNTQ5M8sDYCgVAig2Kk01Ggmqaw==} engines: {node: ^20.19.0 || >=22.12.0} cpu: [arm64] os: [linux] - libc: [musl] '@rolldown/binding-linux-arm64-musl@1.0.0-rc.17': resolution: {integrity: sha512-b/CgbwAJpmrRLp02RPfhbudf5tZnN9nsPWK82znefso832etkem8H7FSZwxrOI9djcdTP7U6YfNhbRnh7djErg==} engines: {node: ^20.19.0 || >=22.12.0} cpu: [arm64] os: [linux] - libc: [musl] '@rolldown/binding-linux-ppc64-gnu@1.0.0-rc.17': resolution: {integrity: sha512-4EII1iNGRUN5WwGbF/kOh/EIkoDN9HsupgLQoXfY+D1oyJm7/F4t5PYU5n8SWZgG0FEwakyM8pGgwcBYruGTlA==} engines: {node: ^20.19.0 || >=22.12.0} cpu: [ppc64] os: [linux] - libc: [glibc] '@rolldown/binding-linux-s390x-gnu@1.0.0-rc.17': resolution: {integrity: sha512-AH8oq3XqQo4IibpVXvPeLDI5pzkpYn0WiZAfT05kFzoJ6tQNzwRdDYQ45M8I/gslbodRZwW8uxLhbSBbkv96rA==} engines: {node: ^20.19.0 || >=22.12.0} cpu: [s390x] os: [linux] - libc: [glibc] '@rolldown/binding-linux-x64-gnu@1.0.0-beta.52': resolution: {integrity: sha512-klahlb2EIFltSUubn/VLjuc3qxp1E7th8ukayPfdkcKvvYcQ5rJztgx8JsJSuAKVzKtNTqUGOhy4On71BuyV8g==} engines: {node: ^20.19.0 || >=22.12.0} cpu: [x64] os: [linux] - libc: [glibc] '@rolldown/binding-linux-x64-gnu@1.0.0-rc.17': resolution: {integrity: sha512-cLnjV3xfo7KslbU41Z7z8BH/E1y5mzUYzAqih1d1MDaIGZRCMqTijqLv76/P7fyHuvUcfGsIpqCdddbxLLK9rA==} engines: {node: ^20.19.0 || >=22.12.0} cpu: [x64] os: [linux] - libc: [glibc] '@rolldown/binding-linux-x64-musl@1.0.0-beta.52': resolution: {integrity: sha512-UuA+JqQIgqtkgGN2c/AQ5wi8M6mJHrahz/wciENPTeI6zEIbbLGoth5XN+sQe2pJDejEVofN9aOAp0kaazwnVg==} engines: {node: ^20.19.0 || >=22.12.0} cpu: [x64] os: [linux] - libc: [musl] '@rolldown/binding-linux-x64-musl@1.0.0-rc.17': resolution: {integrity: sha512-0phclDw1spsL7dUB37sIARuis2tAgomCJXAHZlpt8PXZ4Ba0dRP1e+66lsRqrfhISeN9bEGNjQs+T/Fbd7oYGw==} engines: {node: ^20.19.0 || >=22.12.0} cpu: [x64] os: [linux] - libc: [musl] '@rolldown/binding-openharmony-arm64@1.0.0-beta.52': resolution: {integrity: sha512-1BNQW8u4ro8bsN1+tgKENJiqmvc+WfuaUhXzMImOVSMw28pkBKdfZtX2qJPADV3terx+vNJtlsgSGeb3+W6Jiw==} @@ -502,79 +474,66 @@ packages: resolution: {integrity: sha512-81wiiX3v7aqy+T+bT61TJ78yJjRquqFFTTbAPt08imfQQzkPIW8t6aJbkTagtCCrXMNc9D66+geqlK7ydLPNqA==} cpu: [arm] os: [linux] - libc: [glibc] '@rollup/rollup-linux-arm-musleabihf@4.62.4': resolution: {integrity: sha512-9kmDIvNZqdoHOBZgNtpTBeLWYO/LVipM3H/j62P8848/l/VPEQL6N3uxU9pvP1oZAsXyC2MEnFP3ovRjo7WYNQ==} cpu: [arm] os: [linux] - libc: [musl] '@rollup/rollup-linux-arm64-gnu@4.62.4': resolution: {integrity: sha512-CcnXHWnXg69g+DX5VWL3FHts3qMRN2uVEHX+BZvGLdd07/gXkn3ePjYtO1LDJvxkGKVHMclKBRa1QUTH+6toYQ==} cpu: [arm64] os: [linux] - libc: [glibc] '@rollup/rollup-linux-arm64-musl@4.62.4': resolution: {integrity: sha512-iFOibiHnTRuhrWLlRsOQFdZJJIa7S8OwkneJr4ocALP16u5yk6lWLINFwhHaEqBFMsKDUZofLkGos7+CPzGB3g==} cpu: [arm64] os: [linux] - libc: [musl] '@rollup/rollup-linux-loong64-gnu@4.62.4': resolution: {integrity: sha512-XnWYMI7euHlb5a871xPja+Gm7DRCFU+FGRrtS2sMq9N8FvqtpagUy6gD4YOemC5MRk9xbh8+jYMEJbigFQwsgA==} cpu: [loong64] os: [linux] - libc: [glibc] '@rollup/rollup-linux-loong64-musl@4.62.4': resolution: {integrity: sha512-qGDAlO0U8xedCcsdRm9oaoQY8DAx/QT7uIxJWhCdx0ceIWX783UC9QSYkdpzAe29wNiVfp24+bZdQmn49o45SQ==} cpu: [loong64] os: [linux] - libc: [musl] '@rollup/rollup-linux-ppc64-gnu@4.62.4': resolution: {integrity: sha512-ru4H6ezD7ysA5EiEK6qkkaEb4modH8CTej6kUy/gQi20u3kB3G7Zn8snXXkeJSCOFKG/rbPPtM/+9Wgas1961w==} cpu: [ppc64] os: [linux] - libc: [glibc] '@rollup/rollup-linux-ppc64-musl@4.62.4': resolution: {integrity: sha512-2W4MO5WQVJnbJaZdvDb9rhBDuFU1nKIepPFpJUBsTh2k1YY2g+ODViaWuyOAjQ5cOP7NvrvLzt3wvHOoiAvc7w==} cpu: [ppc64] os: [linux] - libc: [musl] '@rollup/rollup-linux-riscv64-gnu@4.62.4': resolution: {integrity: sha512-+fxjfuoAmVMCYV5QyjoIpu0cp5DOiOTeqYFk1AVaxGr+/ravWLX89XfQmptsoWcaVy/TGf2hexzbUOrCQIL1CQ==} cpu: [riscv64] os: [linux] - libc: [glibc] '@rollup/rollup-linux-riscv64-musl@4.62.4': resolution: {integrity: sha512-jTn8JfHGL4djjFxPuM06LmNUJDsst2jeVlsd9OmIH6zc5sC9K6rIuO4YajXatLUpBmBKl6b35ro1QZocLi+tcA==} cpu: [riscv64] os: [linux] - libc: [musl] '@rollup/rollup-linux-s390x-gnu@4.62.4': resolution: {integrity: sha512-oCJCJL4pXsoDcP2QZ+JVlPTIRc6266zsIaeJJsWImmF7HO0W8nb6HuSgZlMWxJwaPf8ehbSw8yo0EUw925hKsA==} cpu: [s390x] os: [linux] - libc: [glibc] '@rollup/rollup-linux-x64-gnu@4.62.4': resolution: {integrity: sha512-W69hukhZ3KKNRCaMIEzKvcFye42hh0FE1+YoYaf5+Ikacuftoco6yO/xouz0hc5d5W/s3yBro5jRiuEE/Q5vUw==} cpu: [x64] os: [linux] - libc: [glibc] '@rollup/rollup-linux-x64-musl@4.62.4': resolution: {integrity: sha512-qiXbGG2jkjXhzXpsFZSR2Xpb8DN/UaxYsbb/STbuR/6fpaDgRmmaq1B/LmtF2wQFOFOSsK2jdE0RZ3a0zHn4QA==} cpu: [x64] os: [linux] - libc: [musl] '@rollup/rollup-openbsd-x64@4.62.4': resolution: {integrity: sha512-nWeM//hxv8mIo6jD7Hu4o48DVmV9pbV6gsKaWU+4NFyqHoPKwrkRiZGLKUhOBk8qNmDmpwFtPKg80Bo/Tn4xiQ==} @@ -1015,11 +974,6 @@ packages: engines: {node: '>=8'} hasBin: true - yaml@2.9.0: - resolution: {integrity: sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==} - engines: {node: '>= 14.6'} - hasBin: true - snapshots: '@babel/generator@7.29.8': @@ -1379,13 +1333,13 @@ snapshots: chai: 5.3.3 tinyrainbow: 2.0.0 - '@vitest/mocker@3.2.7(vite@7.3.6(@types/node@24.13.3)(yaml@2.9.0))': + '@vitest/mocker@3.2.7(vite@7.3.6(@types/node@24.13.3))': dependencies: '@vitest/spy': 3.2.7 estree-walker: 3.0.3 magic-string: 0.30.21 optionalDependencies: - vite: 7.3.6(@types/node@24.13.3)(yaml@2.9.0) + vite: 7.3.6(@types/node@24.13.3) '@vitest/pretty-format@3.2.7': dependencies: @@ -1708,13 +1662,13 @@ snapshots: dependencies: rolldown: 1.0.0-rc.17 - vite-node@3.2.4(@types/node@24.13.3)(yaml@2.9.0): + vite-node@3.2.4(@types/node@24.13.3): dependencies: cac: 6.7.14 debug: 4.4.3 es-module-lexer: 1.7.0 pathe: 2.0.3 - vite: 7.3.6(@types/node@24.13.3)(yaml@2.9.0) + vite: 7.3.6(@types/node@24.13.3) transitivePeerDependencies: - '@types/node' - jiti @@ -1729,7 +1683,7 @@ snapshots: - tsx - yaml - vite@7.3.6(@types/node@24.13.3)(yaml@2.9.0): + vite@7.3.6(@types/node@24.13.3): dependencies: esbuild: 0.28.2 fdir: 6.5.0(picomatch@4.0.5) @@ -1740,13 +1694,12 @@ snapshots: optionalDependencies: '@types/node': 24.13.3 fsevents: 2.3.3 - yaml: 2.9.0 - vitest@3.2.7(@types/node@24.13.3)(yaml@2.9.0): + vitest@3.2.7(@types/node@24.13.3): dependencies: '@types/chai': 5.2.3 '@vitest/expect': 3.2.7 - '@vitest/mocker': 3.2.7(vite@7.3.6(@types/node@24.13.3)(yaml@2.9.0)) + '@vitest/mocker': 3.2.7(vite@7.3.6(@types/node@24.13.3)) '@vitest/pretty-format': 3.2.7 '@vitest/runner': 3.2.7 '@vitest/snapshot': 3.2.7 @@ -1764,8 +1717,8 @@ snapshots: tinyglobby: 0.2.17 tinypool: 1.1.1 tinyrainbow: 2.0.0 - vite: 7.3.6(@types/node@24.13.3)(yaml@2.9.0) - vite-node: 3.2.4(@types/node@24.13.3)(yaml@2.9.0) + vite: 7.3.6(@types/node@24.13.3) + vite-node: 3.2.4(@types/node@24.13.3) why-is-node-running: 2.3.0 optionalDependencies: '@types/node': 24.13.3 @@ -1787,5 +1740,3 @@ snapshots: dependencies: siginfo: 2.0.0 stackback: 0.0.2 - - yaml@2.9.0: {} diff --git a/integrations/dsh/plugins/powercontext/pnpm-workspace.yaml b/integrations/dsh/plugins/powercontext/pnpm-workspace.yaml index 1252c95d4..d7c6bb866 100644 --- a/integrations/dsh/plugins/powercontext/pnpm-workspace.yaml +++ b/integrations/dsh/plugins/powercontext/pnpm-workspace.yaml @@ -14,5 +14,8 @@ autoInstallPeers: false +packages: + - . + allowBuilds: esbuild: true diff --git a/integrations/dsh/plugins/powercontext/scripts/e2e-server.mjs b/integrations/dsh/plugins/powercontext/scripts/e2e-server.mjs index f0a0d30d4..1fe1906fe 100644 --- a/integrations/dsh/plugins/powercontext/scripts/e2e-server.mjs +++ b/integrations/dsh/plugins/powercontext/scripts/e2e-server.mjs @@ -20,7 +20,6 @@ import { existsSync, mkdtempSync } from 'node:fs' import { tmpdir } from 'node:os' import { dirname, join, resolve } from 'node:path' import { fileURLToPath } from 'node:url' -import { resolvePowerContextRoot } from './sync-openapi.mjs' const pluginRoot = join(dirname(fileURLToPath(import.meta.url)), '..') @@ -36,8 +35,8 @@ function walkForPyproject(startDir) { } export function defaultPowerContextRoot() { - const fromResolver = resolvePowerContextRoot() - if (fromResolver && existsSync(join(fromResolver, 'pyproject.toml'))) return fromResolver + const configured = process.env.POWERCONTEXT_ROOT?.trim() + if (configured && existsSync(join(configured, 'pyproject.toml'))) return resolve(configured) return walkForPyproject(pluginRoot) } diff --git a/integrations/dsh/plugins/powercontext/scripts/gen-operations.mjs b/integrations/dsh/plugins/powercontext/scripts/gen-operations.mjs deleted file mode 100644 index 326a5c9e9..000000000 --- a/integrations/dsh/plugins/powercontext/scripts/gen-operations.mjs +++ /dev/null @@ -1,69 +0,0 @@ -/* - * Copyright (c) 2026 OceanBase. - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -import { mkdirSync, readFileSync, writeFileSync } from 'node:fs' -import { dirname, join } from 'node:path' -import { fileURLToPath, pathToFileURL } from 'node:url' -import { parse } from 'yaml' -import { parseOperations, renderOperationsSource } from './openapi-ops.mjs' -import { resolveOpenApiPath, syncOpenApi } from './sync-openapi.mjs' - -const root = join(dirname(fileURLToPath(import.meta.url)), '..') -const generatedPath = join(root, 'src', 'operations.generated.ts') -const DRIFT_MESSAGE = 'Generated API code drifted; run `pnpm gen` and review the result.' - -export function renderGeneratedSource(yamlPath = resolveOpenApiPath()) { - const doc = parse(readFileSync(yamlPath, 'utf8')) - const rows = parseOperations(doc) - if (rows.length === 0) { - throw new Error('gen-operations: no operations parsed from openapi/powercontext.yaml') - } - return renderOperationsSource(rows) -} - -function normalizeNewlines(text) { - return text.replace(/\r\n/g, '\n') -} - -export function checkGenerated(path = generatedPath) { - const expected = renderGeneratedSource() - const actual = readFileSync(path, 'utf8') - if (normalizeNewlines(actual) !== normalizeNewlines(expected)) throw new Error(DRIFT_MESSAGE) -} - -export function generateOperations() { - const yamlPath = syncOpenApi() - const source = renderGeneratedSource(yamlPath) - mkdirSync(dirname(generatedPath), { recursive: true }) - writeFileSync(generatedPath, source) - return generatedPath -} - -function main() { - if (process.argv.includes('--check')) { - checkGenerated() - console.log('generated operations are current') - return - } - const path = generateOperations() - console.log(`wrote operations to ${path}`) -} - -const invokedDirectly = process.argv[1] !== undefined - && import.meta.url === pathToFileURL(process.argv[1]).href -if (invokedDirectly) { - main() -} diff --git a/integrations/dsh/plugins/powercontext/scripts/openapi-ops.mjs b/integrations/dsh/plugins/powercontext/scripts/openapi-ops.mjs deleted file mode 100644 index 1afad5217..000000000 --- a/integrations/dsh/plugins/powercontext/scripts/openapi-ops.mjs +++ /dev/null @@ -1,128 +0,0 @@ -/* - * Copyright (c) 2026 OceanBase. - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete'] - -export function resolveRef(doc, ref, seen = new Set()) { - if (typeof ref !== 'string' || !ref.startsWith('#/')) return undefined - if (seen.has(ref)) return undefined - seen.add(ref) - let current = doc - for (const raw of ref.slice(2).split('/')) { - const key = raw.replaceAll('~1', '/').replaceAll('~0', '~') - current = current?.[key] - } - return current -} - -export function deref(doc, node, seen = new Set()) { - if (!node || typeof node !== 'object') return node - if (typeof node.$ref === 'string') { - return deref(doc, resolveRef(doc, node.$ref, seen), seen) - } - return node -} - -export function schemaHasScope(doc, schema, seen = new Set()) { - const resolved = deref(doc, schema, seen) - if (!resolved || typeof resolved !== 'object') return false - if (resolved.properties && Object.hasOwn(resolved.properties, 'scope_id')) return true - for (const key of ['allOf', 'oneOf', 'anyOf']) { - const parts = resolved[key] - if (!Array.isArray(parts)) continue - if (parts.some((part) => schemaHasScope(doc, part, new Set(seen)))) return true - } - return false -} - -function jsonBodySchema(doc, operation) { - const body = deref(doc, operation.requestBody) - return body?.content?.['application/json']?.schema -} - -function operationParameters(doc, pathItem, operation) { - const listed = [...(pathItem.parameters ?? []), ...(operation.parameters ?? [])] - return listed.map((item) => deref(doc, item)).filter(Boolean) -} - -function requestLocation(bodySchema, parameters) { - if (bodySchema) return 'body' - if (parameters.some((parameter) => parameter.in === 'query')) return 'query' - return null -} - -function operationHasScope(doc, bodySchema, parameters) { - if (bodySchema && schemaHasScope(doc, bodySchema)) return true - return parameters.some((parameter) => parameter.in === 'query' && parameter.name === 'scope_id') -} - -export function parseOperations(doc) { - const rows = [] - for (const [path, pathItem] of Object.entries(doc.paths ?? {})) { - if (!pathItem || typeof pathItem !== 'object') continue - for (const method of HTTP_METHODS) { - const operation = pathItem[method] - if (!operation?.operationId) continue - const parameters = operationParameters(doc, pathItem, operation) - const bodySchema = jsonBodySchema(doc, operation) - rows.push({ - operationId: operation.operationId, - method: method.toUpperCase(), - path, - location: requestLocation(bodySchema, parameters), - scope: operationHasScope(doc, bodySchema, parameters), - }) - } - } - return rows -} - -export function renderOperationsSource(rows) { - const body = rows - .map((row) => { - const location = row.location === null ? 'null' : `"${row.location}"` - return ` ${row.operationId}: { method: '${row.method}', path: '${row.path}', location: ${location}, scope: ${row.scope} },` - }) - .join('\n') - return `/* - * Copyright (c) 2026 OceanBase. - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -// generated from openapi/powercontext.yaml; do not edit. - -export const OPERATIONS = { -${body} -} as const - -export type OperationId = keyof typeof OPERATIONS - -export type OperationSpec = (typeof OPERATIONS)[OperationId] - -export const OPERATION_IDS = Object.keys(OPERATIONS) as OperationId[] -` -} diff --git a/integrations/dsh/plugins/powercontext/scripts/prepare.mjs b/integrations/dsh/plugins/powercontext/scripts/prepare.mjs index 4b28f1266..94f769c86 100644 --- a/integrations/dsh/plugins/powercontext/scripts/prepare.mjs +++ b/integrations/dsh/plugins/powercontext/scripts/prepare.mjs @@ -34,9 +34,6 @@ if (existsSync(built) && !force) { process.exit(0) } -const gen = run('gen-operations.mjs') -if (gen.status !== 0) process.exit(gen.status ?? 1) - const tsdown = spawnSync('tsdown', { cwd: root, stdio: 'inherit', shell: true }) if (tsdown.status === 0) { const normalize = run('normalize-build-output.mjs') diff --git a/integrations/dsh/plugins/powercontext/scripts/sync-openapi.mjs b/integrations/dsh/plugins/powercontext/scripts/sync-openapi.mjs deleted file mode 100644 index 589ccd94c..000000000 --- a/integrations/dsh/plugins/powercontext/scripts/sync-openapi.mjs +++ /dev/null @@ -1,77 +0,0 @@ -/* - * Copyright (c) 2026 OceanBase. - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -import { copyFileSync, existsSync, mkdirSync } from 'node:fs' -import { dirname, join, resolve } from 'node:path' -import { fileURLToPath, pathToFileURL } from 'node:url' - -const root = join(dirname(fileURLToPath(import.meta.url)), '..') -const dest = join(root, 'openapi', 'powercontext.yaml') - -function existingFile(path) { - return path && existsSync(path) ? resolve(path) : undefined -} - -function walkForOpenApi(startDir, ignoredPath) { - let dir = resolve(startDir) - const ignored = ignoredPath ? resolve(ignoredPath) : undefined - for (let i = 0; i < 8; i += 1) { - const candidate = join(dir, 'openapi', 'powercontext.yaml') - if (existsSync(candidate) && resolve(candidate) !== ignored) return resolve(candidate) - const parent = resolve(dir, '..') - if (parent === dir) break - dir = parent - } - return undefined -} - -export function resolvePowerContextRoot(packageRoot = root) { - const fromEnv = process.env.POWERCONTEXT_ROOT?.trim() - if (fromEnv && existsSync(fromEnv)) return resolve(fromEnv) - const fallback = join(packageRoot, 'openapi', 'powercontext.yaml') - const yamlPath = walkForOpenApi(packageRoot, fallback) - if (!yamlPath) return undefined - return resolve(dirname(yamlPath), '..') -} - -export function resolveOpenApiPath(packageRoot = root) { - const fromEnv = existingFile(process.env.POWERCONTEXT_OPENAPI?.trim()) - if (fromEnv) return fromEnv - const checkout = resolvePowerContextRoot(packageRoot) - const fromRoot = checkout - ? existingFile(join(checkout, 'openapi', 'powercontext.yaml')) - : undefined - if (fromRoot) return fromRoot - const fallback = existingFile(join(packageRoot, 'openapi', 'powercontext.yaml')) - if (fallback) return fallback - throw new Error( - 'openapi/powercontext.yaml is missing. Point POWERCONTEXT_ROOT or POWERCONTEXT_OPENAPI at a PowerContext checkout.', - ) -} - -export function syncOpenApi() { - const source = resolveOpenApiPath() - if (source === dest) return dest - mkdirSync(dirname(dest), { recursive: true }) - copyFileSync(source, dest) - return dest -} - -const invokedDirectly = process.argv[1] !== undefined - && import.meta.url === pathToFileURL(process.argv[1]).href -if (invokedDirectly) { - console.log(`openapi synced to ${syncOpenApi()}`) -} diff --git a/integrations/dsh/plugins/powercontext/src/client.ts b/integrations/dsh/plugins/powercontext/src/client.ts index 1bbdf1655..82f0a0384 100644 --- a/integrations/dsh/plugins/powercontext/src/client.ts +++ b/integrations/dsh/plugins/powercontext/src/client.ts @@ -127,6 +127,26 @@ function isRedirect(status: number): boolean { return status >= 300 && status < 400 } +function bindOperationPath( + spec: OperationSpec, + payload: JsonObject | undefined, +): { path: string; payload: JsonObject | undefined } { + const pathParameters: readonly string[] = spec.pathParameters + if (pathParameters.length === 0) return { path: spec.path, payload } + + const transportPayload = { ...payload } + let path: string = spec.path + for (const name of pathParameters) { + const value = transportPayload[name] + if (typeof value !== 'string' || value.trim().length === 0) { + throw new TypeError(`operation requires string path parameter ${name}`) + } + path = path.replace(`{${name}}`, encodeURIComponent(value)) + delete transportPayload[name] + } + return { path, payload: transportPayload } +} + export class PowerContextClient { private readonly baseUrl: string private readonly authorization: string | undefined @@ -147,20 +167,21 @@ export class PowerContextClient { ): Promise { if (!(id in OPERATIONS)) throw new UnknownOperationError(id) const spec = OPERATIONS[id as OperationId] - const url = this.buildUrl(spec, payload) + const bound = bindOperationPath(spec, payload) + const url = this.buildUrl(spec, bound.path, bound.payload) try { - const response = await this.fetchImpl(url, this.buildInit(spec, payload, signal)) + const response = await this.fetchImpl(url, this.buildInit(spec, bound.payload, signal)) return await this.parseResponse(id, spec, payload, response) } catch (error) { if (error instanceof ServerResponseError || error instanceof InvalidResponseError) throw error if (error instanceof UnknownOperationError) throw error - throw this.wrapTransport(spec.path, error) + throw this.wrapTransport(bound.path, error) } } - private buildUrl(spec: OperationSpec, payload: JsonObject | undefined): string { + private buildUrl(spec: OperationSpec, path: string, payload: JsonObject | undefined): string { const suffix = spec.location === 'query' ? queryString(payload) : '' - return `${this.baseUrl}${spec.path}${suffix}` + return `${this.baseUrl}${path}${suffix}` } private buildInit(spec: OperationSpec, payload: JsonObject | undefined, signal?: AbortSignal): RequestInit { @@ -175,7 +196,7 @@ export class PowerContextClient { redirect: 'manual', signal: combineSignals([timeoutSignal(this.requestTimeoutMs), ...signal ? [signal] : []]), } - if (spec.method === 'POST' && spec.location === 'body') { + if (spec.location === 'body') { headers['Content-Type'] = 'application/json' init.body = JSON.stringify(payload ?? {}) } diff --git a/integrations/dsh/plugins/powercontext/src/commands.ts b/integrations/dsh/plugins/powercontext/src/commands.ts index 401d07e79..597fdefd0 100644 --- a/integrations/dsh/plugins/powercontext/src/commands.ts +++ b/integrations/dsh/plugins/powercontext/src/commands.ts @@ -73,8 +73,8 @@ async function handleReview( } async function handleDoctor(runtime: PluginRuntime, signal?: AbortSignal): Promise { - const live = await invokeOperation(runtime.client, 'get_liveness', {}, runtime.config.scopeId ?? 'local:unknown', signal) - const ready = await invokeOperation(runtime.client, 'get_readiness', {}, runtime.config.scopeId ?? 'local:unknown', signal) + const live = await invokeOperation(runtime.client, 'get_liveness', {}, runtime.config.scopeId ?? '', signal) + const ready = await invokeOperation(runtime.client, 'get_readiness', {}, runtime.config.scopeId ?? '', signal) return { kind: live.ok && ready.ok ? 'success' : 'error', text: formatResult({ ok: live.ok && ready.ok, data: { live, ready } }) } } diff --git a/integrations/dsh/plugins/powercontext/src/index.ts b/integrations/dsh/plugins/powercontext/src/index.ts index d70dcc713..23122cc0d 100644 --- a/integrations/dsh/plugins/powercontext/src/index.ts +++ b/integrations/dsh/plugins/powercontext/src/index.ts @@ -23,7 +23,7 @@ import { PLUGIN_NAME } from './errors.ts' import type { PluginRuntime } from './invoke.ts' import { loadPeer } from './peers.ts' import { runRecallPreStep, type PromptMessage } from './recall.ts' -import { deriveScopeId } from './scope.ts' +import { resolveScopeId } from './scope.ts' import { registerGuidance, registerSkill } from './skill.ts' import { registerTools } from './tools.ts' @@ -67,7 +67,7 @@ function createRuntime(ctx: Context, config: PluginConfig): PluginRuntime { return { client, config: resolved, - resolveScope: (cwd) => deriveScopeId(cwd, { configuredScopeId: resolved.scopeId }), + resolveScope: (cwd) => resolveScopeId(client, cwd, resolved.scopeId), log: (event) => { const line = JSON.stringify({ component: 'powercontext.dsh', ...event }) const quiet = event.outcome === 'ready' || event.outcome === 'ok' || event.outcome === 'empty' diff --git a/integrations/dsh/plugins/powercontext/src/invoke.ts b/integrations/dsh/plugins/powercontext/src/invoke.ts index 0c59706c5..1af7b0806 100644 --- a/integrations/dsh/plugins/powercontext/src/invoke.ts +++ b/integrations/dsh/plugins/powercontext/src/invoke.ts @@ -103,8 +103,11 @@ export function injectScope( payload: JsonObject | undefined, scopeId: string, ): JsonObject | undefined { - if (!OPERATIONS[operationId].scope) return payload - return { ...payload, scope_id: scopeId } + const mode = OPERATIONS[operationId].scopeMode + if (mode === 'selection') { + return { ...payload, selection: { mode: 'exact', scope_ids: [scopeId] } } + } + return mode === 'current' ? { ...payload, scope_id: scopeId } : payload } function encodeSuccess(result: Awaited>): ToolResult { diff --git a/integrations/dsh/plugins/powercontext/src/operations.generated.ts b/integrations/dsh/plugins/powercontext/src/operations.generated.ts index 092c7108a..4dd7b53a3 100644 --- a/integrations/dsh/plugins/powercontext/src/operations.generated.ts +++ b/integrations/dsh/plugins/powercontext/src/operations.generated.ts @@ -17,59 +17,56 @@ // generated from openapi/powercontext.yaml; do not edit. export const OPERATIONS = { - get_liveness: { method: 'GET', path: '/health/live', location: null, scope: false }, - get_readiness: { method: 'GET', path: '/health/ready', location: null, scope: false }, - get_capabilities: { method: 'GET', path: '/v1/capabilities', location: null, scope: false }, - capture_content_source: { method: 'POST', path: '/v1/sources/content', location: "body", scope: true }, - prepare_context: { method: 'POST', path: '/v1/context/prepare', location: "body", scope: true }, - create_work_contract: { method: 'POST', path: '/v1/work/contracts/create', location: "body", scope: true }, - handoff_current_work: { method: 'POST', path: '/v1/work/handoffs/prepare-current', location: "body", scope: true }, - acknowledge_handoff: { method: 'POST', path: '/v1/work/handoffs/acknowledge', location: "body", scope: true }, - record_task_outcome: { method: 'POST', path: '/v1/work/outcomes/record', location: "body", scope: true }, - activate_handoff: { method: 'POST', path: '/v1/handoff/activate', location: "body", scope: true }, - prepare_handoff: { method: 'POST', path: '/v1/handoff/prepare', location: "body", scope: true }, - finalize_handoff: { method: 'POST', path: '/v1/handoff/finalize', location: "body", scope: true }, - commit_handoff: { method: 'POST', path: '/v1/handoff/commit', location: "body", scope: true }, - continue_handoff: { method: 'POST', path: '/v1/handoff/continue', location: "body", scope: true }, - flush_memory: { method: 'POST', path: '/v1/memory/flush', location: "body", scope: true }, - remember_memory: { method: 'POST', path: '/v1/memory/remember', location: "body", scope: true }, - search_memory: { method: 'POST', path: '/v1/memory/search', location: "body", scope: true }, - list_memory_entries: { method: 'POST', path: '/v1/memory/entries/list', location: "body", scope: true }, - get_memory_entry: { method: 'POST', path: '/v1/memory/entries/get', location: "body", scope: true }, - revise_memory_entry: { method: 'POST', path: '/v1/memory/entries/revise', location: "body", scope: true }, - retire_memory_entry: { method: 'POST', path: '/v1/memory/entries/retire', location: "body", scope: true }, - list_memory_changes: { method: 'POST', path: '/v1/memory/changes', location: "body", scope: true }, - propose_experience: { method: 'POST', path: '/v1/experience/propose', location: "body", scope: true }, - generate_experience: { method: 'POST', path: '/v1/experience/generate', location: "body", scope: true }, - get_experience: { method: 'POST', path: '/v1/experience/get', location: "body", scope: true }, - propose_skill: { method: 'POST', path: '/v1/skill/propose', location: "body", scope: true }, - generate_skill: { method: 'POST', path: '/v1/skill/generate', location: "body", scope: true }, - get_skill: { method: 'POST', path: '/v1/skill/get', location: "body", scope: true }, - scan_external_skills: { method: 'POST', path: '/v1/external-skills/scan', location: "body", scope: true }, - list_external_skills: { method: 'POST', path: '/v1/external-skills/list', location: "body", scope: true }, - resolve_external_skill: { method: 'POST', path: '/v1/external-skills/resolve', location: "body", scope: true }, - import_external_skill: { method: 'POST', path: '/v1/external-skills/import', location: "body", scope: true }, - list_artifact_candidates: { method: 'POST', path: '/v1/artifact-candidates/list', location: "body", scope: true }, - get_artifact_candidate: { method: 'POST', path: '/v1/artifact-candidates/get', location: "body", scope: true }, - approve_artifact_candidate: { method: 'POST', path: '/v1/artifact-candidates/approve', location: "body", scope: true }, - reject_artifact_candidate: { method: 'POST', path: '/v1/artifact-candidates/reject', location: "body", scope: true }, - revise_artifact_candidate: { method: 'POST', path: '/v1/artifact-candidates/revise', location: "body", scope: true }, - get_stats: { method: 'GET', path: '/v1/stats', location: "query", scope: true }, - create_handoff_report_project: { method: 'POST', path: '/v1/handoff-reports/projects/create', location: "body", scope: false }, - list_handoff_report_projects: { method: 'POST', path: '/v1/handoff-reports/projects/list', location: "body", scope: false }, - list_handoff_report_known_scopes: { method: 'POST', path: '/v1/handoff-reports/scopes/list-known', location: "body", scope: false }, - get_handoff_report_project: { method: 'POST', path: '/v1/handoff-reports/projects/get', location: "body", scope: false }, - update_handoff_report_project: { method: 'POST', path: '/v1/handoff-reports/projects/update', location: "body", scope: false }, - register_handoff_report_workstream: { method: 'POST', path: '/v1/handoff-reports/workstreams/register', location: "body", scope: true }, - list_handoff_report_workstreams: { method: 'POST', path: '/v1/handoff-reports/workstreams/list', location: "body", scope: false }, - update_handoff_report_workstream: { method: 'POST', path: '/v1/handoff-reports/workstreams/update', location: "body", scope: false }, - get_handoff_report: { method: 'POST', path: '/v1/handoff-reports/get', location: "body", scope: true }, - record_handoff_report_activity: { method: 'POST', path: '/v1/handoff-reports/activities/record', location: "body", scope: true }, - list_handoff_report_activities: { method: 'POST', path: '/v1/handoff-reports/activities/list', location: "body", scope: false }, - purge_handoff_report_activities: { method: 'POST', path: '/v1/handoff-reports/activities/purge', location: "body", scope: false }, - get_handoff_report_workspace: { method: 'POST', path: '/v1/handoff-reports/workspace-bindings/get', location: "body", scope: false }, - attach_handoff_report_workspace: { method: 'POST', path: '/v1/handoff-reports/workspace-bindings/attach', location: "body", scope: false }, - detach_handoff_report_workspace: { method: 'POST', path: '/v1/handoff-reports/workspace-bindings/detach', location: "body", scope: false }, + get_liveness: { method: 'GET', path: '/health/live', location: null, scopeMode: 'none', pathParameters: [] }, + get_readiness: { method: 'GET', path: '/health/ready', location: null, scopeMode: 'none', pathParameters: [] }, + get_capabilities: { method: 'GET', path: '/v1/capabilities', location: null, scopeMode: 'none', pathParameters: [] }, + list_scopes: { method: 'GET', path: '/v1/scopes', location: null, scopeMode: 'none', pathParameters: [] }, + create_scope: { method: 'POST', path: '/v1/scopes', location: "body", scopeMode: 'none', pathParameters: [] }, + publish_artifact: { method: 'POST', path: '/v1/artifact-publications', location: "body", scopeMode: 'none', pathParameters: [] }, + get_scope: { method: 'GET', path: '/v1/scopes/{scope_id}', location: null, scopeMode: 'none', pathParameters: ['scope_id'] }, + update_scope: { method: 'PUT', path: '/v1/scopes/{scope_id}', location: "body", scopeMode: 'none', pathParameters: ['scope_id'] }, + get_default_scope: { method: 'GET', path: '/v1/scopes/default', location: null, scopeMode: 'none', pathParameters: [] }, + set_default_scope: { method: 'PUT', path: '/v1/scopes/default', location: "body", scopeMode: 'none', pathParameters: [] }, + resolve_scope_selection: { method: 'POST', path: '/v1/scopes/selection/resolve', location: "body", scopeMode: 'none', pathParameters: [] }, + resolve_scope_binding: { method: 'POST', path: '/v1/scope-bindings/resolve', location: "body", scopeMode: 'none', pathParameters: [] }, + set_scope_binding: { method: 'PUT', path: '/v1/scope-bindings', location: "body", scopeMode: 'none', pathParameters: [] }, + clear_scope_binding: { method: 'POST', path: '/v1/scope-bindings/clear', location: "body", scopeMode: 'none', pathParameters: [] }, + capture_content_source: { method: 'POST', path: '/v1/sources/content', location: "body", scopeMode: 'current', pathParameters: [] }, + prepare_context: { method: 'POST', path: '/v1/context/prepare', location: "body", scopeMode: 'current', pathParameters: [] }, + create_work_contract: { method: 'POST', path: '/v1/work/contracts/create', location: "body", scopeMode: 'current', pathParameters: [] }, + handoff_current_work: { method: 'POST', path: '/v1/work/handoffs/prepare-current', location: "body", scopeMode: 'current', pathParameters: [] }, + acknowledge_handoff: { method: 'POST', path: '/v1/work/handoffs/acknowledge', location: "body", scopeMode: 'current', pathParameters: [] }, + record_task_outcome: { method: 'POST', path: '/v1/work/outcomes/record', location: "body", scopeMode: 'current', pathParameters: [] }, + activate_handoff: { method: 'POST', path: '/v1/handoff/activate', location: "body", scopeMode: 'current', pathParameters: [] }, + prepare_handoff: { method: 'POST', path: '/v1/handoff/prepare', location: "body", scopeMode: 'current', pathParameters: [] }, + finalize_handoff: { method: 'POST', path: '/v1/handoff/finalize', location: "body", scopeMode: 'current', pathParameters: [] }, + commit_handoff: { method: 'POST', path: '/v1/handoff/commit', location: "body", scopeMode: 'current', pathParameters: [] }, + continue_handoff: { method: 'POST', path: '/v1/handoff/continue', location: "body", scopeMode: 'current', pathParameters: [] }, + flush_memory: { method: 'POST', path: '/v1/memory/flush', location: "body", scopeMode: 'current', pathParameters: [] }, + remember_memory: { method: 'POST', path: '/v1/memory/remember', location: "body", scopeMode: 'current', pathParameters: [] }, + search_memory: { method: 'POST', path: '/v1/memory/search', location: "body", scopeMode: 'current', pathParameters: [] }, + list_memory_entries: { method: 'POST', path: '/v1/memory/entries/list', location: "body", scopeMode: 'current', pathParameters: [] }, + get_memory_entry: { method: 'POST', path: '/v1/memory/entries/get', location: "body", scopeMode: 'current', pathParameters: [] }, + revise_memory_entry: { method: 'POST', path: '/v1/memory/entries/revise', location: "body", scopeMode: 'current', pathParameters: [] }, + retire_memory_entry: { method: 'POST', path: '/v1/memory/entries/retire', location: "body", scopeMode: 'current', pathParameters: [] }, + list_memory_changes: { method: 'POST', path: '/v1/memory/changes', location: "body", scopeMode: 'current', pathParameters: [] }, + propose_experience: { method: 'POST', path: '/v1/experience/propose', location: "body", scopeMode: 'current', pathParameters: [] }, + generate_experience: { method: 'POST', path: '/v1/experience/generate', location: "body", scopeMode: 'current', pathParameters: [] }, + get_experience: { method: 'POST', path: '/v1/experience/get', location: "body", scopeMode: 'current', pathParameters: [] }, + propose_skill: { method: 'POST', path: '/v1/skill/propose', location: "body", scopeMode: 'current', pathParameters: [] }, + generate_skill: { method: 'POST', path: '/v1/skill/generate', location: "body", scopeMode: 'current', pathParameters: [] }, + get_skill: { method: 'POST', path: '/v1/skill/get', location: "body", scopeMode: 'current', pathParameters: [] }, + scan_external_skills: { method: 'POST', path: '/v1/external-skills/scan', location: "body", scopeMode: 'current', pathParameters: [] }, + list_external_skills: { method: 'POST', path: '/v1/external-skills/list', location: "body", scopeMode: 'current', pathParameters: [] }, + resolve_external_skill: { method: 'POST', path: '/v1/external-skills/resolve', location: "body", scopeMode: 'current', pathParameters: [] }, + import_external_skill: { method: 'POST', path: '/v1/external-skills/import', location: "body", scopeMode: 'current', pathParameters: [] }, + list_artifact_candidates: { method: 'POST', path: '/v1/artifact-candidates/list', location: "body", scopeMode: 'current', pathParameters: [] }, + get_artifact_candidate: { method: 'POST', path: '/v1/artifact-candidates/get', location: "body", scopeMode: 'current', pathParameters: [] }, + approve_artifact_candidate: { method: 'POST', path: '/v1/artifact-candidates/approve', location: "body", scopeMode: 'current', pathParameters: [] }, + reject_artifact_candidate: { method: 'POST', path: '/v1/artifact-candidates/reject', location: "body", scopeMode: 'current', pathParameters: [] }, + revise_artifact_candidate: { method: 'POST', path: '/v1/artifact-candidates/revise', location: "body", scopeMode: 'current', pathParameters: [] }, + get_stats: { method: 'POST', path: '/v1/stats', location: "body", scopeMode: 'selection', pathParameters: [] }, + get_handoff_report: { method: 'POST', path: '/v1/handoff-reports/get', location: "body", scopeMode: 'selection', pathParameters: [] }, } as const export type OperationId = keyof typeof OPERATIONS diff --git a/integrations/dsh/plugins/powercontext/src/scope.ts b/integrations/dsh/plugins/powercontext/src/scope.ts index e70182ad2..4ec455b61 100644 --- a/integrations/dsh/plugins/powercontext/src/scope.ts +++ b/integrations/dsh/plugins/powercontext/src/scope.ts @@ -15,101 +15,35 @@ */ import { createHash } from 'node:crypto' -import { spawn } from 'node:child_process' import { resolve } from 'node:path' +import type { PowerContextClient } from './client.ts' -const MAX_SCOPE_LENGTH = 256 -const SCP_REMOTE = /^(?:[^@/\s]+@)?(?[^:/\s]+):(?.+)$/ - -export const UNSCOPED_MESSAGE = 'No project workspace on this session. Set scopeId or open a workspace.' - -export type GitRunner = (cwd: string, args: string[]) => Promise +export const UNSCOPED_MESSAGE = 'PowerContext could not resolve the current Scope.' export function sessionCwd(cwd: string | undefined): string | undefined { const value = cwd?.trim() return value ? value : undefined } -function bounded(prefix: string, value: string): string { - const candidate = `${prefix}:${value}` - if (candidate.length <= MAX_SCOPE_LENGTH) return candidate - return `${prefix}:sha256:${createHash('sha256').update(value).digest('hex')}` -} - -function boundedExplicit(value: string): string { - if (value.length <= MAX_SCOPE_LENGTH) return value - return `sha256:${createHash('sha256').update(value).digest('hex')}` -} - -function normalizePath(path: string): string { - let normalized = path.replaceAll('\\', '/').split('/').filter(Boolean).join('/') - if (normalized.endsWith('.git')) normalized = normalized.slice(0, -4) - return normalized.replace(/\/+$/, '') -} - -export function normalizeGitRemote(remote: string): string | undefined { - const value = remote.trim() - if (!value) return undefined - const scpMatch = !value.includes('://') ? value.match(SCP_REMOTE) : null - if (scpMatch?.groups) { - const host = scpMatch.groups.host.toLowerCase() - const path = normalizePath(scpMatch.groups.path) - return path ? `${host}/${path}` : undefined +export function workspaceBindingKey(cwd: string): { integration: string; kind: string; external_id: string } { + return { + integration: 'dsh', + kind: 'workspace', + external_id: createHash('sha256').update(resolve(cwd)).digest('hex'), } - let parsed: URL - try { - parsed = new URL(value) - } catch { - return undefined - } - if (!['http:', 'https:', 'ssh:', 'git:'].includes(parsed.protocol) || !parsed.hostname) { - return undefined - } - const host = parsed.port ? `${parsed.hostname.toLowerCase()}:${parsed.port}` : parsed.hostname.toLowerCase() - const path = normalizePath(parsed.pathname) - return path ? `${host}/${path}` : undefined -} - -export function spawnGit(cwd: string, args: string[]): Promise { - return new Promise((resolveResult) => { - const child = spawn('git', args, { cwd, windowsHide: true }) - const chunks: Buffer[] = [] - const timer = setTimeout(() => { - child.kill() - resolveResult(undefined) - }, 2000) - child.stdout.on('data', (chunk: Buffer) => chunks.push(chunk)) - child.on('error', () => { - clearTimeout(timer) - resolveResult(undefined) - }) - child.on('close', (code) => { - clearTimeout(timer) - if (code !== 0) { - resolveResult(undefined) - return - } - const text = Buffer.concat(chunks).toString('utf8').trim() - resolveResult(text || undefined) - }) - }) } -export async function deriveScopeId( +export async function resolveScopeId( + client: PowerContextClient, cwd: string | undefined, - options: { configuredScopeId?: string; git?: GitRunner } = {}, + configuredScopeId?: string, ): Promise { - if (options.configuredScopeId) return boundedExplicit(options.configuredScopeId) const workspace = sessionCwd(cwd) - if (!workspace) return undefined - return deriveWorkspaceScope(workspace, options.git ?? spawnGit) -} - -async function deriveWorkspaceScope(workspace: string, git: GitRunner): Promise { - const rootValue = await git(workspace, ['rev-parse', '--show-toplevel']) - const projectRoot = resolve(rootValue || workspace) - const remote = await git(projectRoot, ['config', '--get', 'remote.origin.url']) - const normalized = remote ? normalizeGitRemote(remote) : undefined - if (normalized) return bounded('git', normalized) - return `local:${createHash('sha256').update(projectRoot).digest('hex')}` + const response = await client.request('resolve_scope_binding', { + explicit_scope_id: configuredScopeId, + binding_keys: workspace ? [workspaceBindingKey(workspace)] : [], + }) + const value = response.value + const scopeId = value && typeof value === 'object' ? (value as { scope_id?: unknown }).scope_id : undefined + return typeof scopeId === 'string' && scopeId.trim() ? scopeId : undefined } diff --git a/integrations/dsh/plugins/powercontext/src/tools.ts b/integrations/dsh/plugins/powercontext/src/tools.ts index 384f5b21a..ba7ed5813 100644 --- a/integrations/dsh/plugins/powercontext/src/tools.ts +++ b/integrations/dsh/plugins/powercontext/src/tools.ts @@ -115,7 +115,7 @@ function memoryTools(runtime: PluginRuntime, defineTool: DefineTool): unknown[] }), pcTool(defineTool, { name: 'pc_memory_list', - description: 'List memory entries in the current project scope.', + description: 'List memory entries in the current Scope.', kind: 'read', parameters: { include_inactive: { type: 'boolean', description: 'Include retired entries for audit only.' }, diff --git a/integrations/dsh/plugins/powercontext/tests/client.spec.ts b/integrations/dsh/plugins/powercontext/tests/client.spec.ts index 835e15920..c29f724bc 100644 --- a/integrations/dsh/plugins/powercontext/tests/client.spec.ts +++ b/integrations/dsh/plugins/powercontext/tests/client.spec.ts @@ -61,11 +61,14 @@ describe('PowerContextClient', () => { expect(fetchImpl).toHaveBeenCalledOnce() }) - it('sends get_stats as a GET query string', async () => { + it('sends get_stats as a POST selection', async () => { const fetchImpl = vi.fn(async (url: string, init?: RequestInit) => { - expect(url).toBe('http://127.0.0.1:8000/v1/stats?scope_id=project%3Ademo&period=7d') - expect(init?.method).toBe('GET') - expect(init?.body).toBeUndefined() + expect(url).toBe('http://127.0.0.1:8000/v1/stats') + expect(init?.method).toBe('POST') + expect(JSON.parse(String(init?.body))).toEqual({ + selection: { mode: 'exact', scope_ids: ['project:demo'] }, + period: '7d', + }) return jsonResponse(200, { memories: 1 }) }) const client = new PowerContextClient({ @@ -73,7 +76,10 @@ describe('PowerContextClient', () => { requestTimeoutMs: 1000, fetch: fetchImpl, }) - await client.request('get_stats', { scope_id: 'project:demo', period: '7d' }) + await client.request('get_stats', { + selection: { mode: 'exact', scope_ids: ['project:demo'] }, + period: '7d', + }) expect(fetchImpl).toHaveBeenCalledOnce() }) @@ -83,11 +89,12 @@ describe('PowerContextClient', () => { requestTimeoutMs: 1000, fetch: async () => new Response('# Report', { status: 200 }), }) - await expect(markdownClient.request('get_handoff_report', { project_id: 'p1', format: 'markdown' })).resolves.toMatchObject({ + const selection = { mode: 'exact', scope_ids: ['scope-1'] } + await expect(markdownClient.request('get_handoff_report', { selection, format: 'markdown' })).resolves.toMatchObject({ kind: 'text', value: '# Report', }) - await expect(markdownClient.request('get_handoff_report', { project_id: 'p1' })).resolves.toMatchObject({ + await expect(markdownClient.request('get_handoff_report', { selection })).resolves.toMatchObject({ kind: 'text', value: '# Report', }) @@ -96,7 +103,7 @@ describe('PowerContextClient', () => { requestTimeoutMs: 1000, fetch: async () => new Response(new Uint8Array([1, 2, 3]), { status: 200 }), }) - const downloaded = await bytesClient.request('get_handoff_report', { project_id: 'p1', download: true }) + const downloaded = await bytesClient.request('get_handoff_report', { selection, download: true }) expect(downloaded.kind).toBe('bytes') if (downloaded.kind === 'bytes') expect([...downloaded.value]).toEqual([1, 2, 3]) }) @@ -145,14 +152,19 @@ describe('PowerContextClient', () => { }) for (const id of OPERATION_IDS) { const spec = OPERATIONS[id] - await client.request(id, spec.location === 'query' ? { scope_id: 's' } : { marker: id }) + const pathPayload = Object.fromEntries(spec.pathParameters.map((name) => [name, `value:${name}`])) + await client.request(id, { marker: id, ...pathPayload }) } expect(seen).toHaveLength(OPERATION_IDS.length) OPERATION_IDS.forEach((id, index) => { const spec = OPERATIONS[id] expect(seen[index].method).toBe(spec.method) - expect(seen[index].url.startsWith(`http://example.test${spec.path}`)).toBe(true) - expect(seen[index].hasBody).toBe(spec.method === 'POST' && spec.location === 'body') + const expectedPath = (spec.pathParameters as readonly string[]).reduce( + (path, name) => path.replace(`{${name}}`, encodeURIComponent(`value:${name}`)), + spec.path, + ) + expect(seen[index].url.startsWith(`http://example.test${expectedPath}`)).toBe(true) + expect(seen[index].hasBody).toBe(spec.location === 'body') }) }) }) diff --git a/integrations/dsh/plugins/powercontext/tests/commands.spec.ts b/integrations/dsh/plugins/powercontext/tests/commands.spec.ts index a450cf65d..557a3b65f 100644 --- a/integrations/dsh/plugins/powercontext/tests/commands.spec.ts +++ b/integrations/dsh/plugins/powercontext/tests/commands.spec.ts @@ -20,7 +20,6 @@ import { PowerContextClient } from '../src/client.ts' import type { PluginRuntime } from '../src/invoke.ts' import { resolveConfig } from '../src/config.ts' import { buildSourceId } from '../src/capture.ts' -import { deriveScopeId } from '../src/scope.ts' function runtime(fetchImpl: typeof fetch): PluginRuntime { const config = resolveConfig({ baseUrl: 'http://127.0.0.1:8000' }) @@ -62,24 +61,24 @@ describe('registerCommands missing session cwd', () => { return handler } - it('returns an unscoped error when cwd is missing and scopeId is not configured', async () => { + it('uses the Server default when cwd and scopeId are absent', async () => { const pluginRuntime = runtime(async () => new Response('{}')) pluginRuntime.config = { ...pluginRuntime.config, scopeId: undefined } - pluginRuntime.resolveScope = (cwd) => deriveScopeId(cwd) + pluginRuntime.resolveScope = async () => 'default-scope' const handler = registerHandler(pluginRuntime) const result = await handler({ rawInput: 'search public API', signal: AbortSignal.timeout(1000), agent: { session: { header: {} } }, }) - expect(result.kind).toBe('error') - expect(result.text).toContain('scopeId') + expect(result.kind).toBe('success') + expect(result.text).toContain('"ok": true') }) it('uses configured scopeId when cwd is missing', async () => { const pluginRuntime = runtime(async () => new Response('{}')) pluginRuntime.config = { ...pluginRuntime.config, scopeId: 'project:demo' } - pluginRuntime.resolveScope = (cwd) => deriveScopeId(cwd, { configuredScopeId: 'project:demo' }) + pluginRuntime.resolveScope = async () => 'project:demo' const handler = registerHandler(pluginRuntime) const result = await handler({ rawInput: '', diff --git a/integrations/dsh/plugins/powercontext/tests/e2e/call-through.spec.ts b/integrations/dsh/plugins/powercontext/tests/e2e/call-through.spec.ts index 02e3d9a9c..cfd5769ba 100644 --- a/integrations/dsh/plugins/powercontext/tests/e2e/call-through.spec.ts +++ b/integrations/dsh/plugins/powercontext/tests/e2e/call-through.spec.ts @@ -34,7 +34,7 @@ vi.mock('../../src/peers.ts', () => ({ }, })) -const SCOPE_ID = 'project:dsh-e2e' +let scopeId = '' const TEXT = 'Keep the DSH plugin on the public HTTP contract.' const REQUIRED_SERVICES = ['tools', 'agents', 'commands', 'skills', 'systemPrompt'] as const @@ -211,7 +211,7 @@ async function withHarness( baseUrl: string, callback: (harness: PluginHarness) => Promise, ): Promise { - const harness = new PluginHarness(baseUrl, SCOPE_ID) + const harness = new PluginHarness(baseUrl, scopeId) try { return await callback(harness) } finally { @@ -229,6 +229,9 @@ describe('plugin HTTP call-through without a model', () => { baseUrl: server.baseUrl, requestTimeoutMs: 5000, }) + const resolved = await client.request('get_default_scope') + expect(resolved.kind).toBe('json') + scopeId = (resolved.value as { scope_id: string }).scope_id }, 60_000) afterAll(async () => { @@ -246,14 +249,14 @@ describe('plugin HTTP call-through without a model', () => { it('remembers, searches, prepares, and captures over HTTP', async () => { const remembered = await client.request('remember_memory', { - scope_id: SCOPE_ID, + scope_id: scopeId, kind: 'decision', text: TEXT, }) expect(remembered.kind).toBe('json') const found = await client.request('search_memory', { - scope_id: SCOPE_ID, + scope_id: scopeId, query: 'DSH plugin HTTP contract', }) expect(found.kind).toBe('json') @@ -262,14 +265,14 @@ describe('plugin HTTP call-through without a model', () => { expect(hits.some((hit) => hit.text === TEXT)).toBe(true) const prepared = await client.request('prepare_context', { - scope_id: SCOPE_ID, + scope_id: scopeId, query: 'DSH plugin HTTP contract', }) expect(prepared.kind).toBe('json') expect(typeof prepared.value.content === 'string' || prepared.value.content === null).toBe(true) const captured = await client.request('capture_content_source', { - scope_id: SCOPE_ID, + scope_id: scopeId, source_id: 'dsh-e2e-turn-1', content: 'Call through the plugin client without a model.', metadata: { origin: 'dsh', event: 'e2e' }, @@ -309,7 +312,7 @@ describe('plugin HTTP call-through without a model', () => { })]) const status = await invokePc(harness.commandHandler(), '') expect(status.kind).toBe('success') - expect(status.text).toContain(`scope=${SCOPE_ID}`) + expect(status.text).toContain(`scope=${scopeId}`) }) }) diff --git a/integrations/dsh/plugins/powercontext/tests/e2e/unscoped-session.spec.ts b/integrations/dsh/plugins/powercontext/tests/e2e/unscoped-session.spec.ts index eff66919c..86fb30a41 100644 --- a/integrations/dsh/plugins/powercontext/tests/e2e/unscoped-session.spec.ts +++ b/integrations/dsh/plugins/powercontext/tests/e2e/unscoped-session.spec.ts @@ -14,19 +14,17 @@ * limitations under the License. */ -import { createHash } from 'node:crypto' -import { resolve } from 'node:path' import { afterAll, beforeAll, describe, expect, it } from 'vitest' import { PowerContextClient, type FetchFn, type JsonObject } from '../../src/client.ts' import { registerCommands } from '../../src/commands.ts' import { resolveConfig } from '../../src/config.ts' import type { PluginRuntime } from '../../src/invoke.ts' import { runRecallPreStep } from '../../src/recall.ts' -import { deriveScopeId, UNSCOPED_MESSAGE } from '../../src/scope.ts' +import { resolveScopeId } from '../../src/scope.ts' import { registerTools } from '../../src/tools.ts' import { startPowerContextServer } from '../../scripts/e2e-server.mjs' -const SCOPE_ID = 'project:dsh-e2e-unscoped' +let scopeId = '' const TEXT = 'Optional session cwd must not invent a harness working directory.' type RecordedCall = { path: string; body: JsonObject | undefined } @@ -83,15 +81,16 @@ function createPluginRuntime( timeoutMs: 8000, capturePrompts: true, }, {}) - return { - runtime: { - client: new PowerContextClient({ + const client = new PowerContextClient({ baseUrl: config.baseUrl, requestTimeoutMs: config.requestTimeoutMs, fetch: fetchImpl, - }), + }) + return { + runtime: { + client, config, - resolveScope: (cwd) => deriveScopeId(cwd, { configuredScopeId: config.scopeId }), + resolveScope: (cwd) => resolveScopeId(client, cwd, config.scopeId), log: (event) => { events.push(event) }, @@ -142,22 +141,28 @@ async function recallWithoutCwd(runtime: PluginRuntime, query: string) { }) } -function processDirectoryScope(): string { - return `local:${createHash('sha256').update(resolve(process.cwd())).digest('hex')}` -} - describe('plugin runtime with header.cwd === undefined', () => { let server: Awaited> beforeAll(async () => { server = await startPowerContextServer() + const response = await fetch(`${server.baseUrl}/v1/scopes`, { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ + title: 'DSH E2E Scope', + summary: 'Scope used by the DSH binding integration test.', + idempotency_key: 'dsh-e2e-scope-binding', + }), + }) + scopeId = String((await response.json() as { scope_id: string }).scope_id) }, 60_000) afterAll(async () => { await server?.stop() }) - it('skips recall, /pc, and tools without treating the process directory as a project', async () => { + it('uses the Server default without treating the process directory as a Scope', async () => { const { fetchImpl, calls } = trackingFetch() const { runtime, events } = createPluginRuntime(server.baseUrl, undefined, fetchImpl) const command = pcHandler(runtime) @@ -175,20 +180,17 @@ describe('plugin runtime with header.cwd === undefined', () => { }) expect(recalled).toEqual({ kind: 'enter', messages: [] }) - expect(events).toContainEqual({ - event: 'context_prepare', - outcome: 'skipped', - reason: 'missing_session_cwd', - }) - expect(pc).toEqual({ kind: 'error', text: UNSCOPED_MESSAGE }) - expect(tool).toMatchObject({ ok: false, code: 'unscoped', message: UNSCOPED_MESSAGE }) - expect(await runtime.resolveScope(undefined)).toBeUndefined() - expect(calls).toEqual([]) + expect(events.some((event) => event.event === 'context_prepare')).toBe(true) + expect(pc.kind).toBe('success') + expect(tool).toMatchObject({ ok: true }) + expect(await runtime.resolveScope(undefined)).toMatch(/^scp_/) + expect(calls.some((call) => call.path === '/v1/scope-bindings/resolve')).toBe(true) + expect(calls.every((call) => !String(call.body?.scope_id ?? '').startsWith('local:'))).toBe(true) }) it('uses configured scopeId against a live Server and omits a fabricated cwd', async () => { const { fetchImpl, calls } = trackingFetch() - const { runtime } = createPluginRuntime(server.baseUrl, SCOPE_ID, fetchImpl) + const { runtime } = createPluginRuntime(server.baseUrl, scopeId, fetchImpl) const command = pcHandler(runtime) const search = toolNamed(runtime, 'pc_search') @@ -211,10 +213,10 @@ describe('plugin runtime with header.cwd === undefined', () => { const capture = calls.find((call) => call.path === '/v1/sources/content') expect(capture?.body).toMatchObject({ - scope_id: SCOPE_ID, + scope_id: scopeId, metadata: { origin: 'dsh', event: 'user_prompt_submit', session_id: 'session-unscoped' }, }) expect((capture?.body?.metadata as { cwd?: string } | undefined)?.cwd).toBeUndefined() - expect(calls.every((call) => call.body?.scope_id !== processDirectoryScope())).toBe(true) + expect(calls.every((call) => !String(call.body?.scope_id ?? '').startsWith('local:'))).toBe(true) }) }) diff --git a/integrations/dsh/plugins/powercontext/tests/gen-check.spec.ts b/integrations/dsh/plugins/powercontext/tests/gen-check.spec.ts deleted file mode 100644 index d6654d4bd..000000000 --- a/integrations/dsh/plugins/powercontext/tests/gen-check.spec.ts +++ /dev/null @@ -1,42 +0,0 @@ -/* - * Copyright (c) 2026 OceanBase. - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -import { mkdtempSync, readFileSync, writeFileSync } from 'node:fs' -import { dirname, join } from 'node:path' -import { tmpdir } from 'node:os' -import { fileURLToPath } from 'node:url' -import { describe, expect, it } from 'vitest' -import { checkGenerated, renderGeneratedSource } from '../scripts/gen-operations.mjs' - -const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '..') - -describe('generated operations check', () => { - it('passes when the committed table matches OpenAPI', () => { - expect(() => checkGenerated()).not.toThrow() - }) - - it('fails when the committed table has drifted', () => { - const dir = mkdtempSync(join(tmpdir(), 'pc-gen-')) - const drifted = join(dir, 'operations.generated.ts') - writeFileSync(drifted, 'export const OPERATIONS = {}\n') - expect(() => checkGenerated(drifted)).toThrow(/drifted/) - }) - - it('renders the same source the repository currently commits', () => { - const committed = readFileSync(join(repoRoot, 'src', 'operations.generated.ts'), 'utf8').replace(/\r\n/g, '\n') - expect(renderGeneratedSource()).toBe(committed) - }) -}) diff --git a/integrations/dsh/plugins/powercontext/tests/invoke.spec.ts b/integrations/dsh/plugins/powercontext/tests/invoke.spec.ts index 82394b596..57ffb82ad 100644 --- a/integrations/dsh/plugins/powercontext/tests/invoke.spec.ts +++ b/integrations/dsh/plugins/powercontext/tests/invoke.spec.ts @@ -50,7 +50,7 @@ describe('invokeOperation', () => { expect(seen[1].url).toBe('http://127.0.0.1:8000/health/live') }) - it('overwrites a caller-supplied scope_id with the derived workspace scope', async () => { + it('overwrites a caller-supplied scope_id with the resolved workspace scope', async () => { let body: string | undefined const client = new PowerContextClient({ baseUrl: 'http://127.0.0.1:8000', @@ -64,14 +64,59 @@ describe('invokeOperation', () => { await invokeOperation(client, 'search_memory', { query: 'api', scope_id: 'project:attacker-controlled', - }, 'project:derived-workspace') + }, 'scp_workspace_binding') expect(JSON.parse(body ?? '{}')).toMatchObject({ query: 'api', - scope_id: 'project:derived-workspace', + scope_id: 'scp_workspace_binding', }) }) + it('limits observation selections to the resolved workspace scope', async () => { + const bodies: unknown[] = [] + const client = new PowerContextClient({ + baseUrl: 'http://127.0.0.1:8000', + requestTimeoutMs: 1000, + fetch: async (_url, init) => { + bodies.push(JSON.parse(String(init?.body))) + return new Response(JSON.stringify({ ok: true }), { status: 200 }) + }, + }) + + await invokeOperation(client, 'get_stats', { selection: { mode: 'all' } }, 'scp_workspace_binding') + await invokeOperation(client, 'get_handoff_report', { + selection: { mode: 'subtree', root_scope_id: 'scope:other' }, + format: 'json', + }, 'scp_workspace_binding') + + expect(bodies).toEqual([ + { selection: { mode: 'exact', scope_ids: ['scp_workspace_binding'] } }, + { + selection: { mode: 'exact', scope_ids: ['scp_workspace_binding'] }, + format: 'json', + }, + ]) + }) + + it('preserves explicit Scope control requests', async () => { + let body: string | undefined + const client = new PowerContextClient({ + baseUrl: 'http://127.0.0.1:8000', + requestTimeoutMs: 1000, + fetch: async (_url, init) => { + body = init?.body ? String(init.body) : undefined + return new Response(JSON.stringify({ scope_id: 'scp_target' }), { status: 200 }) + }, + }) + + await invokeOperation(client, 'set_scope_binding', { + key: { integration: 'dsh', kind: 'session', external_id: 'session-1' }, + scope_id: 'scp_target', + }, 'scp_current') + + expect(JSON.parse(body ?? '{}').scope_id).toBe('scp_target') + }) + it('returns unavailable instead of throwing when the server is down', async () => { const client = new PowerContextClient({ baseUrl: 'http://127.0.0.1:8000', diff --git a/integrations/dsh/plugins/powercontext/tests/operations-coverage.spec.ts b/integrations/dsh/plugins/powercontext/tests/operations-coverage.spec.ts deleted file mode 100644 index 61ce821ff..000000000 --- a/integrations/dsh/plugins/powercontext/tests/operations-coverage.spec.ts +++ /dev/null @@ -1,68 +0,0 @@ -/* - * Copyright (c) 2026 OceanBase. - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -import { readFileSync } from 'node:fs' -import { parse } from 'yaml' -import { describe, expect, it } from 'vitest' -import { parseOperations } from '../scripts/openapi-ops.mjs' -import { resolveOpenApiPath } from '../scripts/sync-openapi.mjs' -import { OPERATION_IDS, OPERATIONS } from '../src/operations.generated.ts' - -function loadYamlDoc() { - return parse(readFileSync(resolveOpenApiPath(), 'utf8')) -} - -describe('operations coverage', () => { - it('matches every OpenAPI operationId exactly', () => { - const fromYaml = parseOperations(loadYamlDoc()).map((row) => row.operationId).sort() - const generated = [...OPERATION_IDS].sort() - expect(generated).toEqual(fromYaml) - }) - - it('records method, path, and location for each operation', () => { - expect(OPERATIONS.get_liveness).toEqual({ - method: 'GET', - path: '/health/live', - location: null, - scope: false, - }) - expect(OPERATIONS.get_stats).toEqual({ - method: 'GET', - path: '/v1/stats', - location: 'query', - scope: true, - }) - expect(OPERATIONS.remember_memory).toEqual({ - method: 'POST', - path: '/v1/memory/remember', - location: 'body', - scope: true, - }) - expect(OPERATIONS.get_handoff_report.scope).toBe(true) - expect(OPERATIONS.get_capabilities.location).toBeNull() - }) - - it('matches generated method, path, location, and scope for every operation', () => { - for (const row of parseOperations(loadYamlDoc())) { - expect(OPERATIONS[row.operationId]).toEqual({ - method: row.method, - path: row.path, - location: row.location, - scope: row.scope, - }) - } - }) -}) diff --git a/integrations/dsh/plugins/powercontext/tests/recall-fail-open.spec.ts b/integrations/dsh/plugins/powercontext/tests/recall-fail-open.spec.ts index 3a4a7a048..aa01d1331 100644 --- a/integrations/dsh/plugins/powercontext/tests/recall-fail-open.spec.ts +++ b/integrations/dsh/plugins/powercontext/tests/recall-fail-open.spec.ts @@ -19,7 +19,6 @@ import { PowerContextClient } from '../src/client.ts' import { ServerResponseError, UnavailableError } from '../src/errors.ts' import { runRecallPreStep, type RecallInput } from '../src/recall.ts' import type { ResolvedConfig } from '../src/config.ts' -import { deriveScopeId } from '../src/scope.ts' const config: ResolvedConfig = { baseUrl: 'http://127.0.0.1:8000', @@ -241,23 +240,19 @@ describe('runRecallPreStep fail-open', () => { } }) - it('skips recall when cwd is missing and scopeId is not configured', async () => { + it('recalls from the Server default when cwd and scopeId are absent', async () => { const next = vi.fn(async () => ({ kind: 'enter' as const, messages: [{ id: 'user' }] })) const log = vi.fn() const result = await runRecallPreStep(input({ next, cwd: undefined, config: { ...config, scopeId: undefined }, - resolveScope: (cwd) => deriveScopeId(cwd), + resolveScope: async () => 'default-scope', log, })) expect(next).toHaveBeenCalledOnce() expect(result).toEqual({ kind: 'enter', messages: [{ id: 'user' }] }) - expect(log).toHaveBeenCalledWith({ - event: 'context_prepare', - outcome: 'skipped', - reason: 'missing_session_cwd', - }) + expect(log).toHaveBeenCalled() }) it('recalls with configured scopeId and omits a fabricated cwd from Source', async () => { @@ -280,7 +275,7 @@ describe('runRecallPreStep fail-open', () => { await runRecallPreStep(input({ cwd: undefined, client: { request } as never, - resolveScope: (cwd) => deriveScopeId(cwd, { configuredScopeId: 'project:demo' }), + resolveScope: async () => 'project:demo', })) const capture = request.mock.calls.find((call) => call[0] === 'capture_content_source') expect(capture?.[0]).toBe('capture_content_source') diff --git a/integrations/dsh/plugins/powercontext/tests/scope.spec.ts b/integrations/dsh/plugins/powercontext/tests/scope.spec.ts index b8afaa6bc..c1ca1501d 100644 --- a/integrations/dsh/plugins/powercontext/tests/scope.spec.ts +++ b/integrations/dsh/plugins/powercontext/tests/scope.spec.ts @@ -14,70 +14,31 @@ * limitations under the License. */ -import { createHash } from 'node:crypto' -import { resolve } from 'node:path' -import { describe, expect, it } from 'vitest' -import { deriveScopeId, normalizeGitRemote, sessionCwd } from '../src/scope.ts' +import { describe, expect, it, vi } from 'vitest' +import { resolveScopeId } from '../src/scope.ts' -describe('normalizeGitRemote', () => { - it('normalizes https, ssh, and scp remotes without credentials', () => { - expect(normalizeGitRemote('https://user:token@github.com/org/repo.git')).toBe('github.com/org/repo') - expect(normalizeGitRemote('ssh://git@github.com/org/repo.git')).toBe('github.com/org/repo') - expect(normalizeGitRemote('git@github.com:org/repo.git')).toBe('github.com/org/repo') - }) - - it('returns undefined for unsupported remotes', () => { - expect(normalizeGitRemote('')).toBeUndefined() - expect(normalizeGitRemote('file:///tmp/repo')).toBeUndefined() - }) -}) +describe('Scope binding', () => { + it('delegates explicit, durable, and default precedence to the Server', async () => { + const request = vi.fn().mockResolvedValue({ value: { scope_id: 'scp_00000000000000000000000000' } }) + const client = { request } as never -describe('deriveScopeId', () => { - it('uses an explicit configured id and hashes when it exceeds 256 characters', async () => { - expect(await deriveScopeId('/tmp/project', { configuredScopeId: 'project:demo' })).toBe('project:demo') - const long = `x`.repeat(300) - expect(await deriveScopeId('/tmp/project', { configuredScopeId: long })).toBe( - `sha256:${createHash('sha256').update(long).digest('hex')}`, + await expect(resolveScopeId(client, '/workspace', 'explicit-scope')).resolves.toBe( + 'scp_00000000000000000000000000', ) - }) - - it('derives git:host/path from origin', async () => { - const git = async (_cwd: string, args: string[]) => { - if (args[0] === 'rev-parse') return '/repo' - if (args[0] === 'config') return 'https://github.com/acme/power.git' - return undefined - } - expect(await deriveScopeId('/workspace', { git })).toBe('git:github.com/acme/power') - }) - - it('falls back to local hash when git is unavailable', async () => { - const cwd = resolve('/tmp/no-git-project') - const scope = await deriveScopeId(cwd, { git: async () => undefined }) - expect(scope).toBe(`local:${createHash('sha256').update(cwd).digest('hex')}`) - }) - - it('uses a configured scopeId even when session cwd is missing or blank', async () => { - const git = async () => { - throw new Error('git must not run when scopeId is configured') - } - expect(await deriveScopeId(undefined, { configuredScopeId: 'project:demo', git })).toBe('project:demo') - expect(await deriveScopeId('', { configuredScopeId: 'project:demo', git })).toBe('project:demo') - expect(await deriveScopeId(' ', { configuredScopeId: 'project:demo', git })).toBe('project:demo') - }) - - it('does not treat a missing or blank cwd as the process directory', async () => { - const git = async () => undefined - await expect(deriveScopeId(undefined, { git })).resolves.toBeUndefined() - await expect(deriveScopeId('', { git })).resolves.toBeUndefined() - await expect(deriveScopeId(' ', { git })).resolves.toBeUndefined() - }) -}) - -describe('sessionCwd', () => { - it('treats missing and blank values as absent', () => { - expect(sessionCwd(undefined)).toBeUndefined() - expect(sessionCwd('')).toBeUndefined() - expect(sessionCwd(' ')).toBeUndefined() - expect(sessionCwd('/repo')).toBe('/repo') + const [operation, input] = request.mock.calls[0] + expect(operation).toBe('resolve_scope_binding') + expect(input.explicit_scope_id).toBe('explicit-scope') + expect(input.binding_keys).toHaveLength(1) + expect(input.binding_keys[0]).toMatchObject({ integration: 'dsh', kind: 'workspace' }) + expect(input.binding_keys[0].external_id).not.toContain('/workspace') + }) + + it('uses the Server default when cwd is absent', async () => { + const request = vi.fn().mockResolvedValue({ value: { scope_id: 'default-scope' } }) + await expect(resolveScopeId({ request } as never, undefined)).resolves.toBe('default-scope') + expect(request).toHaveBeenCalledWith('resolve_scope_binding', { + explicit_scope_id: undefined, + binding_keys: [], + }) }) }) diff --git a/integrations/dsh/plugins/powercontext/tests/tools.spec.ts b/integrations/dsh/plugins/powercontext/tests/tools.spec.ts index 01f4e5c1a..f67dc2bbf 100644 --- a/integrations/dsh/plugins/powercontext/tests/tools.spec.ts +++ b/integrations/dsh/plugins/powercontext/tests/tools.spec.ts @@ -111,7 +111,7 @@ describe('agent tool surface', () => { { client: {} as never, config: { maxBytes: 8000 }, - resolveScope: async (cwd?: string) => cwd ? 'local:from-cwd' : undefined, + resolveScope: async (cwd?: string) => cwd ? 'scp_from_server' : undefined, log: vi.fn(), } as unknown as PluginRuntime, (definition) => definition, diff --git a/integrations/hermes/README.md b/integrations/hermes/README.md index c4c658709..73dee31b7 100644 --- a/integrations/hermes/README.md +++ b/integrations/hermes/README.md @@ -83,14 +83,12 @@ Configuration can also be stored manually in `$HERMES_HOME/powercontext/config.j ```json { "base_url": "http://127.0.0.1:8000", - "scope_id": "hermes:{profile}:{user_id}", "max_bytes": 8000, "timeout": 5, "capture_turns": true, "flush_on_session_end": true, "capture_pre_compress": false, - "evaluation_trace": false, - "workstream_persistence": true + "evaluation_trace": false } ``` @@ -102,7 +100,7 @@ Environment variables override file values: | `POWERCONTEXT_HERMES_BASE_URL` | PowerContext server URL | | `POWERCONTEXT_HERMES_AUTHORIZATION` | Complete authorization header, e.g. `Bearer ` | | `POWERCONTEXT_HERMES_TOKEN` | Token shorthand; used when `AUTHORIZATION` is absent | -| `POWERCONTEXT_HERMES_SCOPE_ID` | Explicit scope or scope template | +| `POWERCONTEXT_HERMES_SCOPE_ID` | Explicit server-owned Scope ID | | `POWERCONTEXT_HERMES_MAX_BYTES` | Maximum prepared context size, 512–32768 | | `POWERCONTEXT_HERMES_TIMEOUT` | HTTP request timeout in seconds | | `POWERCONTEXT_HERMES_CAPTURE_TURNS` | Capture completed turns as PowerContext Sources | @@ -110,13 +108,11 @@ Environment variables override file values: | `POWERCONTEXT_HERMES_CAPTURE_PRE_COMPRESS` | Capture filtered new user/assistant turns before compression; disabled by default | | `POWERCONTEXT_HERMES_EVALUATION_TRACE` | Record recalled context in per-session local JSONL files; disabled by default | | `POWERCONTEXT_HERMES_EVALUATION_TRACE_PATH` | Override the evaluation trace directory | -| `POWERCONTEXT_HERMES_WORKSTREAM` | Read the shared Git-private Workstream scope binding; enabled by default | -The default scope template is `hermes:{profile}:{user_id}`. The provider uses -the active Hermes profile and gateway user identifier when available. For local -CLI sessions without a user identifier, it derives a stable identifier from -the active `HERMES_HOME` path. This prevents cross-profile memory leakage while -keeping memories available across sessions. +Hermes asks the Server to resolve an explicit Scope, durable session and +workspace bindings, or the Server default, in that order. Workspace paths are +hashed only as external binding keys. Hermes does not generate Scope IDs from +profiles, users, repositories, or directories. ## Runtime behavior @@ -139,9 +135,8 @@ keeping memories available across sessions. - Mutating operations are described as explicit user-authorized actions. Artifact approval and rejection should only be used after the candidate has been reviewed. -- When Workstream persistence is enabled, Hermes reads - .git/powercontext/codex-workspace.json, the same Git-private binding used by - the other integrations. An explicit scope_id configuration takes precedence. +- `/pc scope bind SCOPE_ID` stores a durable workspace binding in PowerContext. + `/pc scope clear` removes it and resolves the current Scope again. - When evaluation tracing is enabled, each session gets its own JSONL file under `powercontext/evaluation-trace/sessions/`. Events include the session ID, parent session ID, scope, turn number, and a unique event ID. @@ -199,7 +194,7 @@ Hermes exposes that invocation context. /pc skill {propose|generate|get} PAYLOAD_JSON /pc external-skills {scan|list|resolve|import} [PAYLOAD_JSON] /pc review {list|get|approve|reject|revise} [PAYLOAD_JSON] -/pc workstream {status|bind SCOPE_ID|clear} +/pc scope {status|bind SCOPE_ID|clear} /pc call OPERATION [PAYLOAD_JSON] ``` diff --git a/integrations/hermes/plugins/powercontext-command/__init__.py b/integrations/hermes/plugins/powercontext-command/__init__.py index 5cb71a073..63bba9a77 100644 --- a/integrations/hermes/plugins/powercontext-command/__init__.py +++ b/integrations/hermes/plugins/powercontext-command/__init__.py @@ -49,7 +49,7 @@ "skill", "external-skills", "review", - "workstream", + "scope", "trace", "call", ) @@ -123,7 +123,7 @@ def register(ctx: Any) -> None: name, handler, description="Inspect and manage PowerContext memory, handoffs, artifacts, and traces.", - args_hint="status|search|list|changes|get|remember|revise|retire|flush|stats|handoff|experience|skill|external-skills|review|workstream|trace|call ...", + args_hint="status|search|list|changes|get|remember|revise|retire|flush|stats|handoff|experience|skill|external-skills|review|scope|trace|call ...", ) _register_subcommands() diff --git a/integrations/hermes/plugins/powercontext/README.md b/integrations/hermes/plugins/powercontext/README.md index fc81ba6aa..b85440e5f 100644 --- a/integrations/hermes/plugins/powercontext/README.md +++ b/integrations/hermes/plugins/powercontext/README.md @@ -66,11 +66,9 @@ authorization. When the provider is active, it also registers the bundled powercontext skill guide so Hermes has the workflow and authorization rules for those operations. -Workstream persistence is enabled by default. When the current directory is a -Git workspace, Hermes reads the shared -.git/powercontext/codex-workspace.json binding used by the other integrations. -An explicit scope_id configuration takes precedence. The /pc workstream -command can inspect, create, or clear the binding. +Hermes resolves Scope through PowerContext using an explicit Scope, durable +session and workspace bindings, or the Server default. The `/pc scope` command +can inspect, create, or clear the durable workspace binding. The standalone companion registers `/pc` and `/powercontext` during normal Hermes plugin discovery, so both aliases are known before the first Agent is @@ -105,7 +103,7 @@ exposes that invocation context. /pc skill {propose|generate|get} PAYLOAD_JSON /pc external-skills {scan|list|resolve|import} [PAYLOAD_JSON] /pc review {list|get|approve|reject|revise} [PAYLOAD_JSON] -/pc workstream {status|bind SCOPE_ID|clear} +/pc scope {status|bind SCOPE_ID|clear} /pc call OPERATION [PAYLOAD_JSON] ``` diff --git a/integrations/hermes/plugins/powercontext/cli.py b/integrations/hermes/plugins/powercontext/cli.py index 80437a6c6..a4808182d 100644 --- a/integrations/hermes/plugins/powercontext/cli.py +++ b/integrations/hermes/plugins/powercontext/cli.py @@ -91,8 +91,8 @@ def _print_result(value: Any) -> None: def _add_common_options(parser: argparse.ArgumentParser) -> None: parser.add_argument("--scope-id", help="Override the PowerContext memory scope.") - parser.add_argument("--profile", help="Hermes profile used in the default scope template.") - parser.add_argument("--user-id", default="", help="User identifier used in the default scope template.") + parser.add_argument("--profile", help="Hermes profile exposed to the provider.") + parser.add_argument("--user-id", default="", help="Hermes user identifier exposed to the provider.") def _add_citation_options(parser: argparse.ArgumentParser) -> None: diff --git a/integrations/hermes/plugins/powercontext/client.py b/integrations/hermes/plugins/powercontext/client.py index 49ad0a09a..df6a3ab28 100644 --- a/integrations/hermes/plugins/powercontext/client.py +++ b/integrations/hermes/plugins/powercontext/client.py @@ -234,6 +234,27 @@ def get_readiness(self) -> dict[str, Any]: def get_capabilities(self) -> dict[str, Any]: return self._request("/v1/capabilities", method="GET") + def resolve_scope_binding( + self, + *, + explicit_scope_id: str | None, + binding_keys: list[dict[str, str]], + ) -> dict[str, Any]: + return self._request( + "/v1/scope-bindings/resolve", + {"explicit_scope_id": explicit_scope_id, "binding_keys": binding_keys}, + ) + + def set_scope_binding(self, key: dict[str, str], scope_id: str) -> dict[str, Any]: + return self._request( + "/v1/scope-bindings", + {"key": key, "scope_id": scope_id}, + method="PUT", + ) + + def clear_scope_binding(self, key: dict[str, str]) -> dict[str, Any]: + return self._request("/v1/scope-bindings/clear", {"key": key}) + def prepare_context(self, scope_id: str, query: str, *, max_bytes: int) -> dict[str, Any]: return self._request( "/v1/context/prepare", diff --git a/integrations/hermes/plugins/powercontext/commands.py b/integrations/hermes/plugins/powercontext/commands.py index 19baec8cb..5c1f7b08b 100644 --- a/integrations/hermes/plugins/powercontext/commands.py +++ b/integrations/hermes/plugins/powercontext/commands.py @@ -30,7 +30,6 @@ config_value, ) from .operations import OPERATION_REQUIRED_FIELDS, OPERATION_TOOL_MAP -from .workstream import clear_scope, write_scope try: from tools.registry import tool_error # ty: ignore[unresolved-import] @@ -58,7 +57,7 @@ def tool_error(message: str) -> str: "skill", "external-skills", "review", - "workstream", + "scope", "trace", "call", ) @@ -200,14 +199,13 @@ def _split_json_argument(raw_args: str, command: str, label: str) -> tuple[str, return json_text, tail[end:].lstrip() -def workstream_command(provider: Any, args: list[str]) -> str: +def scope_command(provider: Any, args: list[str]) -> str: action = args[0].lower() if args else "status" if action == "status": return json.dumps( { - "cwd": provider._workstream_cwd, - "path": str(provider._workstream_path) if provider._workstream_path else None, - "bound_scope_id": provider._workstream_bound_scope or None, + "cwd": provider._scope_binding_cwd, + "bound_scope_id": provider._bound_scope_id or None, "active_scope_id": provider._scope_id, }, ensure_ascii=False, @@ -215,28 +213,25 @@ def workstream_command(provider: Any, args: list[str]) -> str: ) if action == "bind": if len(args) < 2 or not args[1].strip(): - return tool_error("Usage: /pc workstream bind SCOPE_ID") + return tool_error("Usage: /pc scope bind SCOPE_ID") try: - path = write_scope(provider._workstream_cwd, args[1]) - except (OSError, ValueError) as error: + provider._bind_workspace_scope(args[1].strip()) + except (PowerContextError, ValueError) as error: return tool_error(str(error)) - from .helpers import safe_scope - - provider._workstream_bound_scope = safe_scope(args[1]) - provider._switch_workstream_scope(provider._workstream_bound_scope) - provider._record_trace_event("workstream_bound", scope_id=provider._scope_id, path=str(path)) + provider._record_trace_event("scope_bound", scope_id=provider._scope_id) return json.dumps( - {"status": "bound", "scope_id": provider._scope_id, "path": str(path)}, + {"status": "bound", "scope_id": provider._scope_id}, ensure_ascii=False, indent=2, ) if action == "clear": - cleared = clear_scope(provider._workstream_cwd) - provider._workstream_bound_scope = "" - provider._switch_workstream_scope(provider._default_scope_id) - provider._record_trace_event("workstream_cleared", cleared=cleared) + try: + cleared = provider._clear_workspace_scope() + except PowerContextError as error: + return tool_error(str(error)) + provider._record_trace_event("scope_binding_cleared", cleared=cleared) return json.dumps({"status": "cleared" if cleared else "not_found"}, ensure_ascii=False, indent=2) - return "Usage: /pc workstream {status|bind SCOPE_ID|clear}" + return "Usage: /pc scope {status|bind SCOPE_ID|clear}" def operation_command(provider: Any, operation: str, args: list[str]) -> str: @@ -379,7 +374,7 @@ def status_command(provider: Any) -> str: result: dict[str, Any] = { "scope_id": provider._scope_id, "session_id": provider._session_id, - "workstream_scope_id": provider._workstream_bound_scope or None, + "bound_scope_id": provider._bound_scope_id or None, } if provider._client: for name, method_name in (("liveness", "get_liveness"), ("readiness", "get_readiness")): @@ -432,9 +427,9 @@ def handle_slash_command(provider: Any, raw_args: str) -> str: # noqa: C901 if not args or args[0].lower() in {"help", "-h", "--help"}: return ( "Usage: /pc {status|search|list|changes|get|remember|revise|retire|flush|stats|" - "handoff|experience|skill|external-skills|review|workstream|trace|call} ...\n" + "handoff|experience|skill|external-skills|review|scope|trace|call} ...\n" "Advanced operations accept a JSON payload: /pc call OPERATION PAYLOAD_JSON\n" - "Workstream binding: /pc workstream {status|bind SCOPE_ID|clear}" + "Scope binding: /pc scope {status|bind SCOPE_ID|clear}" ) command = args[0].lower() try: @@ -444,8 +439,8 @@ def handle_slash_command(provider: Any, raw_args: str) -> str: # noqa: C901 return status_command(provider) if command in {"search", "list", "changes", "get", "remember", "revise", "retire", "flush", "stats"}: return memory_command(provider, args) - if command == "workstream": - return workstream_command(provider, args[1:]) + if command == "scope": + return scope_command(provider, args[1:]) if command in {"handoff", "experience", "skill", "external-skills", "review"}: return group_command(provider, command, args[1:]) if command == "call": diff --git a/integrations/hermes/plugins/powercontext/config_schema.py b/integrations/hermes/plugins/powercontext/config_schema.py index 5e89a9a4b..caefcb415 100644 --- a/integrations/hermes/plugins/powercontext/config_schema.py +++ b/integrations/hermes/plugins/powercontext/config_schema.py @@ -48,10 +48,10 @@ ), ProviderField( key="scope_id", - label="Memory scope template", + label="Explicit Scope ID", kind=KIND_TEXT, - default="hermes:{profile}:{user_id}", - description="Supports {profile}, {agent_identity}, {user_id}, and {hermes_home}.", + default="", + description="Optional server-owned Scope selected before durable bindings and the server default.", ), ProviderField( key="max_bytes", @@ -101,12 +101,5 @@ kind=KIND_TEXT, description="Optional directory for per-session evaluation trace files.", ), - ProviderField( - key="workstream_persistence", - label="Git-private Workstream binding", - kind=KIND_BOOL, - default="true", - description="Use the shared .git/powercontext/codex-workspace.json scope binding when present.", - ), ), ) diff --git a/integrations/hermes/plugins/powercontext/helpers.py b/integrations/hermes/plugins/powercontext/helpers.py index 8928f5516..4f2ae75bc 100644 --- a/integrations/hermes/plugins/powercontext/helpers.py +++ b/integrations/hermes/plugins/powercontext/helpers.py @@ -30,7 +30,6 @@ DEFAULT_MAX_BYTES = 8000 DEFAULT_RETRIEVAL_LIMIT = 8 DEFAULT_TIMEOUT = 5.0 -DEFAULT_SCOPE_TEMPLATE = "hermes:{profile}:{user_id}" MAX_TURN_CHARS = 50_000 MAX_PRECOMPRESS_CHARS = 30_000 PRECOMPRESS_ROLES = {"user", "assistant"} @@ -189,16 +188,6 @@ def config_value(config: dict[str, Any], key: str, env_name: str, default: Any = return config.get(key, default) -def format_scope(template: str, *, hermes_home: str, agent_identity: str, user_id: str) -> str: - profile = agent_identity or "default" - user = user_id or hashlib.sha256(str(Path(hermes_home).resolve()).encode()).hexdigest()[:16] - try: - value = template.format(profile=profile, user_id=user, agent_identity=agent_identity, hermes_home=hermes_home) - except (KeyError, ValueError): - value = template - return safe_scope(value) - - def citation_from_args(args: dict[str, Any]) -> dict[str, Any]: required = ("family", "artifact_id", "revision", "entry_id", "entry_version_id") missing = [key for key in required if key not in args] diff --git a/integrations/hermes/plugins/powercontext/provider.py b/integrations/hermes/plugins/powercontext/provider.py index aab5b026b..b2e23ab6f 100644 --- a/integrations/hermes/plugins/powercontext/provider.py +++ b/integrations/hermes/plugins/powercontext/provider.py @@ -41,9 +41,6 @@ from .helpers import ( DEFAULT_MAX_BYTES as _DEFAULT_MAX_BYTES, ) -from .helpers import ( - DEFAULT_SCOPE_TEMPLATE as _DEFAULT_SCOPE_TEMPLATE, -) from .helpers import ( DEFAULT_TIMEOUT as _DEFAULT_TIMEOUT, ) @@ -74,9 +71,6 @@ from .helpers import ( entry_identity as _entry_identity, ) -from .helpers import ( - format_scope as _format_scope, -) from .helpers import ( load_json_config as _load_json_config, ) @@ -96,8 +90,6 @@ redact_secrets as _redact_secrets, ) from .operations import OPERATION_TOOL_MAP as _OPERATION_TOOL_MAP -from .workstream import read_scope as _read_workstream_scope -from .workstream import state_path as _workstream_state_path try: from agent.memory_provider import MemoryProvider, RecallStatus # ty: ignore[unresolved-import] @@ -145,6 +137,13 @@ def _diagnostic_classification( return "invalid_response", None, None +class InvalidScopeBindingError(PowerContextError): + """Raised when the Scope service returns an invalid binding response.""" + + def __init__(self) -> None: + super().__init__("PowerContext returned an invalid Scope binding") + + class PowerContextMemoryProvider(MemoryProvider): """Hermes provider backed by a running PowerContext server.""" @@ -162,6 +161,7 @@ def __init__(self, config: dict[str, Any] | None = None, *, client_factory=None) self._client: PowerContextClient | Any | None = None self._scope_id = "" self._default_scope_id = "" + self._explicit_scope_id: str | None = None self._session_id = "" self._memory_write_queue: queue.Queue[Callable[[], None] | None] | None = None self._memory_write_thread: threading.Thread | None = None @@ -185,9 +185,8 @@ def __init__(self, config: dict[str, Any] | None = None, *, client_factory=None) self._trace_enabled = False self._trace_turn = 0 self._trace_lock = threading.Lock() - self._workstream_cwd = "" - self._workstream_path: Path | None = None - self._workstream_bound_scope = "" + self._scope_binding_cwd = "" + self._bound_scope_id = "" self._diagnostic_last_emitted: dict[str, float] = {} def _emit_failure_diagnostic(self, event: str, error: PowerContextError) -> None: @@ -243,8 +242,8 @@ def get_config_schema(self) -> list[dict[str, Any]]: }, { "key": "scope_id", - "description": "Memory scope template", - "default": _DEFAULT_SCOPE_TEMPLATE, + "description": "Explicit Scope ID (optional)", + "default": "", }, { "key": "max_bytes", @@ -290,12 +289,6 @@ def get_config_schema(self) -> list[dict[str, Any]]: "description": "Directory for per-session evaluation traces", "default": "", }, - { - "key": "workstream_persistence", - "description": "Use the Git-private Workstream scope binding when present", - "default": "true", - "choices": ["true", "false"], - }, ] def save_config(self, values: dict[str, Any], hermes_home: str) -> None: @@ -328,37 +321,25 @@ def initialize(self, session_id: str, **kwargs: Any) -> None: self._precompress_snapshot = [] self._memory_map_path = Path(hermes_home) / "powercontext-memory-map.json" self._memory_map = self._load_memory_map() - self._workstream_cwd = str( + self._scope_binding_cwd = str( kwargs.get("cwd") or kwargs.get("working_directory") or kwargs.get("project_root") or os.getcwd() ) - self._workstream_path = _workstream_state_path(self._workstream_cwd) - self._workstream_bound_scope = "" + self._bound_scope_id = "" agent_identity = str(kwargs.get("agent_identity") or "default") self._profile = agent_identity - user_id = str(kwargs.get("user_id") or "") configured_scope = _config_value(merged_config, "scope_id", "POWERCONTEXT_HERMES_SCOPE_ID") - explicit_scope = ( - configured_scope is not None - and bool(str(configured_scope).strip()) - and str(configured_scope).strip() != _DEFAULT_SCOPE_TEMPLATE - ) - if not explicit_scope and _as_bool( - _config_value(merged_config, "workstream_persistence", "POWERCONTEXT_HERMES_WORKSTREAM", True), - True, - ): - self._workstream_bound_scope = _read_workstream_scope(self._workstream_cwd) or "" - scope_template = str(configured_scope or _DEFAULT_SCOPE_TEMPLATE) - self._default_scope_id = _format_scope( - scope_template, - hermes_home=hermes_home, - agent_identity=agent_identity, - user_id=user_id, - ) - if self._workstream_bound_scope: - self._scope_id = self._workstream_bound_scope - else: - self._scope_id = self._default_scope_id self._client = self._client_factory(merged_config) + explicit_scope_id = None if configured_scope is None else str(configured_scope).strip() or None + self._explicit_scope_id = explicit_scope_id + resolved = self._client.resolve_scope_binding( + explicit_scope_id=explicit_scope_id, + binding_keys=self._scope_binding_keys(), + ) + scope_id = resolved.get("scope_id") + if not isinstance(scope_id, str) or not scope_id.strip() or scope_id != scope_id.strip(): + raise InvalidScopeBindingError + self._default_scope_id = scope_id + self._scope_id = scope_id trace_path = _config_value( merged_config, "evaluation_trace_path", @@ -505,7 +486,7 @@ def _cancel_queued_memory_writes(self) -> int: memory_queue.put_nowait(None) return cancelled - def _switch_workstream_scope(self, scope_id: str) -> None: + def _switch_scope(self, scope_id: str) -> None: """Switch scopes without allowing old queued work to use the new scope.""" old_scope_id = self._scope_id if not scope_id or scope_id == old_scope_id: @@ -543,6 +524,38 @@ def _switch_workstream_scope(self, scope_id: str) -> None: if self._memory_write_queue is memory_queue: self._accept_memory_writes = was_accepting + def _scope_binding_keys(self) -> list[dict[str, str]]: + keys = [] + if self._session_id: + keys.append({"integration": "hermes", "kind": "session", "external_id": self._session_id}) + workspace_id = hashlib.sha256(os.fsencode(Path(self._scope_binding_cwd).resolve(strict=False))).hexdigest() + keys.append({"integration": "hermes", "kind": "workspace", "external_id": workspace_id}) + return keys + + def _bind_workspace_scope(self, scope_id: str) -> None: + response = self._client.set_scope_binding(self._scope_binding_keys()[-1], scope_id) + if response.get("scope_id") != scope_id: + raise InvalidScopeBindingError + self._bound_scope_id = scope_id + self._switch_scope(scope_id) + + def _clear_workspace_scope(self) -> bool: + response = self._client.clear_scope_binding(self._scope_binding_keys()[-1]) + cleared = response.get("cleared") + if not isinstance(cleared, bool): + raise InvalidScopeBindingError + resolved = self._client.resolve_scope_binding( + explicit_scope_id=self._explicit_scope_id, + binding_keys=self._scope_binding_keys(), + ) + scope_id = resolved.get("scope_id") + if not isinstance(scope_id, str) or not scope_id.strip() or scope_id != scope_id.strip(): + raise InvalidScopeBindingError + self._bound_scope_id = "" + self._default_scope_id = scope_id + self._switch_scope(scope_id) + return cleared + def _load_memory_map(self) -> dict[str, dict[str, Any]]: if self._memory_map_path is None: return {} @@ -1044,8 +1057,8 @@ def _request_operation(self, operation: str, payload: dict[str, Any] | None = No def _parse_json_object(value: str, label: str) -> dict[str, Any]: return commands.parse_json_object(value, label) - def _workstream_command(self, args: list[str]) -> str: - return commands.workstream_command(self, args) + def _scope_command(self, args: list[str]) -> str: + return commands.scope_command(self, args) def _operation_command(self, operation: str, args: list[str]) -> str: return commands.operation_command(self, operation, args) diff --git a/integrations/hermes/plugins/powercontext/skills/powercontext/SKILL.md b/integrations/hermes/plugins/powercontext/skills/powercontext/SKILL.md index bb6ca89ef..2fc8e4aa1 100644 --- a/integrations/hermes/plugins/powercontext/skills/powercontext/SKILL.md +++ b/integrations/hermes/plugins/powercontext/skills/powercontext/SKILL.md @@ -53,7 +53,7 @@ fingerprint before import. Use /pc for operational actions and review decisions: - /pc trace ... inspects evaluation traces. -- /pc workstream ... manages the Git-private cross-session scope binding. +- /pc scope ... manages the durable workspace Scope binding in PowerContext. - /pc review ... lists, reads, approves, rejects, or revises candidates. - /pc call OPERATION PAYLOAD_JSON is available for an operation not covered by a short command. diff --git a/integrations/hermes/plugins/powercontext/workstream.py b/integrations/hermes/plugins/powercontext/workstream.py deleted file mode 100644 index 31ace7aa2..000000000 --- a/integrations/hermes/plugins/powercontext/workstream.py +++ /dev/null @@ -1,102 +0,0 @@ -# Copyright (c) 2026 OceanBase. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -"""Git-private Workstream scope binding for the Hermes integration.""" - -from __future__ import annotations - -import json -import os -import subprocess -from pathlib import Path -from shutil import which - -from .helpers import safe_scope - -WORKSTREAM_STATE_SCHEMA = "powercontext.codex-workspace.v1" -WORKSTREAM_STATE_DIRECTORY = "powercontext" -WORKSTREAM_STATE_FILE = "codex-workspace.json" - - -def git_value(cwd: str, *arguments: str) -> str | None: - executable = which("git") - if executable is None: - return None - try: - completed = subprocess.run( # noqa: S603 - executable and arguments are integration-owned. - [executable, *arguments], - cwd=cwd, - check=True, - capture_output=True, - text=True, - timeout=2, - ) - except (OSError, subprocess.SubprocessError): - return None - return completed.stdout.strip() or None - - -def state_path(cwd: str) -> Path | None: - git_directory = git_value(cwd, "rev-parse", "--absolute-git-dir") - if git_directory is None: - return None - return Path(git_directory) / WORKSTREAM_STATE_DIRECTORY / WORKSTREAM_STATE_FILE - - -def read_scope(cwd: str) -> str | None: - path = state_path(cwd) - if path is None: - return None - try: - value = json.loads(path.read_text(encoding="utf-8")) - except (OSError, UnicodeDecodeError, json.JSONDecodeError): - return None - if not isinstance(value, dict) or value.get("schema") != WORKSTREAM_STATE_SCHEMA: - return None - scope_id = value.get("scope_id") - if not isinstance(scope_id, str) or not scope_id.strip() or len(scope_id) > 256: - return None - return safe_scope(scope_id) - - -def write_scope(cwd: str, scope_id: str) -> Path: - path = state_path(cwd) - if path is None: - raise ValueError("Workstream binding requires a Git workspace") # noqa: TRY003 - normalized_scope_id = safe_scope(scope_id) - path.parent.mkdir(parents=True, exist_ok=True) - temporary_path = path.with_name(f".{path.name}.{os.getpid()}.tmp") - try: - temporary_path.write_text( - json.dumps({"schema": WORKSTREAM_STATE_SCHEMA, "scope_id": normalized_scope_id}, separators=(",", ":")) - + "\n", - encoding="utf-8", - ) - os.replace(temporary_path, path) - finally: - temporary_path.unlink(missing_ok=True) - return path - - -def clear_scope(cwd: str) -> bool: - path = state_path(cwd) - if path is None: - return False - try: - path.unlink() - except FileNotFoundError: - return False - except OSError: - return False - return True diff --git a/integrations/langchain/README.md b/integrations/langchain/README.md index f1b490fec..08e588218 100644 --- a/integrations/langchain/README.md +++ b/integrations/langchain/README.md @@ -39,10 +39,13 @@ agent = create_agent( result = await agent.ainvoke( {"messages": [{"role": "user", "content": "How should we deploy this service?"}]}, - context=PowerContextScope(scope_id="git:github.com/acme/api"), + context=PowerContextScope(scope_id="scp_01H..."), ) ``` +If `scope_id` is omitted, the middleware uses the Server's default Scope. An explicit value must name an existing +Server Scope. The adapter does not derive Scope IDs from the repository, working directory, Agent, or prompt. + The middleware changes only the current model request, so recalled context never enters agent state or a checkpointer. Automatic capture is disabled by default. Enable it only when the application's transcript policy permits durable storage of user and model content: `PowerContextMiddleware(auto_capture=True)`. diff --git a/integrations/langchain/src/powercontext_langchain/__init__.py b/integrations/langchain/src/powercontext_langchain/__init__.py index 614c5a500..6fa43e453 100644 --- a/integrations/langchain/src/powercontext_langchain/__init__.py +++ b/integrations/langchain/src/powercontext_langchain/__init__.py @@ -15,13 +15,11 @@ """LangChain middleware integration for PowerContext durable memory.""" from .middleware import PowerContextMiddleware -from .scope import MissingScopeError, PowerContextScope, resolve_scope_id +from .scope import PowerContextScope from .settings import PowerContextLangChainSettings __all__ = [ - "MissingScopeError", "PowerContextLangChainSettings", "PowerContextMiddleware", "PowerContextScope", - "resolve_scope_id", ] diff --git a/integrations/langchain/src/powercontext_langchain/client.py b/integrations/langchain/src/powercontext_langchain/client.py index cabc627d3..126494240 100644 --- a/integrations/langchain/src/powercontext_langchain/client.py +++ b/integrations/langchain/src/powercontext_langchain/client.py @@ -25,8 +25,9 @@ from pydantic import SecretStr from powercontext.client import PowerContextClient +from powercontext.http import ResolveScopeBindingRequest -from .scope import PowerContextScope, resolve_scope_id +from .scope import PowerContextScope from .settings import PowerContextLangChainSettings _SHARED_HTTP_CLIENT: ContextVar[tuple[httpx.AsyncClient, bool] | None] = ContextVar( @@ -39,7 +40,7 @@ class ResolvedConfig: """Effective connection configuration for one middleware operation.""" base_url: str - scope_id: str + scope_id: str | None token: str | None = field(repr=False) timeout: float max_bytes: int @@ -57,7 +58,7 @@ def resolve_config( token = resolved_scope.token if resolved_scope.token is not None else _secret_value(resolved_settings.token) return ResolvedConfig( base_url=(resolved_scope.base_url or resolved_settings.base_url).strip(), - scope_id=resolve_scope_id(resolved_scope.scope_id or resolved_settings.scope_id), + scope_id=_explicit_scope_id(resolved_scope.scope_id or resolved_settings.scope_id), token=token, timeout=resolved_scope.timeout if resolved_scope.timeout is not None else resolved_settings.timeout, max_bytes=resolved_settings.max_bytes, @@ -68,6 +69,22 @@ def _secret_value(secret: SecretStr | None) -> str | None: return secret.get_secret_value() if secret is not None else None +def _explicit_scope_id(value: str | None) -> str | None: + if value is None: + return None + normalized = value.strip() + return normalized or None + + +async def resolve_server_scope(client: PowerContextClient, config: ResolvedConfig) -> str: + """Resolve an explicit or default Server-owned Scope for one operation.""" + + scope = await client.resolve_scope_binding( + ResolveScopeBindingRequest(explicit_scope_id=config.scope_id, binding_keys=[]), + ) + return scope.scope_id + + def open_client(config: ResolvedConfig) -> PowerContextClient: """Return a client for one operation, borrowing a shared HTTP client when installed. @@ -104,4 +121,4 @@ def shared_http_client(client: httpx.AsyncClient, *, trust_transport_security: b _SHARED_HTTP_CLIENT.reset(token) -__all__ = ["ResolvedConfig", "open_client", "resolve_config", "shared_http_client"] +__all__ = ["ResolvedConfig", "open_client", "resolve_config", "resolve_server_scope", "shared_http_client"] diff --git a/integrations/langchain/src/powercontext_langchain/middleware.py b/integrations/langchain/src/powercontext_langchain/middleware.py index 5af944a5d..b1ebcf162 100644 --- a/integrations/langchain/src/powercontext_langchain/middleware.py +++ b/integrations/langchain/src/powercontext_langchain/middleware.py @@ -30,7 +30,7 @@ from powercontext.client import ClientError, ServerResponseError from powercontext.http import CaptureContentSourceRequest, PrepareContextRequest, PreparedContextStatus -from .client import ResolvedConfig, open_client, resolve_config +from .client import open_client, resolve_config, resolve_server_scope from .scope import PowerContextScope _LOGGER = logging.getLogger("powercontext.langchain") @@ -133,12 +133,13 @@ async def aafter_agent( async def _prepare(self, query: str, scope: PowerContextScope | None) -> str | None: try: config = resolve_config(scope) - request = PrepareContextRequest( - scope_id=config.scope_id, - query=query[:_MAX_QUERY_CHARS], - max_bytes=config.max_bytes, - ) async with open_client(config) as client: + scope_id = await resolve_server_scope(client, config) + request = PrepareContextRequest( + scope_id=scope_id, + query=query[:_MAX_QUERY_CHARS], + max_bytes=config.max_bytes, + ) prepared = await client.prepare_context(request) except ValidationError: _LOGGER.debug("PowerContext LangChain recall skipped: request validation failed.") @@ -163,13 +164,14 @@ async def _capture( try: config = resolve_config(scope) content, metadata = _source_content(user_text, assistant_text) - request = CaptureContentSourceRequest( - scope_id=config.scope_id, - source_id=_source_id(config, user_text, assistant_text), - content=content, - metadata=metadata, - ) async with open_client(config) as client: + scope_id = await resolve_server_scope(client, config) + request = CaptureContentSourceRequest( + scope_id=scope_id, + source_id=_source_id(scope_id, user_text, assistant_text), + content=content, + metadata=metadata, + ) await client.capture_content_source(request) except ValidationError: _LOGGER.debug("PowerContext LangChain capture skipped: request validation failed.") @@ -279,9 +281,9 @@ def _source_content(user_text: str, assistant_text: str) -> tuple[str, dict[str, ) -def _source_id(config: ResolvedConfig, user_text: str, assistant_text: str) -> str: +def _source_id(scope_id: str, user_text: str, assistant_text: str) -> str: digest = hashlib.sha256() - for value in (config.scope_id, user_text, assistant_text): + for value in (scope_id, user_text, assistant_text): digest.update(value.encode("utf-8")) digest.update(b"\x00") return f"langchain-agent-turn-{digest.hexdigest()}" diff --git a/integrations/langchain/src/powercontext_langchain/scope.py b/integrations/langchain/src/powercontext_langchain/scope.py index fd145d594..df4195f7e 100644 --- a/integrations/langchain/src/powercontext_langchain/scope.py +++ b/integrations/langchain/src/powercontext_langchain/scope.py @@ -12,31 +12,16 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Invocation scope and stable scope resolution for the LangChain middleware.""" +"""Invocation configuration for the LangChain middleware.""" from __future__ import annotations -import hashlib -import os -import re -import subprocess from dataclasses import dataclass, field -from shutil import which -from urllib.parse import urlsplit - -from powercontext.limits import MAX_SCOPE_ID_LENGTH - -_SCP_REMOTE = re.compile(r"^(?:[^@/\s]+@)?(?P[^:/\s]+):(?P.+)$") @dataclass(frozen=True, slots=True) class PowerContextScope: - """PowerContext configuration for one LangChain agent invocation. - - Pass this value as the ``context`` argument to ``agent.invoke`` or ``agent.ainvoke``. Each invocation of one - agent can use a different scope. Every field is optional; unset fields fall back to the LangChain integration's - environment settings. - """ + """PowerContext connection overrides for one LangChain invocation.""" scope_id: str | None = None base_url: str | None = None @@ -44,90 +29,4 @@ class PowerContextScope: timeout: float | None = None -class MissingScopeError(ValueError): - """Raised when no explicit scope is configured and no Git remote is available.""" - - def __init__(self) -> None: - super().__init__( - "PowerContext scope could not be resolved. Set POWERCONTEXT_LANGCHAIN_SCOPE_ID, pass " - "PowerContextScope(scope_id=...), or run inside a Git repository with a network remote." - ) - - -def resolve_scope_id(scope_id: str | None = None, *, cwd: str | None = None) -> str: - """Return an explicit or Git-derived scope, or raise when neither is available.""" - - explicit = (scope_id or "").strip() - if explicit: - return _bounded_explicit(explicit) - - remote = _git_remote(cwd or os.getcwd()) - normalized_remote = normalize_git_remote(remote) if remote else None - if normalized_remote: - return _bounded("git", normalized_remote) - - raise MissingScopeError - - -def normalize_git_remote(remote: str) -> str | None: - """Normalize common network remotes without retaining credentials.""" - - value = remote.strip() - if not value: - return None - scp_match = _SCP_REMOTE.fullmatch(value) - if scp_match and "://" not in value: - host = scp_match.group("host").lower() - if len(host) == 1 and host.isalpha(): - return None - path = _normalize_path(scp_match.group("path")) - return f"{host}/{path}" if path else None - parsed = urlsplit(value) - if parsed.scheme not in {"http", "https", "ssh", "git"} or parsed.hostname is None: - return None - host = parsed.hostname.lower() - if parsed.port is not None: - host = f"{host}:{parsed.port}" - path = _normalize_path(parsed.path) - return f"{host}/{path}" if path else None - - -def _normalize_path(path: str) -> str: - normalized = "/".join(part for part in path.replace("\\", "/").split("/") if part) - if normalized.endswith(".git"): - normalized = normalized[:-4] - return normalized.rstrip("/") - - -def _bounded(prefix: str, value: str) -> str: - candidate = f"{prefix}:{value}" - if len(candidate) <= MAX_SCOPE_ID_LENGTH: - return candidate - return f"{prefix}:sha256:{hashlib.sha256(value.encode()).hexdigest()}" - - -def _bounded_explicit(value: str) -> str: - if len(value) <= MAX_SCOPE_ID_LENGTH: - return value - return f"sha256:{hashlib.sha256(value.encode()).hexdigest()}" - - -def _git_remote(cwd: str) -> str | None: - executable = which("git") - if executable is None: - return None - try: - completed = subprocess.run( # noqa: S603 - git executable and arguments are integration-owned. - [executable, "config", "--get", "remote.origin.url"], - cwd=cwd, - check=True, - capture_output=True, - text=True, - timeout=2, - ) - except (OSError, subprocess.SubprocessError): - return None - return completed.stdout.strip() or None - - -__all__ = ["MissingScopeError", "PowerContextScope", "normalize_git_remote", "resolve_scope_id"] +__all__ = ["PowerContextScope"] diff --git a/integrations/langgraph/README.md b/integrations/langgraph/README.md index 7d1e62b74..ab4809440 100644 --- a/integrations/langgraph/README.md +++ b/integrations/langgraph/README.md @@ -26,7 +26,7 @@ agent = create_react_agent( context_schema=PowerContextScope, checkpointer=my_checkpointer, ) -await agent.ainvoke(state, context=PowerContextScope(scope_id="git:github.com/acme/api")) +await agent.ainvoke(state, context=PowerContextScope()) ``` The recall hook and the Memory tools are async, so drive the graph with `ainvoke`/`astream`; a synchronous @@ -58,7 +58,7 @@ builder.add_edge(START, "recall") builder.add_edge("recall", "model") graph = builder.compile(checkpointer=my_checkpointer) -await graph.ainvoke(state, context=PowerContextScope(scope_id="git:github.com/acme/api")) +await graph.ainvoke(state, context=PowerContextScope()) ``` ## Installation @@ -82,7 +82,7 @@ Configuration is read through pydantic-settings with the prefix `POWERCONTEXT_LA | --- | --- | --- | | `POWERCONTEXT_LANGGRAPH_BASE_URL` | `http://127.0.0.1:8000` | PowerContext Server URL | | `POWERCONTEXT_LANGGRAPH_TOKEN` | unset | Bearer token forwarded to `PowerContextClient` | -| `POWERCONTEXT_LANGGRAPH_SCOPE_ID` | derived | Durable scope shared across runs | +| `POWERCONTEXT_LANGGRAPH_SCOPE_ID` | unset | Existing Server Scope to use instead of the Server default | | `POWERCONTEXT_LANGGRAPH_TIMEOUT` | `10` | Client timeout in seconds | | `POWERCONTEXT_LANGGRAPH_MAX_BYTES` | `8000` | Prepared-context size limit | @@ -92,16 +92,14 @@ Configuration is read through pydantic-settings with the prefix `POWERCONTEXT_LA ## Scope resolution -The scope for a run is resolved in this order: +The adapter asks the Server to resolve the Scope for every operation: -1. an explicit `scope_id` on `PowerContextScope`, or `POWERCONTEXT_LANGGRAPH_SCOPE_ID`; -2. a scope derived from the current Git remote; -3. otherwise the adapter raises. +1. an explicit, existing `scope_id` on `PowerContextScope`, or `POWERCONTEXT_LANGGRAPH_SCOPE_ID`; +2. otherwise the Server default Scope. -This priority is inverted relative to the Codex plugin. A LangGraph deployment is typically a long-running service in -which the working directory has no relationship to the project, so explicit configuration is the primary path and Git -derivation is the fallback. When neither is available the adapter raises rather than defaulting to a shared local -scope, which would place unrelated tenants together. +Scope IDs are Server-owned opaque identifiers. The adapter never derives one from the process working directory, a +Git remote, or a filesystem path. An explicit ID is validated by the Server before the operation continues; obtain it +from the Scope API rather than inventing it locally. ## Why this package does not implement `BaseStore` diff --git a/integrations/langgraph/examples/agent_memory_roundtrip.py b/integrations/langgraph/examples/agent_memory_roundtrip.py index 0f75fab69..3be0f7e0d 100644 --- a/integrations/langgraph/examples/agent_memory_roundtrip.py +++ b/integrations/langgraph/examples/agent_memory_roundtrip.py @@ -41,7 +41,6 @@ from powercontext_langgraph import PowerContextRecall, PowerContextScope, powercontext_tools from pydantic import SecretStr -SCOPE_ID = "project:langgraph-agent-roundtrip" AUTH_TOKEN = "example-token" # noqa: S105 - local throwaway Server credential, not a real secret. MEMORY_FACT = "hexagonal architecture for the payment gateway" @@ -87,7 +86,7 @@ async def main(base_url: str) -> int: pre_model_hook=PowerContextRecall(), context_schema=PowerContextScope, ) - scope = PowerContextScope(scope_id=SCOPE_ID, base_url=base_url, token=AUTH_TOKEN) + scope = PowerContextScope(base_url=base_url, token=AUTH_TOKEN) turn1 = await agent.ainvoke( {"messages": [("user", f"Persist this decision to long-term memory verbatim: adopt {MEMORY_FACT}.")]}, diff --git a/integrations/langgraph/examples/inspect_recall.py b/integrations/langgraph/examples/inspect_recall.py index 8a7138c7b..89c2264e8 100644 --- a/integrations/langgraph/examples/inspect_recall.py +++ b/integrations/langgraph/examples/inspect_recall.py @@ -35,9 +35,8 @@ from typing_extensions import TypedDict from powercontext.client import PowerContextClient -from powercontext.http import RememberMemoryRequest +from powercontext.http import RememberMemoryRequest, ResolveScopeBindingRequest -SCOPE_ID = "project:langgraph-inspect-recall" SEED_TEXT = "Adopt hexagonal architecture for the payment gateway." @@ -55,12 +54,13 @@ def _build_graph(): async def main(base_url: str) -> None: - scope = PowerContextScope(scope_id=SCOPE_ID, base_url=base_url) + scope = PowerContextScope(base_url=base_url) async with PowerContextClient(base_url) as client: + scope_id = (await client.resolve_scope_binding(ResolveScopeBindingRequest())).scope_id await client.remember_memory( RememberMemoryRequest( - scope_id=SCOPE_ID, + scope_id=scope_id, kind="decision", text=SEED_TEXT, reason="example seed", diff --git a/integrations/langgraph/src/powercontext_langgraph/__init__.py b/integrations/langgraph/src/powercontext_langgraph/__init__.py index d313f077d..c9d9fb0ab 100644 --- a/integrations/langgraph/src/powercontext_langgraph/__init__.py +++ b/integrations/langgraph/src/powercontext_langgraph/__init__.py @@ -17,12 +17,11 @@ from __future__ import annotations from .recall import PowerContextRecall -from .scope import MissingScopeError, PowerContextScope, resolve_scope_id +from .scope import PowerContextScope from .settings import PowerContextLangGraphSettings from .tools import powercontext_context, powercontext_remember, powercontext_search, powercontext_tools __all__ = [ - "MissingScopeError", "PowerContextLangGraphSettings", "PowerContextRecall", "PowerContextScope", @@ -30,5 +29,4 @@ "powercontext_remember", "powercontext_search", "powercontext_tools", - "resolve_scope_id", ] diff --git a/integrations/langgraph/src/powercontext_langgraph/client.py b/integrations/langgraph/src/powercontext_langgraph/client.py index dbcce69b1..35401971c 100644 --- a/integrations/langgraph/src/powercontext_langgraph/client.py +++ b/integrations/langgraph/src/powercontext_langgraph/client.py @@ -25,8 +25,9 @@ from pydantic import SecretStr from powercontext.client import PowerContextClient +from powercontext.http import ResolveScopeBindingRequest -from .scope import PowerContextScope, resolve_scope_id +from .scope import PowerContextScope from .settings import PowerContextLangGraphSettings # A shared HTTP client lets a long-running deployment reuse one connection pool across nodes and tools, and lets tests @@ -44,7 +45,7 @@ class ResolvedConfig: """Effective connection configuration for one operation.""" base_url: str - scope_id: str + scope_id: str | None # Plain bearer token forwarded to the client for the ``Authorization`` header; hidden from the repr so it never # surfaces in a traceback or trace of the resolved configuration. token: str | None = field(repr=False) @@ -57,7 +58,7 @@ def resolve_config( *, settings: PowerContextLangGraphSettings | None = None, ) -> ResolvedConfig: - """Overlay an optional run scope onto the environment settings and resolve the scope id.""" + """Overlay an optional run scope onto the environment settings.""" resolved_settings = settings or PowerContextLangGraphSettings() scope = scope or PowerContextScope() @@ -66,7 +67,7 @@ def resolve_config( token = scope.token if scope.token is not None else _secret_value(resolved_settings.token) return ResolvedConfig( base_url=(scope.base_url or resolved_settings.base_url).strip(), - scope_id=resolve_scope_id(scope.scope_id or resolved_settings.scope_id), + scope_id=_explicit_scope_id(scope.scope_id or resolved_settings.scope_id), token=token, timeout=scope.timeout if scope.timeout is not None else resolved_settings.timeout, max_bytes=resolved_settings.max_bytes, @@ -77,6 +78,22 @@ def _secret_value(secret: SecretStr | None) -> str | None: return secret.get_secret_value() if secret is not None else None +def _explicit_scope_id(value: str | None) -> str | None: + if value is None: + return None + normalized = value.strip() + return normalized or None + + +async def resolve_server_scope(client: PowerContextClient, config: ResolvedConfig) -> str: + """Resolve an explicit or default Server-owned Scope for one operation.""" + + scope = await client.resolve_scope_binding( + ResolveScopeBindingRequest(explicit_scope_id=config.scope_id, binding_keys=[]), + ) + return scope.scope_id + + def open_client(config: ResolvedConfig) -> PowerContextClient: """Open an async client for one operation. The caller closes it with ``async with``. @@ -115,3 +132,6 @@ def shared_http_client(client: httpx.AsyncClient, *, trust_transport_security: b yield finally: _SHARED_HTTP_CLIENT.reset(token) + + +__all__ = ["ResolvedConfig", "open_client", "resolve_config", "resolve_server_scope", "shared_http_client"] diff --git a/integrations/langgraph/src/powercontext_langgraph/recall.py b/integrations/langgraph/src/powercontext_langgraph/recall.py index 22d3c425d..119e92697 100644 --- a/integrations/langgraph/src/powercontext_langgraph/recall.py +++ b/integrations/langgraph/src/powercontext_langgraph/recall.py @@ -25,7 +25,7 @@ from powercontext.client import ClientError, ServerResponseError from powercontext.http import PrepareContextRequest, PreparedContextStatus -from .client import ResolvedConfig, open_client, resolve_config +from .client import ResolvedConfig, open_client, resolve_config, resolve_server_scope from .runtime import current_scope _LOGGER = logging.getLogger("powercontext.langgraph") @@ -91,18 +91,11 @@ async def _prepare_once(self, messages: list[BaseMessage], query: str) -> str | try: config = resolve_config(current_scope()) except Exception as exc: - # Config/scope resolution is part of the fail-open boundary: a malformed setting (ValidationError) or an - # unresolvable scope (MissingScopeError) must skip recall, not interrupt the graph. Logged once so a - # misconfigured deployment is diagnosable rather than silently context-free. + # Settings resolution is part of the fail-open boundary: malformed configuration must skip recall, not + # interrupt the graph. Logged once so a misconfigured deployment is diagnosable. self._log_config_failure(exc) return None - key = _turn_key(config.scope_id, messages, query) - if key is not None and key in self._turn_cache: - return self._turn_cache[key] - content = await self._prepare(config, query) - if key is not None: - self._remember_turn(key, content) - return content + return await self._prepare(config, messages, query) def _remember_turn(self, key: str, content: str | None) -> None: cache = self._turn_cache @@ -110,12 +103,16 @@ def _remember_turn(self, key: str, content: str | None) -> None: while len(cache) > _TURN_CACHE_LIMIT: del cache[next(iter(cache))] - async def _prepare(self, config: ResolvedConfig, query: str) -> str | None: + async def _prepare(self, config: ResolvedConfig, messages: list[BaseMessage], query: str) -> str | None: try: - request = PrepareContextRequest( - scope_id=config.scope_id, query=query[:_MAX_QUERY_CHARS], max_bytes=config.max_bytes - ) async with open_client(config) as client: + scope_id = await resolve_server_scope(client, config) + key = _turn_key(scope_id, messages, query) + if key is not None and key in self._turn_cache: + return self._turn_cache[key] + request = PrepareContextRequest( + scope_id=scope_id, query=query[:_MAX_QUERY_CHARS], max_bytes=config.max_bytes + ) prepared = await client.prepare_context(request) except ValidationError: # Request construction is inside the fail-open boundary: an out-of-range field must skip recall, not @@ -130,9 +127,10 @@ async def _prepare(self, config: ResolvedConfig, query: str) -> str | None: # unexpected client fault must fail open rather than interrupt graph execution. _LOGGER.debug("PowerContext recall skipped after an unexpected error.", exc_info=True) return None - if prepared.status == PreparedContextStatus.EMPTY: - return None - return prepared.content + content = None if prepared.status == PreparedContextStatus.EMPTY else prepared.content + if key is not None: + self._remember_turn(key, content) + return content def _log_failure(self, exc: ClientError) -> None: if ( @@ -152,8 +150,7 @@ def _log_config_failure(self, exc: Exception) -> None: if not self._config_failure_logged: self._config_failure_logged = True _LOGGER.error( - "PowerContext recall skipped: configuration could not be resolved (%s). Set " - "POWERCONTEXT_LANGGRAPH_SCOPE_ID, pass PowerContextScope(scope_id=...), or correct the " + "PowerContext recall skipped: configuration could not be resolved (%s). Correct the " "POWERCONTEXT_LANGGRAPH_* settings.", type(exc).__name__, ) diff --git a/integrations/langgraph/src/powercontext_langgraph/scope.py b/integrations/langgraph/src/powercontext_langgraph/scope.py index 382adab20..7c98c567d 100644 --- a/integrations/langgraph/src/powercontext_langgraph/scope.py +++ b/integrations/langgraph/src/powercontext_langgraph/scope.py @@ -12,42 +12,25 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Run-scoped configuration and stable scope resolution for one LangGraph run. - -:class:`PowerContextScope` is the run-scoped configuration passed through the graph ``context_schema``. -:func:`resolve_scope_id` turns an explicit or Git-derived value into a bounded scope id. The priority is inverted -relative to the Codex plugin. A LangGraph deployment is typically a long-running service in which the working -directory has no relationship to the project, so an explicit scope is the primary path and Git derivation is the -fallback. When neither is available the adapter raises rather than defaulting to a shared local scope, which would -place unrelated tenants together. -""" +"""Run-scoped connection configuration for one LangGraph run.""" from __future__ import annotations -import hashlib -import os -import re -import subprocess from dataclasses import dataclass, field -from shutil import which -from urllib.parse import urlsplit - -from powercontext.limits import MAX_SCOPE_ID_LENGTH - -_SCP_REMOTE = re.compile(r"^(?:[^@/\s]+@)?(?P[^:/\s]+):(?P.+)$") @dataclass(frozen=True, slots=True) class PowerContextScope: - """Durable scope for one graph run. + """PowerContext connection overrides for one graph run. LangGraph 1.x passes run-scoped configuration through ``context_schema``, which nodes receive as ``Runtime[ContextT]``. Supplying this dataclass makes the scope an explicit invocation argument:: - await graph.ainvoke(state, context=PowerContextScope(scope_id="git:github.com/acme/api")) + await graph.ainvoke(state, context=PowerContextScope()) - Separate invocations of one compiled graph can carry separate scopes, which supports multi-tenant - deployment directly. Every field is optional; unset fields fall back to the environment settings. + Separate invocations of one compiled graph can carry separate explicit scopes. When ``scope_id`` is omitted, + the Server default Scope is used. Every connection field is optional; unset fields fall back to environment + settings. """ scope_id: str | None = None @@ -58,90 +41,4 @@ class PowerContextScope: timeout: float | None = None -class MissingScopeError(ValueError): - """Raised when no explicit scope is configured and no Git remote is available.""" - - def __init__(self) -> None: - super().__init__( - "PowerContext scope could not be resolved. Set POWERCONTEXT_LANGGRAPH_SCOPE_ID, pass " - "PowerContextScope(scope_id=...), or run inside a Git repository with a network remote." - ) - - -def resolve_scope_id(scope_id: str | None = None, *, cwd: str | None = None) -> str: - """Return an explicit or Git-derived scope, or raise when neither is available.""" - - explicit = (scope_id or "").strip() - if explicit: - return _bounded_explicit(explicit) - - remote = _git_remote(cwd or os.getcwd()) - normalized_remote = normalize_git_remote(remote) if remote else None - if normalized_remote: - return _bounded("git", normalized_remote) - - raise MissingScopeError - - -def normalize_git_remote(remote: str) -> str | None: - """Normalize common network remotes without retaining credentials.""" - - value = remote.strip() - if not value: - return None - scp_match = _SCP_REMOTE.fullmatch(value) - if scp_match and "://" not in value: - host = scp_match.group("host").lower() - # A single-character host is a Windows drive letter (``C:\repo`` / ``C:/repo``): a machine-local path, not a - # network remote. Binding a tenant scope to a local drive would place unrelated runs together, so it yields - # no scope and the caller raises MissingScopeError. - if len(host) == 1 and host.isalpha(): - return None - path = _normalize_path(scp_match.group("path")) - return f"{host}/{path}" if path else None - parsed = urlsplit(value) - if parsed.scheme not in {"http", "https", "ssh", "git"} or parsed.hostname is None: - return None - host = parsed.hostname.lower() - if parsed.port is not None: - host = f"{host}:{parsed.port}" - path = _normalize_path(parsed.path) - return f"{host}/{path}" if path else None - - -def _normalize_path(path: str) -> str: - normalized = "/".join(part for part in path.replace("\\", "/").split("/") if part) - if normalized.endswith(".git"): - normalized = normalized[:-4] - return normalized.rstrip("/") - - -def _bounded(prefix: str, value: str) -> str: - candidate = f"{prefix}:{value}" - if len(candidate) <= MAX_SCOPE_ID_LENGTH: - return candidate - return f"{prefix}:sha256:{hashlib.sha256(value.encode()).hexdigest()}" - - -def _bounded_explicit(value: str) -> str: - if len(value) <= MAX_SCOPE_ID_LENGTH: - return value - return f"sha256:{hashlib.sha256(value.encode()).hexdigest()}" - - -def _git_remote(cwd: str) -> str | None: - executable = which("git") - if executable is None: - return None - try: - completed = subprocess.run( # noqa: S603 - git executable and arguments are integration-owned. - [executable, "config", "--get", "remote.origin.url"], - cwd=cwd, - check=True, - capture_output=True, - text=True, - timeout=2, - ) - except (OSError, subprocess.SubprocessError): - return None - return completed.stdout.strip() or None +__all__ = ["PowerContextScope"] diff --git a/integrations/langgraph/src/powercontext_langgraph/tools.py b/integrations/langgraph/src/powercontext_langgraph/tools.py index 3541bed37..fabc7cf57 100644 --- a/integrations/langgraph/src/powercontext_langgraph/tools.py +++ b/integrations/langgraph/src/powercontext_langgraph/tools.py @@ -29,7 +29,7 @@ from powercontext.client import ClientError from powercontext.http import PrepareContextRequest, RememberMemoryRequest, SearchMemoryRequest -from .client import open_client, resolve_config +from .client import open_client, resolve_config, resolve_server_scope from .runtime import current_scope # The public ``query`` contract caps a search or prepare request at this many characters. A model can emit more, @@ -54,8 +54,9 @@ async def powercontext_search(query: str, limit: int = 5) -> str: try: config = resolve_config(current_scope()) - request = SearchMemoryRequest(scope_id=config.scope_id, query=query[:_MAX_QUERY_CHARS], limit=limit) async with open_client(config) as client: + scope_id = await resolve_server_scope(client, config) + request = SearchMemoryRequest(scope_id=scope_id, query=query[:_MAX_QUERY_CHARS], limit=limit) response = await client.search_memory(request) except ValidationError: return _invalid_arguments() @@ -85,8 +86,9 @@ async def powercontext_remember(text: str, kind: str = "agent-note", reason: str try: config = resolve_config(current_scope()) - request = RememberMemoryRequest(scope_id=config.scope_id, kind=kind, text=text, reason=reason) async with open_client(config) as client: + scope_id = await resolve_server_scope(client, config) + request = RememberMemoryRequest(scope_id=scope_id, kind=kind, text=text, reason=reason) response = await client.remember_memory(request) except ValidationError: return _invalid_arguments() @@ -105,10 +107,11 @@ async def powercontext_context(query: str) -> str: try: config = resolve_config(current_scope()) - request = PrepareContextRequest( - scope_id=config.scope_id, query=query[:_MAX_QUERY_CHARS], max_bytes=config.max_bytes - ) async with open_client(config) as client: + scope_id = await resolve_server_scope(client, config) + request = PrepareContextRequest( + scope_id=scope_id, query=query[:_MAX_QUERY_CHARS], max_bytes=config.max_bytes + ) response = await client.prepare_context(request) except ValidationError: return _invalid_arguments() @@ -136,7 +139,6 @@ def _invalid_arguments() -> str: def _unavailable() -> str: - # A configuration or unexpected fault (an unresolvable scope, a malformed base URL, or any other client error - # outside ClientError) prevented the call. Report it as a tool result so the model can proceed rather than - # aborting the graph. + # A configuration or unexpected fault outside ClientError prevented the call. Report it as a tool result so the + # model can proceed rather than aborting the graph. return "(PowerContext unavailable: the request could not be completed)" diff --git a/integrations/openclaw/README.md b/integrations/openclaw/README.md index c5b14bcd8..ac0d744c0 100644 --- a/integrations/openclaw/README.md +++ b/integrations/openclaw/README.md @@ -42,10 +42,10 @@ powercontext server run openclaw ``` -To use a Server that actually listens on another port, or to change the memory scope during setup: +To use a Server that actually listens on another port: ```bash -powercontext setup openclaw --server-url http://127.0.0.1:9000 --scope-mode project +powercontext setup openclaw --server-url http://127.0.0.1:9000 ``` Run `setup openclaw` again to refresh an existing installation. @@ -71,9 +71,21 @@ The plugin exposes five tools: `powercontext_memory_search`, `powercontext_memor ## Memory scope -Scope mode defaults to `agent`, which derives the memory scope from the OpenClaw agent identity. Project scope is used -only when OpenClaw supplies exactly one trusted project identity for a turn. Set an explicit `--scope-mode` when the -memory must be shared across agents in the same project or isolated differently. +The plugin asks the Server to resolve one existing Scope before every operation. Resolution uses an explicit +`scopeId`, then durable bindings for the OpenClaw session, ordered active projects, and agent identity, followed by +the Server's default Scope. These host identities are lookup inputs only; the plugin never turns an agent, project, +path, or session into a Scope ID and never creates a Scope. + +To select an existing Scope explicitly for every OpenClaw operation, configure its opaque ID and restart the Gateway: + +```bash +openclaw config set plugins.entries.memory-powercontext.config.scopeId scp_0123456789abcdefghjkmnpqrs +openclaw gateway restart +``` + +Without `scopeId`, provision durable bindings on the Server when the host identity must retain a selection; otherwise +the ordinary Server default is used. The plugin does not persist bindings because OpenClaw currently exposes no Scope +selection contract. ## Connect to an authenticated Server diff --git a/integrations/openclaw/plugins/memory-powercontext/index.ts b/integrations/openclaw/plugins/memory-powercontext/index.ts index c7c1daa3a..c01084c44 100644 --- a/integrations/openclaw/plugins/memory-powercontext/index.ts +++ b/integrations/openclaw/plugins/memory-powercontext/index.ts @@ -140,7 +140,9 @@ export default definePluginEntry({ ); return; } - api.logger.info(`memory-powercontext: configured (${config.scopeMode} scope)`); + api.logger.info( + `memory-powercontext: configured (${config.scopeId ? "explicit" : "server-resolved"} scope)`, + ); }, stop: async () => { managers.clear(); diff --git a/integrations/openclaw/plugins/memory-powercontext/openclaw.plugin.json b/integrations/openclaw/plugins/memory-powercontext/openclaw.plugin.json index 329230b2d..705b64fc6 100644 --- a/integrations/openclaw/plugins/memory-powercontext/openclaw.plugin.json +++ b/integrations/openclaw/plugins/memory-powercontext/openclaw.plugin.json @@ -77,13 +77,11 @@ "maximum": 20000, "default": 4000 }, - "scopeMode": { + "scopeId": { "type": "string", - "enum": [ - "agent", - "project" - ], - "default": "agent" + "minLength": 1, + "maxLength": 256, + "pattern": ".*\\S.*" } } }, @@ -96,9 +94,9 @@ "label": "PowerContext Token Environment Variable", "help": "Environment variable containing the Bearer token, read by the Gateway process." }, - "scopeMode": { - "label": "Memory Scope", - "help": "Agent scope is the default. Project scope is used only when OpenClaw supplies exactly one trusted project identity for a turn." + "scopeId": { + "label": "Explicit Scope ID", + "help": "Optional existing PowerContext Scope. When unset, the Server resolves durable OpenClaw bindings and then its default Scope." } } } diff --git a/integrations/openclaw/plugins/memory-powercontext/pnpm-workspace.yaml b/integrations/openclaw/plugins/memory-powercontext/pnpm-workspace.yaml index 7b13d9ae4..5d53d6f75 100644 --- a/integrations/openclaw/plugins/memory-powercontext/pnpm-workspace.yaml +++ b/integrations/openclaw/plugins/memory-powercontext/pnpm-workspace.yaml @@ -13,6 +13,9 @@ # limitations under the License. +packages: + - . + allowBuilds: '@google/genai': false openclaw: false diff --git a/integrations/openclaw/plugins/memory-powercontext/scripts/configure-openclaw.py b/integrations/openclaw/plugins/memory-powercontext/scripts/configure-openclaw.py old mode 100755 new mode 100644 index 9e95d84c8..f4ff839e8 --- a/integrations/openclaw/plugins/memory-powercontext/scripts/configure-openclaw.py +++ b/integrations/openclaw/plugins/memory-powercontext/scripts/configure-openclaw.py @@ -57,13 +57,6 @@ def build_parser() -> argparse.ArgumentParser: default="http://127.0.0.1:8000", help="PowerContext Server URL for enable", ) - parser.add_argument( - "scope_mode", - nargs="?", - default="agent", - choices=("agent", "project"), - help="memory scope for enable", - ) return parser @@ -73,7 +66,7 @@ def main(argv: Sequence[str] | None = None) -> int: openclaw = find_openclaw() if args.action == "enable": require_supported_openclaw(openclaw) - enable(openclaw, args.endpoint, args.scope_mode) + enable(openclaw, args.endpoint) elif args.action == "disable": disable(openclaw) elif args.action == "off": @@ -113,14 +106,13 @@ def require_supported_openclaw(executable: str) -> str: return version_text -def enable(executable: str, endpoint: str, scope_mode: str) -> None: +def enable(executable: str, endpoint: str) -> None: normalized_endpoint = normalize_endpoint(endpoint) settings = [ {"path": "plugins.entries.memory-powercontext.enabled", "value": True}, {"path": "plugins.entries.memory-powercontext.config.endpoint", "value": normalized_endpoint}, {"path": "plugins.entries.memory-powercontext.config.autoRecall", "value": True}, {"path": "plugins.entries.memory-powercontext.config.autoCapture", "value": True}, - {"path": "plugins.entries.memory-powercontext.config.scopeMode", "value": scope_mode}, {"path": "plugins.entries.memory-powercontext.hooks.allowConversationAccess", "value": True}, {"path": "plugins.slots.memory", "value": "memory-powercontext"}, ] diff --git a/integrations/openclaw/plugins/memory-powercontext/src/config.test.ts b/integrations/openclaw/plugins/memory-powercontext/src/config.test.ts index 549b5f750..919702c6a 100644 --- a/integrations/openclaw/plugins/memory-powercontext/src/config.test.ts +++ b/integrations/openclaw/plugins/memory-powercontext/src/config.test.ts @@ -16,20 +16,12 @@ import { describe, expect, it } from "vitest"; -import { resolvePowerContextConfig, resolvePowerContextScope } from "./config.js"; +import { resolvePowerContextConfig } from "./config.js"; -describe("PowerContext scope resolution", () => { - it("isolates agents without using a raw session key", () => { - const config = resolvePowerContextConfig(undefined, { scopeMode: "agent" }); - expect(resolvePowerContextScope("Research Agent", config)).toBe("openclaw:agent:Research%20Agent"); - }); +describe("PowerContext config", () => { + it("normalizes an explicit Scope ID", () => { + const config = resolvePowerContextConfig(undefined, { scopeId: " scp_existing " }); - it("uses a stable opaque project identity only for one trusted project", () => { - const config = resolvePowerContextConfig(undefined, { scopeMode: "project" }); - const first = resolvePowerContextScope("main", config, ["/workspace/project"]); - const second = resolvePowerContextScope("main", config, ["/workspace/project"]); - expect(first).toBe(second); - expect(first).toMatch(/^openclaw:agent:main:project:[0-9a-f]{32}$/u); - expect(resolvePowerContextScope("main", config, ["/a", "/b"])).toBe("openclaw:agent:main"); + expect(config.scopeId).toBe("scp_existing"); }); }); diff --git a/integrations/openclaw/plugins/memory-powercontext/src/config.ts b/integrations/openclaw/plugins/memory-powercontext/src/config.ts index f5f45cbd5..4fb1b8b9a 100644 --- a/integrations/openclaw/plugins/memory-powercontext/src/config.ts +++ b/integrations/openclaw/plugins/memory-powercontext/src/config.ts @@ -21,13 +21,13 @@ import { asOptionalRecord } from "openclaw/plugin-sdk/string-coerce-runtime"; export type PowerContextConfig = { endpoint?: string; + scopeId?: string; tokenEnv: string; timeoutMs: number; prepareMaxBytes: number; autoRecall: boolean; autoCapture: boolean; captureMaxChars: number; - scopeMode: "agent" | "project"; }; const DEFAULT_CONFIG: PowerContextConfig = { @@ -37,7 +37,6 @@ const DEFAULT_CONFIG: PowerContextConfig = { autoRecall: true, autoCapture: true, captureMaxChars: 4000, - scopeMode: "agent", }; function readPluginConfig(config: OpenClawConfig | undefined, fallback: unknown): Record { @@ -79,37 +78,20 @@ export function resolvePowerContextConfig( typeof raw.tokenEnv === "string" && /^[A-Za-z_][A-Za-z0-9_]*$/u.test(raw.tokenEnv.trim()) ? raw.tokenEnv.trim() : DEFAULT_CONFIG.tokenEnv; - const scopeMode = raw.scopeMode === "project" ? "project" : DEFAULT_CONFIG.scopeMode; + const scopeId = typeof raw.scopeId === "string" && raw.scopeId.trim() ? raw.scopeId.trim() : undefined; return { ...DEFAULT_CONFIG, ...(endpoint ? { endpoint } : {}), + ...(scopeId ? { scopeId } : {}), tokenEnv, timeoutMs: boundedInteger(raw.timeoutMs, DEFAULT_CONFIG.timeoutMs, 250, 15000), prepareMaxBytes: boundedInteger(raw.prepareMaxBytes, DEFAULT_CONFIG.prepareMaxBytes, 512, 32768), autoRecall: raw.autoRecall !== false, autoCapture: raw.autoCapture !== false, captureMaxChars: boundedInteger(raw.captureMaxChars, DEFAULT_CONFIG.captureMaxChars, 128, 20000), - scopeMode, }; } -function encoded(value: string): string { - return encodeURIComponent(value.trim()); -} - -export function resolvePowerContextScope( - agentId: string, - config: PowerContextConfig, - activeProjectKeys?: readonly string[], -): string { - const agent = encoded(agentId); - if (config.scopeMode !== "project" || activeProjectKeys?.length !== 1) { - return `openclaw:agent:${agent}`; - } - const projectHash = createHash("sha256").update(activeProjectKeys[0]).digest("hex").slice(0, 32); - return `openclaw:agent:${agent}:project:${projectHash}`; -} - export function opaqueSessionId(sessionId: string | undefined, sessionKey: string | undefined): string | undefined { const value = (sessionId ?? sessionKey ?? "").trim(); return value ? createHash("sha256").update(value).digest("hex") : undefined; diff --git a/integrations/openclaw/plugins/memory-powercontext/src/lifecycle.test.ts b/integrations/openclaw/plugins/memory-powercontext/src/lifecycle.test.ts index 7fc25264e..d65d3f5da 100644 --- a/integrations/openclaw/plugins/memory-powercontext/src/lifecycle.test.ts +++ b/integrations/openclaw/plugins/memory-powercontext/src/lifecycle.test.ts @@ -17,9 +17,10 @@ import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry"; import { describe, expect, it } from "vitest"; -import { resolvePowerContextConfig, resolvePowerContextScope } from "./config.js"; +import { resolvePowerContextConfig } from "./config.js"; import { PowerContextRequestError, type PowerContextClient } from "./http.js"; import { registerPowerContextLifecycle } from "./lifecycle.js"; +import { scopeBindingKeys, type ScopeBindingKey } from "./scope.js"; type Hook = (event: unknown, context: unknown) => unknown; @@ -30,14 +31,25 @@ function createLifecycleHarness() { const flushScopes: string[] = []; const capturedScopes: string[] = []; const contextQueries: string[] = []; + const scopeResolutionRequests: Array> = []; let memoryExtraction = true; let contextPrepareError: unknown; let captureError: unknown; let flushError: unknown; const config = resolvePowerContextConfig(undefined, { endpoint: "http://powercontext.test", - scopeMode: "project", }); + const projectScopes = new Map( + [ + ["/workspace/project-a", "scp_project_a"], + ["/workspace/project-b", "scp_project_b"], + ].map(([projectKey, scopeId]) => { + const binding = scopeBindingKeys({ agentId: "main", activeProjectKeys: [projectKey] }).find( + (key) => key.kind === "project", + ); + return [binding!.external_id, scopeId] as const; + }), + ); const client = { async get(path: string): Promise { if (path !== "/v1/capabilities") { @@ -46,6 +58,16 @@ function createLifecycleHarness() { return { memory_extraction: memoryExtraction } as T; }, async post(path: string, body: Record): Promise { + if (path === "/v1/scope-bindings/resolve") { + scopeResolutionRequests.push(body); + const bindingKeys = body.binding_keys as ScopeBindingKey[]; + const projectBinding = bindingKeys.find( + (key) => key.kind === "project" && projectScopes.has(key.external_id), + ); + return { + scope_id: projectBinding ? projectScopes.get(projectBinding.external_id) : "scp_default", + } as T; + } if (path === "/v1/memory/flush") { flushScopes.push(String(body.scope_id)); if (flushError !== undefined) { @@ -109,6 +131,7 @@ function createLifecycleHarness() { setFlushError(error: unknown) { flushError = error; }, + scopeResolutionRequests, warnings, }; } @@ -139,10 +162,7 @@ describe("PowerContext lifecycle", () => { sessionContext, ); - expect(harness.flushScopes).toEqual([ - resolvePowerContextScope("main", harness.config, ["/workspace/project-a"]), - resolvePowerContextScope("main", harness.config, ["/workspace/project-b"]), - ]); + expect(harness.flushScopes).toEqual(["scp_project_a", "scp_project_b"]); expect(harness.warnings).toEqual([]); }); @@ -281,6 +301,27 @@ describe("PowerContext lifecycle", () => { expect(harness.warnings).toEqual([]); }); + it("keeps capture and flush on one resolved Scope during compaction", async () => { + const harness = createLifecycleHarness(); + const beforeCompaction = harness.hooks.get("before_compaction"); + expect(beforeCompaction).toBeDefined(); + + await beforeCompaction!( + { messages: [{ role: "user", content: "remember this" }] }, + { + agentId: "main", + sessionId: "session-1", + sessionKey: "agent:main:telegram:direct:user-1", + activeProjectKeys: ["/workspace/project-a"], + }, + ); + + expect(harness.scopeResolutionRequests).toHaveLength(1); + expect(harness.capturedScopes).toEqual(["scp_project_a"]); + expect(harness.flushScopes).toEqual(["scp_project_a"]); + expect(harness.warnings).toEqual([]); + }); + it("defers flush without dropping captured sources when extraction is unavailable", async () => { const harness = createLifecycleHarness(); const agentEnd = harness.hooks.get("agent_end"); @@ -309,7 +350,7 @@ describe("PowerContext lifecycle", () => { ); await sessionEnd!({ sessionId: context.sessionId, messageCount: 2 }, context); - const scope = resolvePowerContextScope("main", harness.config, context.activeProjectKeys); + const scope = "scp_project_a"; expect(harness.capturedScopes).toEqual([scope]); expect(harness.flushScopes).toEqual([]); expect(harness.debugMessages).toContain( diff --git a/integrations/openclaw/plugins/memory-powercontext/src/lifecycle.ts b/integrations/openclaw/plugins/memory-powercontext/src/lifecycle.ts index 0bafb6004..18905da8c 100644 --- a/integrations/openclaw/plugins/memory-powercontext/src/lifecycle.ts +++ b/integrations/openclaw/plugins/memory-powercontext/src/lifecycle.ts @@ -17,7 +17,7 @@ import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry"; import type { PowerContextConfig } from "./config.js"; -import { opaqueSessionId, resolvePowerContextScope } from "./config.js"; +import { opaqueSessionId } from "./config.js"; import { captureTranscript, deterministicSourceId, @@ -27,6 +27,7 @@ import { } from "./content.js"; import type { PowerContextClient } from "./http.js"; import { createDiagnosticEmitter, failureEvent } from "./diagnostics.js"; +import { resolvePowerContextScope } from "./scope.js"; import { isPowerContextCapabilities, isPreparedContext } from "./types.js"; type LifecycleDependencies = { @@ -75,13 +76,14 @@ export function registerPowerContextLifecycle(api: OpenClawPluginApi, deps: Life ); } }; - const resolveScope = (params: { + const resolveScope = async (params: { agentId: string; sessionId?: string; + sessionKey?: string; activeProjectKeys?: readonly string[]; }) => { const config = deps.getConfig(); - const scopeId = resolvePowerContextScope(params.agentId, config, params.activeProjectKeys); + const scopeId = await resolvePowerContextScope(deps.client, config, params); rememberScope(params.sessionId, scopeId); return scopeId; }; @@ -93,7 +95,7 @@ export function registerPowerContextLifecycle(api: OpenClawPluginApi, deps: Life activeProjectKeys?: readonly string[]; channel?: string; messages: unknown[]; - }) => { + }, resolvedScopeId?: string) => { const config = deps.getConfig(); if ( !config.endpoint || @@ -112,8 +114,9 @@ export function registerPowerContextLifecycle(api: OpenClawPluginApi, deps: Life opaqueSessionId: sessionIdentity, content, }); + const scopeId = resolvedScopeId ?? await resolveScope(params); await deps.client.post("/v1/sources/content", { - scope_id: resolveScope(params), + scope_id: scopeId, source_id: sourceId, content, metadata: { @@ -159,9 +162,10 @@ export function registerPowerContextLifecycle(api: OpenClawPluginApi, deps: Life return undefined; } try { - const scopeId = resolveScope({ + const scopeId = await resolveScope({ agentId, sessionId: ctx.sessionId, + sessionKey: ctx.sessionKey, activeProjectKeys: ctx.activeProjectKeys, }); const prepared = await deps.client.post("/v1/context/prepare", { @@ -216,6 +220,18 @@ export function registerPowerContextLifecycle(api: OpenClawPluginApi, deps: Life if (!agentId || !deps.isPrivateSession(agentId, ctx.sessionKey)) { return; } + let scopeId: string; + try { + scopeId = await resolveScope({ + agentId, + sessionId: ctx.sessionId, + sessionKey: ctx.sessionKey, + activeProjectKeys: ctx.activeProjectKeys, + }); + } catch (error) { + reportFailure("scope_binding", error); + return; + } if (event.messages?.length) { try { await capture({ @@ -225,18 +241,14 @@ export function registerPowerContextLifecycle(api: OpenClawPluginApi, deps: Life activeProjectKeys: ctx.activeProjectKeys, channel: ctx.channel ?? ctx.messageProvider, messages: event.messages, - }); + }, scopeId); } catch (error) { reportFailure("capture_source", error); } } try { if (await canExtractMemory()) { - await flush(resolveScope({ - agentId, - sessionId: ctx.sessionId, - activeProjectKeys: ctx.activeProjectKeys, - })); + await flush(scopeId); } } catch (error) { reportFailure("pre_compaction_flush", error); @@ -249,19 +261,16 @@ export function registerPowerContextLifecycle(api: OpenClawPluginApi, deps: Life if (!agentId || !deps.isPrivateSession(agentId, sessionKey)) { return; } - const config = deps.getConfig(); const observedScopes = sessionScopes.get(event.sessionId); sessionScopes.delete(event.sessionId); - if (!observedScopes?.size && config.scopeMode === "project") { - api.logger.debug?.( - "memory-powercontext: session-end flush skipped because no trusted project scope was observed", - ); - return; - } try { const scopes = observedScopes?.size ? [...observedScopes] - : [resolvePowerContextScope(agentId, config)]; + : [await resolveScope({ + agentId, + sessionId: event.sessionId, + sessionKey, + })]; if (!(await canExtractMemory())) { return; } diff --git a/integrations/openclaw/plugins/memory-powercontext/src/manager.test.ts b/integrations/openclaw/plugins/memory-powercontext/src/manager.test.ts index 974162531..23f60a3bb 100644 --- a/integrations/openclaw/plugins/memory-powercontext/src/manager.test.ts +++ b/integrations/openclaw/plugins/memory-powercontext/src/manager.test.ts @@ -16,7 +16,7 @@ import { describe, expect, it } from "vitest"; -import { resolvePowerContextConfig, resolvePowerContextScope } from "./config.js"; +import { resolvePowerContextConfig } from "./config.js"; import type { PowerContextClient } from "./http.js"; import { PowerContextMemoryManager } from "./manager.js"; import { encodeCitation, type MemoryCitation } from "./types.js"; @@ -30,7 +30,10 @@ const citation: MemoryCitation = { describe("PowerContext memory manager", () => { it("keeps memory_get excerpts within the OpenClaw default budget", async () => { const client = { - async post() { + async post(path: string) { + if (path === "/v1/scope-bindings/resolve") { + return { scope_id: "scp_default" }; + } return { citation, version: 1, @@ -56,11 +59,14 @@ describe("PowerContext memory manager", () => { expect(result.text).not.toContain("line-121"); }); - it("reads citations in the current project scope rather than a cached search scope", async () => { - const postBodies: Array> = []; + it("reads citations in the resolved request Scope rather than a cached search Scope", async () => { + const requests: Array<{ path: string; body: Record }> = []; const client = { async post(path: string, body: Record): Promise { - postBodies.push(body); + requests.push({ path, body }); + if (path === "/v1/scope-bindings/resolve") { + return { scope_id: "scp_search" } as T; + } if (path === "/v1/memory/search") { return { memory: citation.memory_ref, @@ -71,25 +77,21 @@ describe("PowerContext memory manager", () => { return { citation, version: 1, kind: "fact", text: "remembered fact", state: "active" } as T; }, } as unknown as PowerContextClient; - const config = resolvePowerContextConfig(undefined, { - endpoint: "http://powercontext.test", - scopeMode: "project", - }); + const config = resolvePowerContextConfig(undefined, { endpoint: "http://powercontext.test" }); const manager = new PowerContextMemoryManager("main", () => config, client, () => true); - const projectA = ["/workspace/project-a"]; - const projectB = ["/workspace/project-b"]; const [result] = await manager.search("fact", { sessionKey: "agent:main:telegram:direct:user-1", - activeProjectKeys: projectA, + activeProjectKeys: ["/workspace/project-a"], }); await manager.readFile({ relPath: result.path, - scopeId: resolvePowerContextScope("main", config, projectB), + scopeId: "scp_current", }); - expect(postBodies.at(-1)).toMatchObject({ - scope_id: resolvePowerContextScope("main", config, projectB), + expect(requests.at(-1)).toMatchObject({ + path: "/v1/memory/entries/get", + body: { scope_id: "scp_current" }, }); }); }); diff --git a/integrations/openclaw/plugins/memory-powercontext/src/manager.ts b/integrations/openclaw/plugins/memory-powercontext/src/manager.ts index f6255b712..8a73171f6 100644 --- a/integrations/openclaw/plugins/memory-powercontext/src/manager.ts +++ b/integrations/openclaw/plugins/memory-powercontext/src/manager.ts @@ -22,8 +22,8 @@ import type { MemorySearchResult, } from "openclaw/plugin-sdk/memory-core-host-engine-storage"; import type { PowerContextConfig } from "./config.js"; -import { resolvePowerContextScope } from "./config.js"; import type { PowerContextClient } from "./http.js"; +import { resolvePowerContextScope } from "./scope.js"; import { decodeCitation, encodeCitation, @@ -43,7 +43,6 @@ export class PowerContextMemoryManager implements MemorySearchManager { private readonly getConfig: () => PowerContextConfig, private readonly client: PowerContextClient, private readonly isPrivateSession: (agentId: string, sessionKey: string | undefined) => boolean, - private readonly fallbackScopeId?: string, ) {} async search( @@ -65,7 +64,16 @@ export class PowerContextMemoryManager implements MemorySearchManager { return []; } const config = this.getConfig(); - const scopeId = resolvePowerContextScope(this.agentId, config, opts?.activeProjectKeys); + const scopeId = await resolvePowerContextScope( + this.client, + config, + { + agentId: this.agentId, + sessionKey: opts?.sessionKey, + activeProjectKeys: opts?.activeProjectKeys, + }, + opts?.signal, + ); const result = await this.client.post( "/v1/memory/search", { @@ -117,19 +125,10 @@ export class PowerContextMemoryManager implements MemorySearchManager { async readFile(params: { relPath: string; from?: number; lines?: number; scopeId?: string }): Promise { const citation = decodeCitation(params.relPath); - const config = this.getConfig(); const scopeId = params.scopeId ?? this.citationScopes.get(params.relPath) ?? - this.fallbackScopeId ?? - (config.scopeMode === "agent" - ? resolvePowerContextScope(this.agentId, config) - : undefined); - if (!scopeId) { - throw new Error( - "PowerContext project citation is not bound to this manager; run memory_search again", - ); - } + (await resolvePowerContextScope(this.client, this.getConfig(), { agentId: this.agentId })); const entry = await this.client.post("/v1/memory/entries/get", { scope_id: scopeId, citation, @@ -179,7 +178,7 @@ export class PowerContextMemoryManager implements MemorySearchManager { sources: ["memory"], custom: { configured: Boolean(config.endpoint), - scopeMode: config.scopeMode, + explicitScope: Boolean(config.scopeId), }, }; } diff --git a/integrations/openclaw/plugins/memory-powercontext/src/scope.test.ts b/integrations/openclaw/plugins/memory-powercontext/src/scope.test.ts new file mode 100644 index 000000000..6f2c5db73 --- /dev/null +++ b/integrations/openclaw/plugins/memory-powercontext/src/scope.test.ts @@ -0,0 +1,82 @@ +/* + * Copyright (c) 2026 OceanBase. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import { createHash } from "node:crypto"; +import { describe, expect, it } from "vitest"; +import { resolvePowerContextConfig } from "./config.js"; +import type { PowerContextClient } from "./http.js"; +import { resolvePowerContextScope } from "./scope.js"; + +const digest = (value: string) => createHash("sha256").update(value).digest("hex"); + +describe("PowerContext Scope binding", () => { + it("asks the Server to resolve explicit and ordered host bindings", async () => { + const requests: Array<{ path: string; body: Record }> = []; + const client = { + async post(path: string, body: Record): Promise { + requests.push({ path, body }); + return { scope_id: "scp_server_owned" } as T; + }, + } as unknown as PowerContextClient; + const config = resolvePowerContextConfig(undefined, { scopeId: "scp_explicit" }); + + const scopeId = await resolvePowerContextScope(client, config, { + agentId: "main", + sessionKey: "agent:main:telegram:direct:user-1", + activeProjectKeys: ["/workspace/primary", " /workspace/primary ", "/workspace/secondary"], + }); + + expect(scopeId).toBe("scp_server_owned"); + expect(requests).toEqual([ + { + path: "/v1/scope-bindings/resolve", + body: { + explicit_scope_id: "scp_explicit", + binding_keys: [ + { + integration: "openclaw", + kind: "session", + external_id: digest("agent:main:telegram:direct:user-1"), + }, + { + integration: "openclaw", + kind: "project", + external_id: digest("/workspace/primary"), + }, + { + integration: "openclaw", + kind: "project", + external_id: digest("/workspace/secondary"), + }, + { integration: "openclaw", kind: "agent", external_id: "main" }, + ], + }, + }, + ]); + }); + + it("rejects an invalid Server binding response", async () => { + const client = { + async post(): Promise { + return { scope_id: " " } as T; + }, + } as unknown as PowerContextClient; + + await expect( + resolvePowerContextScope(client, resolvePowerContextConfig(undefined), { agentId: "main" }), + ).rejects.toThrow("invalid Scope binding"); + }); +}); diff --git a/integrations/openclaw/plugins/memory-powercontext/src/scope.ts b/integrations/openclaw/plugins/memory-powercontext/src/scope.ts new file mode 100644 index 000000000..6ceb104bd --- /dev/null +++ b/integrations/openclaw/plugins/memory-powercontext/src/scope.ts @@ -0,0 +1,92 @@ +/* + * Copyright (c) 2026 OceanBase. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import { createHash } from "node:crypto"; +import type { PowerContextConfig } from "./config.js"; +import type { PowerContextClient } from "./http.js"; + +export type OpenClawScopeIdentity = { + agentId: string; + sessionKey?: string; + activeProjectKeys?: readonly string[]; +}; + +export type ScopeBindingKey = { + integration: "openclaw"; + kind: "session" | "project" | "agent"; + external_id: string; +}; + +type ScopeDescriptor = { + scope_id: string; +}; + +function normalized(value: string | undefined): string | undefined { + const result = value?.trim(); + return result || undefined; +} + +function opaqueExternalId(value: string): string { + return createHash("sha256").update(value).digest("hex"); +} + +export function scopeBindingKeys(identity: OpenClawScopeIdentity): ScopeBindingKey[] { + const keys: ScopeBindingKey[] = []; + const sessionKey = normalized(identity.sessionKey); + if (sessionKey) { + keys.push({ integration: "openclaw", kind: "session", external_id: opaqueExternalId(sessionKey) }); + } + + const projectIds = new Set(); + for (const projectKey of identity.activeProjectKeys ?? []) { + const project = normalized(projectKey); + if (!project) { + continue; + } + const externalId = opaqueExternalId(project); + if (!projectIds.has(externalId)) { + projectIds.add(externalId); + keys.push({ integration: "openclaw", kind: "project", external_id: externalId }); + } + } + + const agentId = normalized(identity.agentId); + if (agentId) { + keys.push({ integration: "openclaw", kind: "agent", external_id: agentId }); + } + return keys; +} + +export async function resolvePowerContextScope( + client: PowerContextClient, + config: PowerContextConfig, + identity: OpenClawScopeIdentity, + signal?: AbortSignal, +): Promise { + const descriptor = await client.post( + "/v1/scope-bindings/resolve", + { + ...(config.scopeId ? { explicit_scope_id: config.scopeId } : {}), + binding_keys: scopeBindingKeys(identity), + }, + signal, + ); + const scopeId = normalized(descriptor?.scope_id); + if (!scopeId) { + throw new Error("PowerContext returned an invalid Scope binding"); + } + return scopeId; +} diff --git a/integrations/openclaw/plugins/memory-powercontext/src/tools.test.ts b/integrations/openclaw/plugins/memory-powercontext/src/tools.test.ts index 106c2a549..f43d06912 100644 --- a/integrations/openclaw/plugins/memory-powercontext/src/tools.test.ts +++ b/integrations/openclaw/plugins/memory-powercontext/src/tools.test.ts @@ -179,4 +179,39 @@ describe("PowerContext tools", () => { })!.execute("call-3", { text: "fact", kind: "fact" }); expect(invalidRequest.details).toMatchObject({ status: "invalid_request", code: "invalid_request" }); }); + + it("uses the Server-resolved Scope for a memory mutation", async () => { + const requests: Array<{ path: string; body: Record }> = []; + const client = { + async post(path: string, body: Record): Promise { + requests.push({ path, body }); + if (path === "/v1/scope-bindings/resolve") { + return { scope_id: "scp_resolved" } as T; + } + return { + memory: { family: "memory", artifact_id: "artifact-1", revision: 1 }, + entry: null, + } as T; + }, + } as unknown as PowerContextClient; + const context = { + agentId: "main", + sessionKey: "agent:main:telegram:direct:user-1", + activeProjectKeys: ["/workspace/project"], + } as OpenClawPluginToolContext; + const deps = { + client, + getConfig: () => resolvePowerContextConfig(undefined, { endpoint: "http://powercontext.test" }), + isPrivateSession: () => true, + }; + + const result = await createMemoryStoreTool(context, deps)!.execute("call-1", { text: "durable fact" }); + + expect(result.details).toMatchObject({ status: "stored", revision: 1 }); + expect(requests.map((request) => request.path)).toEqual([ + "/v1/scope-bindings/resolve", + "/v1/memory/remember", + ]); + expect(requests[1].body).toMatchObject({ scope_id: "scp_resolved", text: "durable fact" }); + }); }); diff --git a/integrations/openclaw/plugins/memory-powercontext/src/tools.ts b/integrations/openclaw/plugins/memory-powercontext/src/tools.ts index af48a86c7..c34d9c8d0 100644 --- a/integrations/openclaw/plugins/memory-powercontext/src/tools.ts +++ b/integrations/openclaw/plugins/memory-powercontext/src/tools.ts @@ -25,10 +25,10 @@ import { import { Type } from "typebox"; import type { OpenClawPluginToolContext } from "openclaw/plugin-sdk/plugin-entry"; import type { PowerContextConfig } from "./config.js"; -import { resolvePowerContextScope } from "./config.js"; import type { PowerContextClient } from "./http.js"; import { PowerContextRequestError } from "./http.js"; import { PowerContextMemoryManager } from "./manager.js"; +import { resolvePowerContextScope } from "./scope.js"; import { decodeCitation, encodeCitation, @@ -113,11 +113,24 @@ function mutationFailure(error: unknown) { return unavailable(error); } -function resolveToolScope(ctx: OpenClawPluginToolContext, deps: ToolDependencies): string { +async function resolveToolScope( + ctx: OpenClawPluginToolContext, + deps: ToolDependencies, + signal?: AbortSignal, +): Promise { if (!ctx.agentId) { throw new Error("trusted agent identity is unavailable for this turn"); } - return resolvePowerContextScope(ctx.agentId, deps.getConfig(), ctx.activeProjectKeys); + return resolvePowerContextScope( + deps.client, + deps.getConfig(), + { + agentId: ctx.agentId, + sessionKey: ctx.sessionKey, + activeProjectKeys: ctx.activeProjectKeys, + }, + signal, + ); } export function createMemorySearchTool(ctx: OpenClawPluginToolContext, deps: ToolDependencies) { @@ -236,6 +249,7 @@ export function createMemoryGetTool(ctx: OpenClawPluginToolContext, deps: ToolDe error: "PowerContext does not provide the wiki corpus", }); } + const scopeId = await resolveToolScope(ctx, deps); const manager = deps.managerFor?.(ctx) ?? new PowerContextMemoryManager( @@ -243,13 +257,12 @@ export function createMemoryGetTool(ctx: OpenClawPluginToolContext, deps: ToolDe deps.getConfig, deps.client, deps.isPrivateSession, - resolveToolScope(ctx, deps), ); return jsonResult(await manager.readFile({ relPath: path, from: readPositiveIntegerParam(raw, "from"), lines: readPositiveIntegerParam(raw, "lines"), - scopeId: resolveToolScope(ctx, deps), + scopeId, })); } catch (error) { return readUnavailable(path, error); @@ -286,7 +299,7 @@ export function createMemoryStoreTool(ctx: OpenClawPluginToolContext, deps: Tool try { const result = await deps.client.post( "/v1/memory/remember", - { scope_id: resolveToolScope(ctx, deps), kind, text, ...(reason ? { reason } : {}) }, + { scope_id: await resolveToolScope(ctx, deps, signal), kind, text, ...(reason ? { reason } : {}) }, signal, ); return jsonResult({ @@ -338,7 +351,7 @@ export function createMemoryReviseTool(ctx: OpenClawPluginToolContext, deps: Too const result = await deps.client.post( "/v1/memory/entries/revise", { - scope_id: resolveToolScope(ctx, deps), + scope_id: await resolveToolScope(ctx, deps, signal), citation, kind, text, @@ -383,7 +396,7 @@ export function createMemoryRetireTool(ctx: OpenClawPluginToolContext, deps: Too const reason = readStringParam(raw, "reason"); const result = await deps.client.post( "/v1/memory/entries/retire", - { scope_id: resolveToolScope(ctx, deps), citation, ...(reason ? { reason } : {}) }, + { scope_id: await resolveToolScope(ctx, deps, signal), citation, ...(reason ? { reason } : {}) }, signal, ); return jsonResult({ status: "retired", revision: result.memory.revision }); diff --git a/integrations/opencode/plugins/powercontext/README.md b/integrations/opencode/plugins/powercontext/README.md index b6e887ec6..59f2a774a 100644 --- a/integrations/opencode/plugins/powercontext/README.md +++ b/integrations/opencode/plugins/powercontext/README.md @@ -16,8 +16,8 @@ evidence. Recalled content is inserted transiently before model dispatch and is not persisted into the OpenCode transcript. Curated `pc_*` tools expose Memory, Handoff, Experience, Skill, and read-only Candidate operations. OpenCode asks before a named durable mutation. -The project scope comes from the normalized Git remote, falling back to a hash of the worktree path. Set -`POWERCONTEXT_OPENCODE_SCOPE_ID` to override it. Other configuration uses the same prefix with `BASE_URL`, +Each Session resolves an explicit Scope, its durable Session or workspace binding, or the Server default. Set +`POWERCONTEXT_OPENCODE_SCOPE_ID` only to force an existing Scope. Other configuration uses the same prefix with `BASE_URL`, `AUTHORIZATION`, `CAPTURE_PROMPTS`, `FLUSH_ON_CAPTURE`, `REQUEST_TIMEOUT_MS`, `HTTP_BUDGET_MS`, `MAX_BYTES`, and `FLUSH_MAX_CALLS`. diff --git a/integrations/opencode/plugins/powercontext/lib/index.js b/integrations/opencode/plugins/powercontext/lib/index.js index 67358051b..e41009945 100644 --- a/integrations/opencode/plugins/powercontext/lib/index.js +++ b/integrations/opencode/plugins/powercontext/lib/index.js @@ -16,7 +16,6 @@ import { createHash } from "node:crypto"; import { writeFile } from "node:fs/promises"; import { tool } from "@opencode-ai/plugin"; -import { spawn } from "node:child_process"; import { resolve } from "node:path"; //#region src/errors.ts @@ -72,313 +71,351 @@ const OPERATIONS = { method: "GET", path: "/health/live", location: null, - scope: false + scopeMode: "none", + pathParameters: [] }, get_readiness: { method: "GET", path: "/health/ready", location: null, - scope: false + scopeMode: "none", + pathParameters: [] }, get_capabilities: { method: "GET", path: "/v1/capabilities", location: null, - scope: false + scopeMode: "none", + pathParameters: [] + }, + list_scopes: { + method: "GET", + path: "/v1/scopes", + location: null, + scopeMode: "none", + pathParameters: [] + }, + create_scope: { + method: "POST", + path: "/v1/scopes", + location: "body", + scopeMode: "none", + pathParameters: [] + }, + publish_artifact: { + method: "POST", + path: "/v1/artifact-publications", + location: "body", + scopeMode: "none", + pathParameters: [] + }, + get_scope: { + method: "GET", + path: "/v1/scopes/{scope_id}", + location: null, + scopeMode: "none", + pathParameters: ["scope_id"] + }, + update_scope: { + method: "PUT", + path: "/v1/scopes/{scope_id}", + location: "body", + scopeMode: "none", + pathParameters: ["scope_id"] + }, + get_default_scope: { + method: "GET", + path: "/v1/scopes/default", + location: null, + scopeMode: "none", + pathParameters: [] + }, + set_default_scope: { + method: "PUT", + path: "/v1/scopes/default", + location: "body", + scopeMode: "none", + pathParameters: [] + }, + resolve_scope_selection: { + method: "POST", + path: "/v1/scopes/selection/resolve", + location: "body", + scopeMode: "none", + pathParameters: [] + }, + resolve_scope_binding: { + method: "POST", + path: "/v1/scope-bindings/resolve", + location: "body", + scopeMode: "none", + pathParameters: [] + }, + set_scope_binding: { + method: "PUT", + path: "/v1/scope-bindings", + location: "body", + scopeMode: "none", + pathParameters: [] + }, + clear_scope_binding: { + method: "POST", + path: "/v1/scope-bindings/clear", + location: "body", + scopeMode: "none", + pathParameters: [] }, capture_content_source: { method: "POST", path: "/v1/sources/content", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, prepare_context: { method: "POST", path: "/v1/context/prepare", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, create_work_contract: { method: "POST", path: "/v1/work/contracts/create", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, handoff_current_work: { method: "POST", path: "/v1/work/handoffs/prepare-current", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, acknowledge_handoff: { method: "POST", path: "/v1/work/handoffs/acknowledge", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, record_task_outcome: { method: "POST", path: "/v1/work/outcomes/record", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, activate_handoff: { method: "POST", path: "/v1/handoff/activate", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, prepare_handoff: { method: "POST", path: "/v1/handoff/prepare", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, finalize_handoff: { method: "POST", path: "/v1/handoff/finalize", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, commit_handoff: { method: "POST", path: "/v1/handoff/commit", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, continue_handoff: { method: "POST", path: "/v1/handoff/continue", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, flush_memory: { method: "POST", path: "/v1/memory/flush", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, remember_memory: { method: "POST", path: "/v1/memory/remember", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, search_memory: { method: "POST", path: "/v1/memory/search", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, list_memory_entries: { method: "POST", path: "/v1/memory/entries/list", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, get_memory_entry: { method: "POST", path: "/v1/memory/entries/get", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, revise_memory_entry: { method: "POST", path: "/v1/memory/entries/revise", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, retire_memory_entry: { method: "POST", path: "/v1/memory/entries/retire", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, list_memory_changes: { method: "POST", path: "/v1/memory/changes", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, propose_experience: { method: "POST", path: "/v1/experience/propose", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, generate_experience: { method: "POST", path: "/v1/experience/generate", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, get_experience: { method: "POST", path: "/v1/experience/get", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, propose_skill: { method: "POST", path: "/v1/skill/propose", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, generate_skill: { method: "POST", path: "/v1/skill/generate", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, get_skill: { method: "POST", path: "/v1/skill/get", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, scan_external_skills: { method: "POST", path: "/v1/external-skills/scan", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, list_external_skills: { method: "POST", path: "/v1/external-skills/list", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, resolve_external_skill: { method: "POST", path: "/v1/external-skills/resolve", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, import_external_skill: { method: "POST", path: "/v1/external-skills/import", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, list_artifact_candidates: { method: "POST", path: "/v1/artifact-candidates/list", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, get_artifact_candidate: { method: "POST", path: "/v1/artifact-candidates/get", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, approve_artifact_candidate: { method: "POST", path: "/v1/artifact-candidates/approve", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, reject_artifact_candidate: { method: "POST", path: "/v1/artifact-candidates/reject", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, revise_artifact_candidate: { method: "POST", path: "/v1/artifact-candidates/revise", location: "body", - scope: true + scopeMode: "current", + pathParameters: [] }, get_stats: { - method: "GET", - path: "/v1/stats", - location: "query", - scope: true - }, - create_handoff_report_project: { - method: "POST", - path: "/v1/handoff-reports/projects/create", - location: "body", - scope: false - }, - list_handoff_report_projects: { - method: "POST", - path: "/v1/handoff-reports/projects/list", - location: "body", - scope: false - }, - get_handoff_report_project: { - method: "POST", - path: "/v1/handoff-reports/projects/get", - location: "body", - scope: false - }, - update_handoff_report_project: { - method: "POST", - path: "/v1/handoff-reports/projects/update", - location: "body", - scope: false - }, - register_handoff_report_workstream: { - method: "POST", - path: "/v1/handoff-reports/workstreams/register", - location: "body", - scope: true - }, - list_handoff_report_workstreams: { - method: "POST", - path: "/v1/handoff-reports/workstreams/list", - location: "body", - scope: false - }, - update_handoff_report_workstream: { method: "POST", - path: "/v1/handoff-reports/workstreams/update", + path: "/v1/stats", location: "body", - scope: false + scopeMode: "selection", + pathParameters: [] }, get_handoff_report: { method: "POST", path: "/v1/handoff-reports/get", location: "body", - scope: false - }, - record_handoff_report_activity: { - method: "POST", - path: "/v1/handoff-reports/activities/record", - location: "body", - scope: true - }, - list_handoff_report_activities: { - method: "POST", - path: "/v1/handoff-reports/activities/list", - location: "body", - scope: false - }, - purge_handoff_report_activities: { - method: "POST", - path: "/v1/handoff-reports/activities/purge", - location: "body", - scope: false - }, - get_handoff_report_workspace: { - method: "POST", - path: "/v1/handoff-reports/workspace-bindings/get", - location: "body", - scope: false - }, - attach_handoff_report_workspace: { - method: "POST", - path: "/v1/handoff-reports/workspace-bindings/attach", - location: "body", - scope: false - }, - detach_handoff_report_workspace: { - method: "POST", - path: "/v1/handoff-reports/workspace-bindings/detach", - location: "body", - scope: false + scopeMode: "selection", + pathParameters: [] } }; const OPERATION_IDS = Object.keys(OPERATIONS); @@ -444,11 +481,24 @@ async function readLimitedBody(response) { } return body; } -function queryString(payload) { - const params = new URLSearchParams(); - for (const [key, value] of Object.entries(payload ?? {})) if (value !== void 0 && value !== null) params.set(key, String(value)); - const encoded = params.toString(); - return encoded ? `?${encoded}` : ""; +function bindOperationPath(spec, payload) { + const pathParameters = spec.pathParameters; + if (pathParameters.length === 0) return { + path: spec.path, + payload + }; + const transportPayload = { ...payload }; + let path = spec.path; + for (const name of pathParameters) { + const value = transportPayload[name]; + if (typeof value !== "string" || value.trim().length === 0) throw new TypeError(`operation requires string path parameter ${name}`); + path = path.replace(`{${name}}`, encodeURIComponent(value)); + delete transportPayload[name]; + } + return { + path, + payload: transportPayload + }; } var PowerContextClient = class { fetchImpl; @@ -459,8 +509,9 @@ var PowerContextClient = class { async request(id, payload, signal) { if (!(id in OPERATIONS)) throw new UnknownOperationError(id); const spec = OPERATIONS[id]; + const bound = bindOperationPath(spec, payload); try { - const response = await this.fetchImpl(this.url(spec, payload), this.init(spec, payload, signal)); + const response = await this.fetchImpl(this.url(bound.path), this.init(spec, bound.payload, signal)); if (response.status >= 300 && response.status < 400) throw new InvalidResponseError(spec.path); const bytes = await readLimitedBody(response); const requestId = response.headers.get(REQUEST_ID_HEADER) ?? void 0; @@ -488,12 +539,11 @@ var PowerContextClient = class { } } catch (error) { if (error instanceof ServerResponseError || error instanceof InvalidResponseError || error instanceof UnknownOperationError) throw error; - throw new UnavailableError(spec.path, error); + throw new UnavailableError(bound.path, error); } } - url(spec, payload) { - const query = spec.location === "query" ? queryString(payload) : ""; - return `${this.options.baseUrl.replace(/\/+$/, "")}${spec.path}${query}`; + url(path) { + return `${this.options.baseUrl.replace(/\/+$/, "")}${path}`; } init(spec, payload, signal) { const headers = { @@ -509,7 +559,7 @@ var PowerContextClient = class { redirect: "manual", signal: combineSignals(signals) }; - if (spec.method === "POST" && spec.location === "body") { + if (spec.location === "body") { headers["Content-Type"] = "application/json"; init.body = JSON.stringify(payload ?? {}); } @@ -661,7 +711,14 @@ function errorResult(error) { }; } async function invokeOperation(client, operationId, payload, scopeId, signal) { - const body = OPERATIONS[operationId].scope ? { + const mode = OPERATIONS[operationId].scopeMode; + const body = mode === "selection" ? { + ...payload, + selection: { + mode: "exact", + scope_ids: [scopeId] + } + } : mode === "current" ? { ...payload, scope_id: scopeId } : payload; @@ -715,78 +772,32 @@ function validatePreparedContext(value, maxBytes) { //#endregion //#region src/scope.ts -const MAX_SCOPE_LENGTH = 256; -const SCP_REMOTE = /^(?:[^@/\s]+@)?(?[^:/\s]+):(?.+)$/; -function bounded(prefix, value) { - const candidate = `${prefix}:${value}`; - return candidate.length <= MAX_SCOPE_LENGTH ? candidate : `${prefix}:sha256:${createHash("sha256").update(value).digest("hex")}`; -} -function normalizePath(path) { - let normalized = path.replaceAll("\\", "/").split("/").filter(Boolean).join("/"); - if (normalized.endsWith(".git")) normalized = normalized.slice(0, -4); - return normalized.replace(/\/+$/, ""); +function sessionBindingKey(sessionID) { + return { + integration: "opencode", + kind: "session", + external_id: sessionID + }; } -function normalizeGitRemote(remote) { - const value = remote.trim(); - if (!value) return void 0; - const scpMatch = !value.includes("://") ? value.match(SCP_REMOTE) : null; - if (scpMatch?.groups?.host && scpMatch.groups.path) { - const path = normalizePath(scpMatch.groups.path); - return path ? `${scpMatch.groups.host.toLowerCase()}/${path}` : void 0; - } - try { - const parsed = new URL(value); - if (![ - "http:", - "https:", - "ssh:", - "git:" - ].includes(parsed.protocol) || !parsed.hostname) return void 0; - const host = parsed.port ? `${parsed.hostname.toLowerCase()}:${parsed.port}` : parsed.hostname.toLowerCase(); - const path = normalizePath(parsed.pathname); - return path ? `${host}/${path}` : void 0; - } catch { - return; - } +function workspaceBindingKey(cwd) { + return { + integration: "opencode", + kind: "workspace", + external_id: createHash("sha256").update(resolve(cwd)).digest("hex") + }; } -function spawnGit(cwd, args) { - return new Promise((finish) => { - const child = spawn("git", args, { - cwd, - windowsHide: true - }); - const chunks = []; - let settled = false; - const done = (value) => { - if (settled) return; - settled = true; - clearTimeout(timer); - finish(value); - }; - const timer = setTimeout(() => { - child.kill(); - done(void 0); - }, 2e3); - timer.unref(); - child.stdout.on("data", (chunk) => chunks.push(chunk)); - child.on("error", () => done(void 0)); - child.on("close", (code) => done(code === 0 ? Buffer.concat(chunks).toString("utf8").trim() || void 0 : void 0)); +async function resolveScopeId(client, input) { + const value = (await client.request("resolve_scope_binding", { + explicit_scope_id: input.configuredScopeId, + binding_keys: [sessionBindingKey(input.sessionID), workspaceBindingKey(input.cwd)] + })).value; + const scopeId = value && typeof value === "object" ? value.scope_id : void 0; + if (typeof scopeId !== "string" || !scopeId.trim()) throw new Error("PowerContext returned an invalid Scope"); + if (input.persistSession && !input.configuredScopeId) await client.request("set_scope_binding", { + key: sessionBindingKey(input.sessionID), + scope_id: scopeId }); -} -async function deriveScopeId(cwd, options = {}) { - if (options.configuredScopeId) { - const explicit = options.configuredScopeId; - return explicit.length <= MAX_SCOPE_LENGTH ? explicit : `sha256:${createHash("sha256").update(explicit).digest("hex")}`; - } - const git = options.git ?? spawnGit; - const root = resolve(await git(cwd, ["rev-parse", "--show-toplevel"]) || cwd); - const remote = await git(root, [ - "config", - "--get", - "remote.origin.url" - ]); - const normalized = remote ? normalizeGitRemote(remote) : void 0; - return normalized ? bounded("git", normalized) : `local:${createHash("sha256").update(root).digest("hex")}`; + return scopeId; } //#endregion @@ -922,31 +933,37 @@ async function prepareTurn(runtime, input) { }); } } -async function sessionContextFromDirectory(cwd, config) { +async function sessionContextFromDirectory(client, cwd, sessionID, config) { const directory = cwd.trim(); if (!directory) throw new Error("OpenCode session has no directory"); return { cwd: directory, - scopeId: await deriveScopeId(directory, { configuredScopeId: config.scopeId }) + scopeId: await resolveScopeId(client, { + cwd: directory, + sessionID, + configuredScopeId: config.scopeId, + persistSession: true + }) }; } -async function loadSessionContext(input, config, sessionID) { +async function loadSessionContext(input, client, config, sessionID) { const cwd = (await input.client.session.get({ path: { id: sessionID } })).data?.directory; if (!cwd) throw new Error(`OpenCode session ${sessionID} has no directory`); - return sessionContextFromDirectory(cwd, config); + return sessionContextFromDirectory(client, cwd, sessionID, config); } function createRuntime(input, config) { const sessionContexts = /* @__PURE__ */ new Map(); + const client = new PowerContextClient({ + baseUrl: config.baseUrl, + authorization: config.authorization, + requestTimeoutMs: config.requestTimeoutMs + }); return { config, - client: new PowerContextClient({ - baseUrl: config.baseUrl, - authorization: config.authorization, - requestTimeoutMs: config.requestTimeoutMs - }), + client, sessionContexts, cacheSessionContext(sessionID, cwd) { - const context = sessionContextFromDirectory(cwd, config); + const context = sessionContextFromDirectory(client, cwd, sessionID, config); sessionContexts.set(sessionID, context); context.catch(() => { if (sessionContexts.get(sessionID) === context) sessionContexts.delete(sessionID); @@ -955,7 +972,7 @@ function createRuntime(input, config) { resolveSessionContext(sessionID) { let context = sessionContexts.get(sessionID); if (!context) { - context = loadSessionContext(input, config, sessionID); + context = loadSessionContext(input, client, config, sessionID); sessionContexts.set(sessionID, context); context.catch(() => { if (sessionContexts.get(sessionID) === context) sessionContexts.delete(sessionID); @@ -1004,7 +1021,7 @@ function operationTool(runtime, definition) { }); let result; try { - const scopeId = await deriveScopeId(context.worktree || context.directory, { configuredScopeId: runtime.config.scopeId }); + const scopeId = (await runtime.resolveSessionContext(context.sessionID)).scopeId; result = await invokeOperation(runtime.client, definition.operationId, definition.payload(args), scopeId, context.abort); } catch { result = { @@ -1048,7 +1065,7 @@ function createTools(runtime) { }) }), pc_memory_list: operationTool(runtime, { - description: "List Memory entries in the current project scope.", + description: "List Memory entries in the current Scope.", args: { include_inactive: z.boolean().optional() }, operationId: "list_memory_entries", payload: (args) => ({ include_inactive: args.include_inactive ?? false }) diff --git a/integrations/opencode/plugins/powercontext/package.json b/integrations/opencode/plugins/powercontext/package.json index ceecb55e7..b8df6c20d 100644 --- a/integrations/opencode/plugins/powercontext/package.json +++ b/integrations/opencode/plugins/powercontext/package.json @@ -1,7 +1,7 @@ { "name": "powercontext-opencode", "version": "0.0.1", - "description": "OpenCode plugin that connects to a PowerContext Server for project-scoped memory and handoff.", + "description": "OpenCode plugin that connects to a PowerContext Server for Scope-bound memory and handoff.", "license": "Apache-2.0", "type": "module", "main": "lib/index.js", diff --git a/integrations/opencode/plugins/powercontext/pnpm-workspace.yaml b/integrations/opencode/plugins/powercontext/pnpm-workspace.yaml index 84201a701..9663c4ed6 100644 --- a/integrations/opencode/plugins/powercontext/pnpm-workspace.yaml +++ b/integrations/opencode/plugins/powercontext/pnpm-workspace.yaml @@ -12,6 +12,9 @@ # See the License for the specific language governing permissions and # limitations under the License. +packages: + - . + allowBuilds: esbuild: true msgpackr-extract: false diff --git a/integrations/opencode/plugins/powercontext/skills/project-context/SKILL.md b/integrations/opencode/plugins/powercontext/skills/project-context/SKILL.md index ef6cfdb86..95e0a2ff2 100644 --- a/integrations/opencode/plugins/powercontext/skills/project-context/SKILL.md +++ b/integrations/opencode/plugins/powercontext/skills/project-context/SKILL.md @@ -17,7 +17,7 @@ Source evidence. Do not call `pc_remember` merely to duplicate the current promp ## Read context - Use `pc_search` with a focused query, `mode: "auto"`, and no more than eight results. -- Use `pc_memory_list` to inspect active entries in the current project scope. +- Use `pc_memory_list` to inspect active entries in the current Scope. - Use `pc_memory_get` only with an exact citation returned by search or list. - Use `pc_prepare_context` when one bounded value is more useful than raw search hits. diff --git a/integrations/opencode/plugins/powercontext/src/client.ts b/integrations/opencode/plugins/powercontext/src/client.ts index 061072c61..c804a66af 100644 --- a/integrations/opencode/plugins/powercontext/src/client.ts +++ b/integrations/opencode/plugins/powercontext/src/client.ts @@ -107,13 +107,24 @@ async function readLimitedBody(response: Response): Promise { return body } -function queryString(payload: JsonObject | undefined): string { - const params = new URLSearchParams() - for (const [key, value] of Object.entries(payload ?? {})) { - if (value !== undefined && value !== null) params.set(key, String(value)) +function bindOperationPath( + spec: OperationSpec, + payload: JsonObject | undefined, +): { path: string; payload: JsonObject | undefined } { + const pathParameters: readonly string[] = spec.pathParameters + if (pathParameters.length === 0) return { path: spec.path, payload } + + const transportPayload = { ...payload } + let path: string = spec.path + for (const name of pathParameters) { + const value = transportPayload[name] + if (typeof value !== 'string' || value.trim().length === 0) { + throw new TypeError(`operation requires string path parameter ${name}`) + } + path = path.replace(`{${name}}`, encodeURIComponent(value)) + delete transportPayload[name] } - const encoded = params.toString() - return encoded ? `?${encoded}` : '' + return { path, payload: transportPayload } } export class PowerContextClient { @@ -126,8 +137,9 @@ export class PowerContextClient { async request(id: string, payload?: JsonObject, signal?: AbortSignal): Promise { if (!(id in OPERATIONS)) throw new UnknownOperationError(id) const spec = OPERATIONS[id as OperationId] + const bound = bindOperationPath(spec, payload) try { - const response = await this.fetchImpl(this.url(spec, payload), this.init(spec, payload, signal)) + const response = await this.fetchImpl(this.url(bound.path), this.init(spec, bound.payload, signal)) if (response.status >= 300 && response.status < 400) throw new InvalidResponseError(spec.path) const bytes = await readLimitedBody(response) const requestId = response.headers.get(REQUEST_ID_HEADER) ?? undefined @@ -152,13 +164,12 @@ export class PowerContextClient { if (error instanceof ServerResponseError || error instanceof InvalidResponseError || error instanceof UnknownOperationError) { throw error } - throw new UnavailableError(spec.path, error) + throw new UnavailableError(bound.path, error) } } - private url(spec: OperationSpec, payload: JsonObject | undefined): string { - const query = spec.location === 'query' ? queryString(payload) : '' - return `${this.options.baseUrl.replace(/\/+$/, '')}${spec.path}${query}` + private url(path: string): string { + return `${this.options.baseUrl.replace(/\/+$/, '')}${path}` } private init(spec: OperationSpec, payload: JsonObject | undefined, signal?: AbortSignal): RequestInit { @@ -167,7 +178,7 @@ export class PowerContextClient { const signals = [createTimeoutSignal(this.options.requestTimeoutMs)] if (signal) signals.push(signal) const init: RequestInit = { method: spec.method, headers, redirect: 'manual', signal: combineSignals(signals) } - if (spec.method === 'POST' && spec.location === 'body') { + if (spec.location === 'body') { headers['Content-Type'] = 'application/json' init.body = JSON.stringify(payload ?? {}) } diff --git a/integrations/opencode/plugins/powercontext/src/index.ts b/integrations/opencode/plugins/powercontext/src/index.ts index 0d01ce2c3..c098378d0 100644 --- a/integrations/opencode/plugins/powercontext/src/index.ts +++ b/integrations/opencode/plugins/powercontext/src/index.ts @@ -24,7 +24,7 @@ import { invokeOperation, operationMutates } from './invoke.ts' import type { JsonObject } from './client.ts' import type { OperationId } from './operations.generated.ts' import { validatePreparedContext } from './prepared-context.ts' -import { deriveScopeId } from './scope.ts' +import { resolveScopeId } from './scope.ts' import { containsSecret } from './secrets.ts' export const GUIDANCE = `PowerContext provides durable project memory shared across agent sessions. @@ -191,31 +191,50 @@ async function prepareTurn( } } -async function sessionContextFromDirectory(cwd: string, config: ResolvedConfig): Promise { +async function sessionContextFromDirectory( + client: PowerContextClient, + cwd: string, + sessionID: string, + config: ResolvedConfig, +): Promise { const directory = cwd.trim() if (!directory) throw new Error('OpenCode session has no directory') - return { cwd: directory, scopeId: await deriveScopeId(directory, { configuredScopeId: config.scopeId }) } + return { + cwd: directory, + scopeId: await resolveScopeId(client, { + cwd: directory, + sessionID, + configuredScopeId: config.scopeId, + persistSession: true, + }), + } } -async function loadSessionContext(input: PluginInput, config: ResolvedConfig, sessionID: string): Promise { +async function loadSessionContext( + input: PluginInput, + client: PowerContextClient, + config: ResolvedConfig, + sessionID: string, +): Promise { const result = await input.client.session.get({ path: { id: sessionID } }) const cwd = result.data?.directory if (!cwd) throw new Error(`OpenCode session ${sessionID} has no directory`) - return sessionContextFromDirectory(cwd, config) + return sessionContextFromDirectory(client, cwd, sessionID, config) } function createRuntime(input: PluginInput, config: ResolvedConfig): Runtime { const sessionContexts = new Map>() + const client = new PowerContextClient({ + baseUrl: config.baseUrl, + authorization: config.authorization, + requestTimeoutMs: config.requestTimeoutMs, + }) return { config, - client: new PowerContextClient({ - baseUrl: config.baseUrl, - authorization: config.authorization, - requestTimeoutMs: config.requestTimeoutMs, - }), + client, sessionContexts, cacheSessionContext(sessionID, cwd) { - const context = sessionContextFromDirectory(cwd, config) + const context = sessionContextFromDirectory(client, cwd, sessionID, config) sessionContexts.set(sessionID, context) void context.catch(() => { if (sessionContexts.get(sessionID) === context) sessionContexts.delete(sessionID) @@ -224,7 +243,7 @@ function createRuntime(input: PluginInput, config: ResolvedConfig): Runtime { resolveSessionContext(sessionID) { let context = sessionContexts.get(sessionID) if (!context) { - context = loadSessionContext(input, config, sessionID) + context = loadSessionContext(input, client, config, sessionID) sessionContexts.set(sessionID, context) void context.catch(() => { if (sessionContexts.get(sessionID) === context) sessionContexts.delete(sessionID) @@ -275,9 +294,7 @@ function operationTool( } let result try { - const scopeId = await deriveScopeId(context.worktree || context.directory, { - configuredScopeId: runtime.config.scopeId, - }) + const scopeId = (await runtime.resolveSessionContext(context.sessionID)).scopeId result = await invokeOperation( runtime.client, definition.operationId, @@ -312,7 +329,7 @@ function createTools(runtime: Runtime) { payload: (args) => ({ kind: args.kind, text: args.text, reason: args.reason }), }), pc_memory_list: operationTool(runtime, { - description: 'List Memory entries in the current project scope.', + description: 'List Memory entries in the current Scope.', args: { include_inactive: z.boolean().optional() }, operationId: 'list_memory_entries', payload: (args) => ({ include_inactive: args.include_inactive ?? false }), diff --git a/integrations/opencode/plugins/powercontext/src/invoke.ts b/integrations/opencode/plugins/powercontext/src/invoke.ts index 9eaa5edb7..1a85cf56e 100644 --- a/integrations/opencode/plugins/powercontext/src/invoke.ts +++ b/integrations/opencode/plugins/powercontext/src/invoke.ts @@ -82,7 +82,12 @@ export async function invokeOperation( scopeId: string, signal?: AbortSignal, ): Promise { - const body = OPERATIONS[operationId].scope ? { ...payload, scope_id: scopeId } : payload + const mode = OPERATIONS[operationId].scopeMode + const body = mode === 'selection' + ? { ...payload, selection: { mode: 'exact', scope_ids: [scopeId] } } + : mode === 'current' + ? { ...payload, scope_id: scopeId } + : payload if (operationMutates(operationId) && hasSecret(body)) { return { ok: false, code: 'secret_rejected', message: 'Refused to send secret-like content to PowerContext.' } } diff --git a/integrations/opencode/plugins/powercontext/src/operations.generated.ts b/integrations/opencode/plugins/powercontext/src/operations.generated.ts index 092c7108a..4dd7b53a3 100644 --- a/integrations/opencode/plugins/powercontext/src/operations.generated.ts +++ b/integrations/opencode/plugins/powercontext/src/operations.generated.ts @@ -17,59 +17,56 @@ // generated from openapi/powercontext.yaml; do not edit. export const OPERATIONS = { - get_liveness: { method: 'GET', path: '/health/live', location: null, scope: false }, - get_readiness: { method: 'GET', path: '/health/ready', location: null, scope: false }, - get_capabilities: { method: 'GET', path: '/v1/capabilities', location: null, scope: false }, - capture_content_source: { method: 'POST', path: '/v1/sources/content', location: "body", scope: true }, - prepare_context: { method: 'POST', path: '/v1/context/prepare', location: "body", scope: true }, - create_work_contract: { method: 'POST', path: '/v1/work/contracts/create', location: "body", scope: true }, - handoff_current_work: { method: 'POST', path: '/v1/work/handoffs/prepare-current', location: "body", scope: true }, - acknowledge_handoff: { method: 'POST', path: '/v1/work/handoffs/acknowledge', location: "body", scope: true }, - record_task_outcome: { method: 'POST', path: '/v1/work/outcomes/record', location: "body", scope: true }, - activate_handoff: { method: 'POST', path: '/v1/handoff/activate', location: "body", scope: true }, - prepare_handoff: { method: 'POST', path: '/v1/handoff/prepare', location: "body", scope: true }, - finalize_handoff: { method: 'POST', path: '/v1/handoff/finalize', location: "body", scope: true }, - commit_handoff: { method: 'POST', path: '/v1/handoff/commit', location: "body", scope: true }, - continue_handoff: { method: 'POST', path: '/v1/handoff/continue', location: "body", scope: true }, - flush_memory: { method: 'POST', path: '/v1/memory/flush', location: "body", scope: true }, - remember_memory: { method: 'POST', path: '/v1/memory/remember', location: "body", scope: true }, - search_memory: { method: 'POST', path: '/v1/memory/search', location: "body", scope: true }, - list_memory_entries: { method: 'POST', path: '/v1/memory/entries/list', location: "body", scope: true }, - get_memory_entry: { method: 'POST', path: '/v1/memory/entries/get', location: "body", scope: true }, - revise_memory_entry: { method: 'POST', path: '/v1/memory/entries/revise', location: "body", scope: true }, - retire_memory_entry: { method: 'POST', path: '/v1/memory/entries/retire', location: "body", scope: true }, - list_memory_changes: { method: 'POST', path: '/v1/memory/changes', location: "body", scope: true }, - propose_experience: { method: 'POST', path: '/v1/experience/propose', location: "body", scope: true }, - generate_experience: { method: 'POST', path: '/v1/experience/generate', location: "body", scope: true }, - get_experience: { method: 'POST', path: '/v1/experience/get', location: "body", scope: true }, - propose_skill: { method: 'POST', path: '/v1/skill/propose', location: "body", scope: true }, - generate_skill: { method: 'POST', path: '/v1/skill/generate', location: "body", scope: true }, - get_skill: { method: 'POST', path: '/v1/skill/get', location: "body", scope: true }, - scan_external_skills: { method: 'POST', path: '/v1/external-skills/scan', location: "body", scope: true }, - list_external_skills: { method: 'POST', path: '/v1/external-skills/list', location: "body", scope: true }, - resolve_external_skill: { method: 'POST', path: '/v1/external-skills/resolve', location: "body", scope: true }, - import_external_skill: { method: 'POST', path: '/v1/external-skills/import', location: "body", scope: true }, - list_artifact_candidates: { method: 'POST', path: '/v1/artifact-candidates/list', location: "body", scope: true }, - get_artifact_candidate: { method: 'POST', path: '/v1/artifact-candidates/get', location: "body", scope: true }, - approve_artifact_candidate: { method: 'POST', path: '/v1/artifact-candidates/approve', location: "body", scope: true }, - reject_artifact_candidate: { method: 'POST', path: '/v1/artifact-candidates/reject', location: "body", scope: true }, - revise_artifact_candidate: { method: 'POST', path: '/v1/artifact-candidates/revise', location: "body", scope: true }, - get_stats: { method: 'GET', path: '/v1/stats', location: "query", scope: true }, - create_handoff_report_project: { method: 'POST', path: '/v1/handoff-reports/projects/create', location: "body", scope: false }, - list_handoff_report_projects: { method: 'POST', path: '/v1/handoff-reports/projects/list', location: "body", scope: false }, - list_handoff_report_known_scopes: { method: 'POST', path: '/v1/handoff-reports/scopes/list-known', location: "body", scope: false }, - get_handoff_report_project: { method: 'POST', path: '/v1/handoff-reports/projects/get', location: "body", scope: false }, - update_handoff_report_project: { method: 'POST', path: '/v1/handoff-reports/projects/update', location: "body", scope: false }, - register_handoff_report_workstream: { method: 'POST', path: '/v1/handoff-reports/workstreams/register', location: "body", scope: true }, - list_handoff_report_workstreams: { method: 'POST', path: '/v1/handoff-reports/workstreams/list', location: "body", scope: false }, - update_handoff_report_workstream: { method: 'POST', path: '/v1/handoff-reports/workstreams/update', location: "body", scope: false }, - get_handoff_report: { method: 'POST', path: '/v1/handoff-reports/get', location: "body", scope: true }, - record_handoff_report_activity: { method: 'POST', path: '/v1/handoff-reports/activities/record', location: "body", scope: true }, - list_handoff_report_activities: { method: 'POST', path: '/v1/handoff-reports/activities/list', location: "body", scope: false }, - purge_handoff_report_activities: { method: 'POST', path: '/v1/handoff-reports/activities/purge', location: "body", scope: false }, - get_handoff_report_workspace: { method: 'POST', path: '/v1/handoff-reports/workspace-bindings/get', location: "body", scope: false }, - attach_handoff_report_workspace: { method: 'POST', path: '/v1/handoff-reports/workspace-bindings/attach', location: "body", scope: false }, - detach_handoff_report_workspace: { method: 'POST', path: '/v1/handoff-reports/workspace-bindings/detach', location: "body", scope: false }, + get_liveness: { method: 'GET', path: '/health/live', location: null, scopeMode: 'none', pathParameters: [] }, + get_readiness: { method: 'GET', path: '/health/ready', location: null, scopeMode: 'none', pathParameters: [] }, + get_capabilities: { method: 'GET', path: '/v1/capabilities', location: null, scopeMode: 'none', pathParameters: [] }, + list_scopes: { method: 'GET', path: '/v1/scopes', location: null, scopeMode: 'none', pathParameters: [] }, + create_scope: { method: 'POST', path: '/v1/scopes', location: "body", scopeMode: 'none', pathParameters: [] }, + publish_artifact: { method: 'POST', path: '/v1/artifact-publications', location: "body", scopeMode: 'none', pathParameters: [] }, + get_scope: { method: 'GET', path: '/v1/scopes/{scope_id}', location: null, scopeMode: 'none', pathParameters: ['scope_id'] }, + update_scope: { method: 'PUT', path: '/v1/scopes/{scope_id}', location: "body", scopeMode: 'none', pathParameters: ['scope_id'] }, + get_default_scope: { method: 'GET', path: '/v1/scopes/default', location: null, scopeMode: 'none', pathParameters: [] }, + set_default_scope: { method: 'PUT', path: '/v1/scopes/default', location: "body", scopeMode: 'none', pathParameters: [] }, + resolve_scope_selection: { method: 'POST', path: '/v1/scopes/selection/resolve', location: "body", scopeMode: 'none', pathParameters: [] }, + resolve_scope_binding: { method: 'POST', path: '/v1/scope-bindings/resolve', location: "body", scopeMode: 'none', pathParameters: [] }, + set_scope_binding: { method: 'PUT', path: '/v1/scope-bindings', location: "body", scopeMode: 'none', pathParameters: [] }, + clear_scope_binding: { method: 'POST', path: '/v1/scope-bindings/clear', location: "body", scopeMode: 'none', pathParameters: [] }, + capture_content_source: { method: 'POST', path: '/v1/sources/content', location: "body", scopeMode: 'current', pathParameters: [] }, + prepare_context: { method: 'POST', path: '/v1/context/prepare', location: "body", scopeMode: 'current', pathParameters: [] }, + create_work_contract: { method: 'POST', path: '/v1/work/contracts/create', location: "body", scopeMode: 'current', pathParameters: [] }, + handoff_current_work: { method: 'POST', path: '/v1/work/handoffs/prepare-current', location: "body", scopeMode: 'current', pathParameters: [] }, + acknowledge_handoff: { method: 'POST', path: '/v1/work/handoffs/acknowledge', location: "body", scopeMode: 'current', pathParameters: [] }, + record_task_outcome: { method: 'POST', path: '/v1/work/outcomes/record', location: "body", scopeMode: 'current', pathParameters: [] }, + activate_handoff: { method: 'POST', path: '/v1/handoff/activate', location: "body", scopeMode: 'current', pathParameters: [] }, + prepare_handoff: { method: 'POST', path: '/v1/handoff/prepare', location: "body", scopeMode: 'current', pathParameters: [] }, + finalize_handoff: { method: 'POST', path: '/v1/handoff/finalize', location: "body", scopeMode: 'current', pathParameters: [] }, + commit_handoff: { method: 'POST', path: '/v1/handoff/commit', location: "body", scopeMode: 'current', pathParameters: [] }, + continue_handoff: { method: 'POST', path: '/v1/handoff/continue', location: "body", scopeMode: 'current', pathParameters: [] }, + flush_memory: { method: 'POST', path: '/v1/memory/flush', location: "body", scopeMode: 'current', pathParameters: [] }, + remember_memory: { method: 'POST', path: '/v1/memory/remember', location: "body", scopeMode: 'current', pathParameters: [] }, + search_memory: { method: 'POST', path: '/v1/memory/search', location: "body", scopeMode: 'current', pathParameters: [] }, + list_memory_entries: { method: 'POST', path: '/v1/memory/entries/list', location: "body", scopeMode: 'current', pathParameters: [] }, + get_memory_entry: { method: 'POST', path: '/v1/memory/entries/get', location: "body", scopeMode: 'current', pathParameters: [] }, + revise_memory_entry: { method: 'POST', path: '/v1/memory/entries/revise', location: "body", scopeMode: 'current', pathParameters: [] }, + retire_memory_entry: { method: 'POST', path: '/v1/memory/entries/retire', location: "body", scopeMode: 'current', pathParameters: [] }, + list_memory_changes: { method: 'POST', path: '/v1/memory/changes', location: "body", scopeMode: 'current', pathParameters: [] }, + propose_experience: { method: 'POST', path: '/v1/experience/propose', location: "body", scopeMode: 'current', pathParameters: [] }, + generate_experience: { method: 'POST', path: '/v1/experience/generate', location: "body", scopeMode: 'current', pathParameters: [] }, + get_experience: { method: 'POST', path: '/v1/experience/get', location: "body", scopeMode: 'current', pathParameters: [] }, + propose_skill: { method: 'POST', path: '/v1/skill/propose', location: "body", scopeMode: 'current', pathParameters: [] }, + generate_skill: { method: 'POST', path: '/v1/skill/generate', location: "body", scopeMode: 'current', pathParameters: [] }, + get_skill: { method: 'POST', path: '/v1/skill/get', location: "body", scopeMode: 'current', pathParameters: [] }, + scan_external_skills: { method: 'POST', path: '/v1/external-skills/scan', location: "body", scopeMode: 'current', pathParameters: [] }, + list_external_skills: { method: 'POST', path: '/v1/external-skills/list', location: "body", scopeMode: 'current', pathParameters: [] }, + resolve_external_skill: { method: 'POST', path: '/v1/external-skills/resolve', location: "body", scopeMode: 'current', pathParameters: [] }, + import_external_skill: { method: 'POST', path: '/v1/external-skills/import', location: "body", scopeMode: 'current', pathParameters: [] }, + list_artifact_candidates: { method: 'POST', path: '/v1/artifact-candidates/list', location: "body", scopeMode: 'current', pathParameters: [] }, + get_artifact_candidate: { method: 'POST', path: '/v1/artifact-candidates/get', location: "body", scopeMode: 'current', pathParameters: [] }, + approve_artifact_candidate: { method: 'POST', path: '/v1/artifact-candidates/approve', location: "body", scopeMode: 'current', pathParameters: [] }, + reject_artifact_candidate: { method: 'POST', path: '/v1/artifact-candidates/reject', location: "body", scopeMode: 'current', pathParameters: [] }, + revise_artifact_candidate: { method: 'POST', path: '/v1/artifact-candidates/revise', location: "body", scopeMode: 'current', pathParameters: [] }, + get_stats: { method: 'POST', path: '/v1/stats', location: "body", scopeMode: 'selection', pathParameters: [] }, + get_handoff_report: { method: 'POST', path: '/v1/handoff-reports/get', location: "body", scopeMode: 'selection', pathParameters: [] }, } as const export type OperationId = keyof typeof OPERATIONS diff --git a/integrations/opencode/plugins/powercontext/src/scope.ts b/integrations/opencode/plugins/powercontext/src/scope.ts index cefe982cb..2d529c7c8 100644 --- a/integrations/opencode/plugins/powercontext/src/scope.ts +++ b/integrations/opencode/plugins/powercontext/src/scope.ts @@ -15,78 +15,36 @@ */ import { createHash } from 'node:crypto' -import { spawn } from 'node:child_process' import { resolve } from 'node:path' +import type { PowerContextClient } from './client.ts' -const MAX_SCOPE_LENGTH = 256 -const SCP_REMOTE = /^(?:[^@/\s]+@)?(?[^:/\s]+):(?.+)$/ -export type GitRunner = (cwd: string, args: string[]) => Promise +type ScopeBindingKey = { integration: string; kind: string; external_id: string } -function bounded(prefix: string, value: string): string { - const candidate = `${prefix}:${value}` - return candidate.length <= MAX_SCOPE_LENGTH - ? candidate - : `${prefix}:sha256:${createHash('sha256').update(value).digest('hex')}` +export function sessionBindingKey(sessionID: string): ScopeBindingKey { + return { integration: 'opencode', kind: 'session', external_id: sessionID } } -function normalizePath(path: string): string { - let normalized = path.replaceAll('\\', '/').split('/').filter(Boolean).join('/') - if (normalized.endsWith('.git')) normalized = normalized.slice(0, -4) - return normalized.replace(/\/+$/, '') -} - -export function normalizeGitRemote(remote: string): string | undefined { - const value = remote.trim() - if (!value) return undefined - const scpMatch = !value.includes('://') ? value.match(SCP_REMOTE) : null - if (scpMatch?.groups?.host && scpMatch.groups.path) { - const path = normalizePath(scpMatch.groups.path) - return path ? `${scpMatch.groups.host.toLowerCase()}/${path}` : undefined - } - try { - const parsed = new URL(value) - if (!['http:', 'https:', 'ssh:', 'git:'].includes(parsed.protocol) || !parsed.hostname) return undefined - const host = parsed.port ? `${parsed.hostname.toLowerCase()}:${parsed.port}` : parsed.hostname.toLowerCase() - const path = normalizePath(parsed.pathname) - return path ? `${host}/${path}` : undefined - } catch { - return undefined +export function workspaceBindingKey(cwd: string): ScopeBindingKey { + return { + integration: 'opencode', + kind: 'workspace', + external_id: createHash('sha256').update(resolve(cwd)).digest('hex'), } } -export function spawnGit(cwd: string, args: string[]): Promise { - return new Promise((finish) => { - const child = spawn('git', args, { cwd, windowsHide: true }) - const chunks: Buffer[] = [] - let settled = false - const done = (value: string | undefined) => { - if (settled) return - settled = true - clearTimeout(timer) - finish(value) - } - const timer = setTimeout(() => { - child.kill() - done(undefined) - }, 2000) - timer.unref() - child.stdout.on('data', (chunk: Buffer) => chunks.push(chunk)) - child.on('error', () => done(undefined)) - child.on('close', (code) => done(code === 0 ? Buffer.concat(chunks).toString('utf8').trim() || undefined : undefined)) - }) -} - -export async function deriveScopeId( - cwd: string, - options: { configuredScopeId?: string; git?: GitRunner } = {}, +export async function resolveScopeId( + client: PowerContextClient, + input: { cwd: string; sessionID: string; configuredScopeId?: string; persistSession?: boolean }, ): Promise { - if (options.configuredScopeId) { - const explicit = options.configuredScopeId - return explicit.length <= MAX_SCOPE_LENGTH ? explicit : `sha256:${createHash('sha256').update(explicit).digest('hex')}` + const response = await client.request('resolve_scope_binding', { + explicit_scope_id: input.configuredScopeId, + binding_keys: [sessionBindingKey(input.sessionID), workspaceBindingKey(input.cwd)], + }) + const value = response.value + const scopeId = value && typeof value === 'object' ? (value as { scope_id?: unknown }).scope_id : undefined + if (typeof scopeId !== 'string' || !scopeId.trim()) throw new Error('PowerContext returned an invalid Scope') + if (input.persistSession && !input.configuredScopeId) { + await client.request('set_scope_binding', { key: sessionBindingKey(input.sessionID), scope_id: scopeId }) } - const git = options.git ?? spawnGit - const root = resolve(await git(cwd, ['rev-parse', '--show-toplevel']) || cwd) - const remote = await git(root, ['config', '--get', 'remote.origin.url']) - const normalized = remote ? normalizeGitRemote(remote) : undefined - return normalized ? bounded('git', normalized) : `local:${createHash('sha256').update(root).digest('hex')}` + return scopeId } diff --git a/integrations/opencode/plugins/powercontext/tests/client.spec.ts b/integrations/opencode/plugins/powercontext/tests/client.spec.ts index c097e2de8..1a9b805ed 100644 --- a/integrations/opencode/plugins/powercontext/tests/client.spec.ts +++ b/integrations/opencode/plugins/powercontext/tests/client.spec.ts @@ -28,6 +28,33 @@ function clientFor(response: Response): PowerContextClient { } describe('PowerContextClient response limits', () => { + it('binds scope resource paths and omits path values from the request body', async () => { + const requests: Array<{ url: string; init: RequestInit }> = [] + const client = new PowerContextClient({ + baseUrl: 'http://127.0.0.1:8000', + requestTimeoutMs: 1000, + fetch: async (url, init) => { + requests.push({ url, init }) + return new Response(JSON.stringify({ scope_id: 'scope:feature' }), { status: 200 }) + }, + }) + + await client.request('get_scope', { scope_id: 'scope:feature' }) + await client.request('update_scope', { + scope_id: 'scope:feature', + expected_version: 1, + title: 'Feature', + summary: 'Current work', + }) + + expect(requests.map((request) => request.url)).toEqual([ + 'http://127.0.0.1:8000/v1/scopes/scope%3Afeature', + 'http://127.0.0.1:8000/v1/scopes/scope%3Afeature', + ]) + expect(requests[0]!.init.body).toBeUndefined() + expect(JSON.parse(String(requests[1]!.init.body))).not.toHaveProperty('scope_id') + }) + it('cancels a chunked response before it can exceed 1 MiB', async () => { let pulls = 0 let cancelled = false diff --git a/integrations/opencode/plugins/powercontext/tests/plugin.spec.ts b/integrations/opencode/plugins/powercontext/tests/plugin.spec.ts index c5c316cd9..ef65c265b 100644 --- a/integrations/opencode/plugins/powercontext/tests/plugin.spec.ts +++ b/integrations/opencode/plugins/powercontext/tests/plugin.spec.ts @@ -57,6 +57,16 @@ function userMessage() { } } +function bindingResponse(url: string, body: any): Response | undefined { + if (url.endsWith('/v1/scope-bindings/resolve')) { + return Response.json({ scope_id: body.explicit_scope_id ?? 'default-scope' }) + } + if (url.endsWith('/v1/scope-bindings')) { + return Response.json({ key: body.key, scope_id: body.scope_id }) + } + return undefined +} + afterEach(() => { vi.unstubAllGlobals() for (const key of ENV_KEYS) delete process.env[key] @@ -82,6 +92,8 @@ describe('PowerContextPlugin', () => { vi.stubGlobal('fetch', vi.fn(async (url: string, init: RequestInit) => { const body = init.body ? JSON.parse(String(init.body)) : undefined calls.push({ url, body }) + const binding = bindingResponse(url, body) + if (binding) return binding if (url.endsWith('/v1/context/prepare')) { const content = 'Parser decision: preserve the public token shape.' return Response.json({ @@ -110,11 +122,12 @@ describe('PowerContextPlugin', () => { expect(incoming.parts[1]).toMatchObject({ synthetic: true, messageID: 'msg-1', sessionID: 'session-1' }) expect(incoming.parts[1]?.text).toContain('Parser decision') expect(calls.map((call) => call.url)).toEqual([ + 'http://127.0.0.1:8000/v1/scope-bindings/resolve', 'http://127.0.0.1:8000/v1/context/prepare', 'http://127.0.0.1:8000/v1/sources/content', ]) - expect(calls[1]?.body.source_id).toMatch(/^opencode-user-prompt:/) - expect(calls[1]?.body.metadata.origin).toBe('opencode') + expect(calls[2]?.body.source_id).toMatch(/^opencode-user-prompt:/) + expect(calls[2]?.body.metadata.origin).toBe('opencode') }) it('fails open when the Server is unavailable', async () => { @@ -135,6 +148,8 @@ describe('PowerContextPlugin', () => { const calls: Array<{ url: string; body: any }> = [] vi.stubGlobal('fetch', vi.fn(async (url: string, init: RequestInit) => { calls.push({ url, body: JSON.parse(String(init.body)) }) + const binding = bindingResponse(url, calls.at(-1)?.body) + if (binding) return binding if (url.endsWith('/v1/context/prepare')) { return Response.json({ schema: 'powercontext.prepared-context.v1', @@ -154,8 +169,8 @@ describe('PowerContextPlugin', () => { { message: incoming.info, parts: incoming.parts } as any, ) - expect(calls[0]?.body.query).toBe('multi word prompt') - expect(calls[1]?.body.content).toBe('multi word prompt') + expect(calls.find((call) => call.url.endsWith('/v1/context/prepare'))?.body.query).toBe('multi word prompt') + expect(calls.find((call) => call.url.endsWith('/v1/sources/content'))?.body.content).toBe('multi word prompt') }) it('preserves intentional outer quotes in an already-decoded chat message', async () => { @@ -163,6 +178,8 @@ describe('PowerContextPlugin', () => { const calls: Array<{ url: string; body: any }> = [] vi.stubGlobal('fetch', vi.fn(async (url: string, init: RequestInit) => { calls.push({ url, body: JSON.parse(String(init.body)) }) + const binding = bindingResponse(url, calls.at(-1)?.body) + if (binding) return binding if (url.endsWith('/v1/context/prepare')) { return Response.json({ schema: 'powercontext.prepared-context.v1', @@ -182,13 +199,16 @@ describe('PowerContextPlugin', () => { { message: incoming.info, parts: incoming.parts } as any, ) - expect(calls[0]?.body.query).toBe('"preserve these quotes"') - expect(calls[1]?.body.content).toBe('"preserve these quotes"') + expect(calls.find((call) => call.url.endsWith('/v1/context/prepare'))?.body.query).toBe('"preserve these quotes"') + expect(calls.find((call) => call.url.endsWith('/v1/sources/content'))?.body.content).toBe('"preserve these quotes"') }) it('asks before a durable tool operation', async () => { process.env.POWERCONTEXT_OPENCODE_SCOPE_ID = 'project:test' - vi.stubGlobal('fetch', vi.fn(async () => Response.json({ revision: 1 }))) + vi.stubGlobal('fetch', vi.fn(async (url: string, init: RequestInit) => { + const body = init.body ? JSON.parse(String(init.body)) : undefined + return bindingResponse(url, body) ?? Response.json({ revision: 1 }) + })) const hooks = await PowerContextPlugin(pluginInput()) const ask = vi.fn(async () => undefined) const result = await hooks.tool?.pc_remember?.execute( @@ -234,6 +254,8 @@ describe('PowerContextPlugin', () => { const calls: Array<{ url: string; body: any }> = [] vi.stubGlobal('fetch', vi.fn(async (url: string, init: RequestInit) => { calls.push({ url, body: JSON.parse(String(init.body)) }) + const binding = bindingResponse(url, calls.at(-1)?.body) + if (binding) return binding if (url.endsWith('/v1/context/prepare')) { return Response.json({ schema: 'powercontext.prepared-context.v1', @@ -268,7 +290,7 @@ describe('PowerContextPlugin', () => { const prepared = calls.filter((call) => call.url.endsWith('/v1/context/prepare')) expect(prepared).toHaveLength(2) - expect(new Set(prepared.map((call) => call.body.scope_id)).size).toBe(2) + expect(new Set(prepared.map((call) => call.body.scope_id))).toEqual(new Set(['default-scope'])) const captured = calls.filter((call) => call.url.endsWith('/v1/sources/content')) expect(captured.map((call) => call.body.metadata.cwd)).toEqual([firstDirectory, secondDirectory]) expect(input.client.session.get).not.toHaveBeenCalled() @@ -278,13 +300,15 @@ describe('PowerContextPlugin', () => { } }) - it('loads uncached session directories and shares scope only within the same project', async () => { + it('loads uncached session directories without inventing workspace Scopes', async () => { const firstProject = await mkdtemp(join(tmpdir(), 'powercontext-opencode-shared-')) const secondProject = await mkdtemp(join(tmpdir(), 'powercontext-opencode-isolated-')) try { const calls: Array<{ url: string; body: any }> = [] vi.stubGlobal('fetch', vi.fn(async (url: string, init: RequestInit) => { calls.push({ url, body: JSON.parse(String(init.body)) }) + const binding = bindingResponse(url, calls.at(-1)?.body) + if (binding) return binding if (url.endsWith('/v1/context/prepare')) { return Response.json({ schema: 'powercontext.prepared-context.v1', @@ -325,7 +349,7 @@ describe('PowerContextPlugin', () => { prepared[0]?.body.scope_id, prepared[2]?.body.scope_id, ]) - expect(prepared[2]?.body.scope_id).not.toBe(prepared[0]?.body.scope_id) + expect(prepared[2]?.body.scope_id).toBe(prepared[0]?.body.scope_id) const captured = calls.filter((call) => call.url.endsWith('/v1/sources/content')) expect(captured.map((call) => call.body.metadata.cwd)).toEqual([firstProject, firstProject, secondProject]) expect(input.client.session.get).toHaveBeenCalledTimes(3) @@ -340,6 +364,8 @@ describe('PowerContextPlugin', () => { const calls: Array<{ url: string; body: any }> = [] vi.stubGlobal('fetch', vi.fn(async (url: string, init: RequestInit) => { calls.push({ url, body: JSON.parse(String(init.body)) }) + const binding = bindingResponse(url, calls.at(-1)?.body) + if (binding) return binding if (url.endsWith('/v1/context/prepare')) { return Response.json({ schema: 'powercontext.prepared-context.v1', diff --git a/integrations/opencode/plugins/powercontext/tests/scope.spec.ts b/integrations/opencode/plugins/powercontext/tests/scope.spec.ts index a007f096b..e9dfef64c 100644 --- a/integrations/opencode/plugins/powercontext/tests/scope.spec.ts +++ b/integrations/opencode/plugins/powercontext/tests/scope.spec.ts @@ -14,23 +14,43 @@ * limitations under the License. */ -import { describe, expect, it } from 'vitest' -import { deriveScopeId, normalizeGitRemote } from '../src/scope.ts' +import { describe, expect, it, vi } from 'vitest' +import { resolveScopeId } from '../src/scope.ts' -describe('scope', () => { - it('normalizes HTTPS and SCP remotes identically', () => { - expect(normalizeGitRemote('https://github.com/oceanbase/powercontext.git')).toBe('github.com/oceanbase/powercontext') - expect(normalizeGitRemote('git@github.com:oceanbase/powercontext.git')).toBe('github.com/oceanbase/powercontext') - }) +describe('Scope binding', () => { + it('resolves session, workspace, and default precedence on the Server', async () => { + const request = vi.fn().mockResolvedValue({ value: { scope_id: 'scp_00000000000000000000000000' } }) + const client = { request } as never - it('prefers an explicit scope', async () => { - await expect(deriveScopeId('/tmp/project', { configuredScopeId: 'project:test' })).resolves.toBe('project:test') + await expect(resolveScopeId(client, { + cwd: '/workspace/powercontext', + sessionID: 'session-a', + configuredScopeId: 'explicit-scope', + })).resolves.toBe('scp_00000000000000000000000000') + const firstCall = request.mock.calls[0] + expect(firstCall).toBeDefined() + if (!firstCall) throw new Error('resolve_scope_binding was not called') + const [operation, input] = firstCall + expect(operation).toBe('resolve_scope_binding') + expect(input.explicit_scope_id).toBe('explicit-scope') + expect(input.binding_keys[0]).toEqual({ integration: 'opencode', kind: 'session', external_id: 'session-a' }) + expect(input.binding_keys[1]).toMatchObject({ integration: 'opencode', kind: 'workspace' }) + expect(input.binding_keys[1].external_id).not.toContain('/workspace/powercontext') }) - it('derives a git scope from the project remote', async () => { - const git = async (_cwd: string, args: string[]) => args.includes('--show-toplevel') - ? '/tmp/project' - : 'git@github.com:oceanbase/powercontext.git' - await expect(deriveScopeId('/tmp/project/subdir', { git })).resolves.toBe('git:github.com/oceanbase/powercontext') + it('fixes a new session to its resolved Scope', async () => { + const request = vi.fn().mockResolvedValue({ value: { scope_id: 'scope-a' } }) + await resolveScopeId({ request } as never, { + cwd: '/workspace', + sessionID: 'session-a', + persistSession: true, + }) + expect(request.mock.calls[1]).toEqual([ + 'set_scope_binding', + { + key: { integration: 'opencode', kind: 'session', external_id: 'session-a' }, + scope_id: 'scope-a', + }, + ]) }) }) diff --git a/integrations/pi/plugins/powercontext/README.md b/integrations/pi/plugins/powercontext/README.md index 32bd21e8f..3acd2328d 100644 --- a/integrations/pi/plugins/powercontext/README.md +++ b/integrations/pi/plugins/powercontext/README.md @@ -12,6 +12,6 @@ powercontext setup pi --source /path/to/powercontext Start `powercontext server run`, then open a new Pi session in the project. The package supplies the `project-context` skill, `pc_*` Memory and Handoff tools, and `/pc` diagnostics. -Use `POWERCONTEXT_PI_BASE_URL`, `POWERCONTEXT_PI_SCOPE_ID`, and `POWERCONTEXT_PI_CAPTURE_PROMPTS` to adjust the -connection, scope, and automatic prompt capture. See the repository documentation for the full configuration and -security behavior. +The package resolves an explicit Scope, a durable workspace binding, or the Server default. Use +`POWERCONTEXT_PI_BASE_URL`, `POWERCONTEXT_PI_SCOPE_ID`, and `POWERCONTEXT_PI_CAPTURE_PROMPTS` to adjust the connection, +explicit override, and automatic prompt capture. diff --git a/integrations/pi/plugins/powercontext/extensions/powercontext.ts b/integrations/pi/plugins/powercontext/extensions/powercontext.ts index aec0102f6..7fdafefe4 100644 --- a/integrations/pi/plugins/powercontext/extensions/powercontext.ts +++ b/integrations/pi/plugins/powercontext/extensions/powercontext.ts @@ -21,7 +21,7 @@ import { resolveConfig } from '../src/config.ts' import { createPendingSourceFlusher } from '../src/flush.ts' import { createDiagnosticEmitter, failureEvent } from '../src/diagnostics.ts' import { recallBeforeAgentStart, type PluginRuntime } from '../src/recall.ts' -import { deriveScopeId } from '../src/scope.ts' +import { resolveScopeId } from '../src/scope.ts' import { registerTools } from '../src/tools.ts' function createRuntime(): PluginRuntime { @@ -37,19 +37,11 @@ function createRuntime(): PluginRuntime { if (failure) emitDiagnostic({ component: 'powercontext.pi', ...failure }) } const flusher = createPendingSourceFlusher(client, config, diagnostic) - const scopes = new Map>() return { client, config, resolveScope(cwd) { - const existing = scopes.get(cwd) - if (existing) return existing - const derived = deriveScopeId(cwd, { configuredScopeId: config.scopeId }) - scopes.set(cwd, derived) - void derived.catch(() => { - if (scopes.get(cwd) === derived) scopes.delete(cwd) - }) - return derived + return resolveScopeId(client, cwd, config.scopeId) }, recordCapture: (scopeId, position) => flusher.record(scopeId, position), flushPending: (signal) => flusher.flush(signal), diff --git a/integrations/pi/plugins/powercontext/package.json b/integrations/pi/plugins/powercontext/package.json index 9efede91b..2dab4062e 100644 --- a/integrations/pi/plugins/powercontext/package.json +++ b/integrations/pi/plugins/powercontext/package.json @@ -1,7 +1,7 @@ { "name": "powercontext-pi", "version": "0.0.2", - "description": "Native Pi package that connects to a PowerContext Server for project-scoped recall and handoff.", + "description": "Native Pi package that connects to a PowerContext Server for Scope-bound recall and handoff.", "license": "Apache-2.0", "type": "module", "keywords": [ diff --git a/integrations/pi/plugins/powercontext/pnpm-workspace.yaml b/integrations/pi/plugins/powercontext/pnpm-workspace.yaml index c19044eea..a0aff3eb7 100644 --- a/integrations/pi/plugins/powercontext/pnpm-workspace.yaml +++ b/integrations/pi/plugins/powercontext/pnpm-workspace.yaml @@ -12,6 +12,9 @@ # See the License for the specific language governing permissions and # limitations under the License. +packages: + - . + allowBuilds: '@google/genai': false esbuild: true diff --git a/integrations/pi/plugins/powercontext/skills/project-context/SKILL.md b/integrations/pi/plugins/powercontext/skills/project-context/SKILL.md index f7f0f0be5..fcc5d7ca9 100644 --- a/integrations/pi/plugins/powercontext/skills/project-context/SKILL.md +++ b/integrations/pi/plugins/powercontext/skills/project-context/SKILL.md @@ -14,7 +14,7 @@ evidence. Do not call `pc_remember` merely to duplicate the current prompt. ## Read context - Use `pc_search` with a focused query, `mode: "auto"`, and no more than eight results. -- Use `pc_memory_list` to inspect active entries in the current project scope. +- Use `pc_memory_list` to inspect active entries in the current Scope. - Use `pc_memory_get` only with an exact citation returned by search or list. - Use `pc_prepare_context` when one bounded, query-specific context value is more useful than raw search hits. diff --git a/integrations/pi/plugins/powercontext/src/client.ts b/integrations/pi/plugins/powercontext/src/client.ts index 302a73472..88abae7ba 100644 --- a/integrations/pi/plugins/powercontext/src/client.ts +++ b/integrations/pi/plugins/powercontext/src/client.ts @@ -112,19 +112,30 @@ function decodeError(bytes: Uint8Array): { code?: string; message?: string } { } } -function queryString(payload: JsonObject | undefined): string { - const params = new URLSearchParams() - for (const [key, value] of Object.entries(payload ?? {})) { - if (value !== undefined && value !== null) params.set(key, String(value)) - } - const encoded = params.toString() - return encoded ? `?${encoded}` : '' -} - function isRedirect(status: number): boolean { return status >= 300 && status < 400 } +function bindOperationPath( + spec: OperationSpec, + payload: JsonObject | undefined, +): { path: string; payload: JsonObject | undefined } { + const pathParameters: readonly string[] = spec.pathParameters + if (pathParameters.length === 0) return { path: spec.path, payload } + + const transportPayload = { ...payload } + let path: string = spec.path + for (const name of pathParameters) { + const value = transportPayload[name] + if (typeof value !== 'string' || value.trim().length === 0) { + throw new TypeError(`operation requires string path parameter ${name}`) + } + path = path.replace(`{${name}}`, encodeURIComponent(value)) + delete transportPayload[name] + } + return { path, payload: transportPayload } +} + export class PowerContextClient { private readonly baseUrl: string private readonly authorization: string | undefined @@ -141,9 +152,10 @@ export class PowerContextClient { async request(id: string, payload?: JsonObject, signal?: AbortSignal): Promise { if (!(id in OPERATIONS)) throw new UnknownOperationError(id) const spec = OPERATIONS[id as OperationId] - const url = this.buildUrl(spec, payload) + const bound = bindOperationPath(spec, payload) + const url = this.buildUrl(bound.path) try { - const response = await this.fetchImpl(url, this.buildInit(spec, payload, signal)) + const response = await this.fetchImpl(url, this.buildInit(spec, bound.payload, signal)) return await this.parseResponse(spec, response) } catch (error) { if ( @@ -153,13 +165,12 @@ export class PowerContextClient { ) { throw error } - throw new UnavailableError(spec.path, error) + throw new UnavailableError(bound.path, error) } } - private buildUrl(spec: OperationSpec, payload: JsonObject | undefined): string { - const suffix = spec.location === 'query' ? queryString(payload) : '' - return `${this.baseUrl}${spec.path}${suffix}` + private buildUrl(path: string): string { + return `${this.baseUrl}${path}` } private buildInit(spec: OperationSpec, payload: JsonObject | undefined, signal?: AbortSignal): RequestInit { @@ -176,7 +187,7 @@ export class PowerContextClient { redirect: 'manual', signal: combineSignals(signals), } - if (spec.method === 'POST' && spec.location === 'body') { + if (spec.location === 'body') { headers['Content-Type'] = 'application/json' init.body = JSON.stringify(payload ?? {}) } diff --git a/integrations/pi/plugins/powercontext/src/invoke.ts b/integrations/pi/plugins/powercontext/src/invoke.ts index f2f37ed12..dafa9b7b1 100644 --- a/integrations/pi/plugins/powercontext/src/invoke.ts +++ b/integrations/pi/plugins/powercontext/src/invoke.ts @@ -137,8 +137,11 @@ export function injectScope( payload: JsonObject | undefined, scopeId: string, ): JsonObject | undefined { - if (!OPERATIONS[operationId].scope) return payload - return { ...payload, scope_id: scopeId } + const mode = OPERATIONS[operationId].scopeMode + if (mode === 'selection') { + return { ...payload, selection: { mode: 'exact', scope_ids: [scopeId] } } + } + return mode === 'current' ? { ...payload, scope_id: scopeId } : payload } function hasSecret(value: unknown): boolean { diff --git a/integrations/pi/plugins/powercontext/src/operations.generated.ts b/integrations/pi/plugins/powercontext/src/operations.generated.ts index 092c7108a..4dd7b53a3 100644 --- a/integrations/pi/plugins/powercontext/src/operations.generated.ts +++ b/integrations/pi/plugins/powercontext/src/operations.generated.ts @@ -17,59 +17,56 @@ // generated from openapi/powercontext.yaml; do not edit. export const OPERATIONS = { - get_liveness: { method: 'GET', path: '/health/live', location: null, scope: false }, - get_readiness: { method: 'GET', path: '/health/ready', location: null, scope: false }, - get_capabilities: { method: 'GET', path: '/v1/capabilities', location: null, scope: false }, - capture_content_source: { method: 'POST', path: '/v1/sources/content', location: "body", scope: true }, - prepare_context: { method: 'POST', path: '/v1/context/prepare', location: "body", scope: true }, - create_work_contract: { method: 'POST', path: '/v1/work/contracts/create', location: "body", scope: true }, - handoff_current_work: { method: 'POST', path: '/v1/work/handoffs/prepare-current', location: "body", scope: true }, - acknowledge_handoff: { method: 'POST', path: '/v1/work/handoffs/acknowledge', location: "body", scope: true }, - record_task_outcome: { method: 'POST', path: '/v1/work/outcomes/record', location: "body", scope: true }, - activate_handoff: { method: 'POST', path: '/v1/handoff/activate', location: "body", scope: true }, - prepare_handoff: { method: 'POST', path: '/v1/handoff/prepare', location: "body", scope: true }, - finalize_handoff: { method: 'POST', path: '/v1/handoff/finalize', location: "body", scope: true }, - commit_handoff: { method: 'POST', path: '/v1/handoff/commit', location: "body", scope: true }, - continue_handoff: { method: 'POST', path: '/v1/handoff/continue', location: "body", scope: true }, - flush_memory: { method: 'POST', path: '/v1/memory/flush', location: "body", scope: true }, - remember_memory: { method: 'POST', path: '/v1/memory/remember', location: "body", scope: true }, - search_memory: { method: 'POST', path: '/v1/memory/search', location: "body", scope: true }, - list_memory_entries: { method: 'POST', path: '/v1/memory/entries/list', location: "body", scope: true }, - get_memory_entry: { method: 'POST', path: '/v1/memory/entries/get', location: "body", scope: true }, - revise_memory_entry: { method: 'POST', path: '/v1/memory/entries/revise', location: "body", scope: true }, - retire_memory_entry: { method: 'POST', path: '/v1/memory/entries/retire', location: "body", scope: true }, - list_memory_changes: { method: 'POST', path: '/v1/memory/changes', location: "body", scope: true }, - propose_experience: { method: 'POST', path: '/v1/experience/propose', location: "body", scope: true }, - generate_experience: { method: 'POST', path: '/v1/experience/generate', location: "body", scope: true }, - get_experience: { method: 'POST', path: '/v1/experience/get', location: "body", scope: true }, - propose_skill: { method: 'POST', path: '/v1/skill/propose', location: "body", scope: true }, - generate_skill: { method: 'POST', path: '/v1/skill/generate', location: "body", scope: true }, - get_skill: { method: 'POST', path: '/v1/skill/get', location: "body", scope: true }, - scan_external_skills: { method: 'POST', path: '/v1/external-skills/scan', location: "body", scope: true }, - list_external_skills: { method: 'POST', path: '/v1/external-skills/list', location: "body", scope: true }, - resolve_external_skill: { method: 'POST', path: '/v1/external-skills/resolve', location: "body", scope: true }, - import_external_skill: { method: 'POST', path: '/v1/external-skills/import', location: "body", scope: true }, - list_artifact_candidates: { method: 'POST', path: '/v1/artifact-candidates/list', location: "body", scope: true }, - get_artifact_candidate: { method: 'POST', path: '/v1/artifact-candidates/get', location: "body", scope: true }, - approve_artifact_candidate: { method: 'POST', path: '/v1/artifact-candidates/approve', location: "body", scope: true }, - reject_artifact_candidate: { method: 'POST', path: '/v1/artifact-candidates/reject', location: "body", scope: true }, - revise_artifact_candidate: { method: 'POST', path: '/v1/artifact-candidates/revise', location: "body", scope: true }, - get_stats: { method: 'GET', path: '/v1/stats', location: "query", scope: true }, - create_handoff_report_project: { method: 'POST', path: '/v1/handoff-reports/projects/create', location: "body", scope: false }, - list_handoff_report_projects: { method: 'POST', path: '/v1/handoff-reports/projects/list', location: "body", scope: false }, - list_handoff_report_known_scopes: { method: 'POST', path: '/v1/handoff-reports/scopes/list-known', location: "body", scope: false }, - get_handoff_report_project: { method: 'POST', path: '/v1/handoff-reports/projects/get', location: "body", scope: false }, - update_handoff_report_project: { method: 'POST', path: '/v1/handoff-reports/projects/update', location: "body", scope: false }, - register_handoff_report_workstream: { method: 'POST', path: '/v1/handoff-reports/workstreams/register', location: "body", scope: true }, - list_handoff_report_workstreams: { method: 'POST', path: '/v1/handoff-reports/workstreams/list', location: "body", scope: false }, - update_handoff_report_workstream: { method: 'POST', path: '/v1/handoff-reports/workstreams/update', location: "body", scope: false }, - get_handoff_report: { method: 'POST', path: '/v1/handoff-reports/get', location: "body", scope: true }, - record_handoff_report_activity: { method: 'POST', path: '/v1/handoff-reports/activities/record', location: "body", scope: true }, - list_handoff_report_activities: { method: 'POST', path: '/v1/handoff-reports/activities/list', location: "body", scope: false }, - purge_handoff_report_activities: { method: 'POST', path: '/v1/handoff-reports/activities/purge', location: "body", scope: false }, - get_handoff_report_workspace: { method: 'POST', path: '/v1/handoff-reports/workspace-bindings/get', location: "body", scope: false }, - attach_handoff_report_workspace: { method: 'POST', path: '/v1/handoff-reports/workspace-bindings/attach', location: "body", scope: false }, - detach_handoff_report_workspace: { method: 'POST', path: '/v1/handoff-reports/workspace-bindings/detach', location: "body", scope: false }, + get_liveness: { method: 'GET', path: '/health/live', location: null, scopeMode: 'none', pathParameters: [] }, + get_readiness: { method: 'GET', path: '/health/ready', location: null, scopeMode: 'none', pathParameters: [] }, + get_capabilities: { method: 'GET', path: '/v1/capabilities', location: null, scopeMode: 'none', pathParameters: [] }, + list_scopes: { method: 'GET', path: '/v1/scopes', location: null, scopeMode: 'none', pathParameters: [] }, + create_scope: { method: 'POST', path: '/v1/scopes', location: "body", scopeMode: 'none', pathParameters: [] }, + publish_artifact: { method: 'POST', path: '/v1/artifact-publications', location: "body", scopeMode: 'none', pathParameters: [] }, + get_scope: { method: 'GET', path: '/v1/scopes/{scope_id}', location: null, scopeMode: 'none', pathParameters: ['scope_id'] }, + update_scope: { method: 'PUT', path: '/v1/scopes/{scope_id}', location: "body", scopeMode: 'none', pathParameters: ['scope_id'] }, + get_default_scope: { method: 'GET', path: '/v1/scopes/default', location: null, scopeMode: 'none', pathParameters: [] }, + set_default_scope: { method: 'PUT', path: '/v1/scopes/default', location: "body", scopeMode: 'none', pathParameters: [] }, + resolve_scope_selection: { method: 'POST', path: '/v1/scopes/selection/resolve', location: "body", scopeMode: 'none', pathParameters: [] }, + resolve_scope_binding: { method: 'POST', path: '/v1/scope-bindings/resolve', location: "body", scopeMode: 'none', pathParameters: [] }, + set_scope_binding: { method: 'PUT', path: '/v1/scope-bindings', location: "body", scopeMode: 'none', pathParameters: [] }, + clear_scope_binding: { method: 'POST', path: '/v1/scope-bindings/clear', location: "body", scopeMode: 'none', pathParameters: [] }, + capture_content_source: { method: 'POST', path: '/v1/sources/content', location: "body", scopeMode: 'current', pathParameters: [] }, + prepare_context: { method: 'POST', path: '/v1/context/prepare', location: "body", scopeMode: 'current', pathParameters: [] }, + create_work_contract: { method: 'POST', path: '/v1/work/contracts/create', location: "body", scopeMode: 'current', pathParameters: [] }, + handoff_current_work: { method: 'POST', path: '/v1/work/handoffs/prepare-current', location: "body", scopeMode: 'current', pathParameters: [] }, + acknowledge_handoff: { method: 'POST', path: '/v1/work/handoffs/acknowledge', location: "body", scopeMode: 'current', pathParameters: [] }, + record_task_outcome: { method: 'POST', path: '/v1/work/outcomes/record', location: "body", scopeMode: 'current', pathParameters: [] }, + activate_handoff: { method: 'POST', path: '/v1/handoff/activate', location: "body", scopeMode: 'current', pathParameters: [] }, + prepare_handoff: { method: 'POST', path: '/v1/handoff/prepare', location: "body", scopeMode: 'current', pathParameters: [] }, + finalize_handoff: { method: 'POST', path: '/v1/handoff/finalize', location: "body", scopeMode: 'current', pathParameters: [] }, + commit_handoff: { method: 'POST', path: '/v1/handoff/commit', location: "body", scopeMode: 'current', pathParameters: [] }, + continue_handoff: { method: 'POST', path: '/v1/handoff/continue', location: "body", scopeMode: 'current', pathParameters: [] }, + flush_memory: { method: 'POST', path: '/v1/memory/flush', location: "body", scopeMode: 'current', pathParameters: [] }, + remember_memory: { method: 'POST', path: '/v1/memory/remember', location: "body", scopeMode: 'current', pathParameters: [] }, + search_memory: { method: 'POST', path: '/v1/memory/search', location: "body", scopeMode: 'current', pathParameters: [] }, + list_memory_entries: { method: 'POST', path: '/v1/memory/entries/list', location: "body", scopeMode: 'current', pathParameters: [] }, + get_memory_entry: { method: 'POST', path: '/v1/memory/entries/get', location: "body", scopeMode: 'current', pathParameters: [] }, + revise_memory_entry: { method: 'POST', path: '/v1/memory/entries/revise', location: "body", scopeMode: 'current', pathParameters: [] }, + retire_memory_entry: { method: 'POST', path: '/v1/memory/entries/retire', location: "body", scopeMode: 'current', pathParameters: [] }, + list_memory_changes: { method: 'POST', path: '/v1/memory/changes', location: "body", scopeMode: 'current', pathParameters: [] }, + propose_experience: { method: 'POST', path: '/v1/experience/propose', location: "body", scopeMode: 'current', pathParameters: [] }, + generate_experience: { method: 'POST', path: '/v1/experience/generate', location: "body", scopeMode: 'current', pathParameters: [] }, + get_experience: { method: 'POST', path: '/v1/experience/get', location: "body", scopeMode: 'current', pathParameters: [] }, + propose_skill: { method: 'POST', path: '/v1/skill/propose', location: "body", scopeMode: 'current', pathParameters: [] }, + generate_skill: { method: 'POST', path: '/v1/skill/generate', location: "body", scopeMode: 'current', pathParameters: [] }, + get_skill: { method: 'POST', path: '/v1/skill/get', location: "body", scopeMode: 'current', pathParameters: [] }, + scan_external_skills: { method: 'POST', path: '/v1/external-skills/scan', location: "body", scopeMode: 'current', pathParameters: [] }, + list_external_skills: { method: 'POST', path: '/v1/external-skills/list', location: "body", scopeMode: 'current', pathParameters: [] }, + resolve_external_skill: { method: 'POST', path: '/v1/external-skills/resolve', location: "body", scopeMode: 'current', pathParameters: [] }, + import_external_skill: { method: 'POST', path: '/v1/external-skills/import', location: "body", scopeMode: 'current', pathParameters: [] }, + list_artifact_candidates: { method: 'POST', path: '/v1/artifact-candidates/list', location: "body", scopeMode: 'current', pathParameters: [] }, + get_artifact_candidate: { method: 'POST', path: '/v1/artifact-candidates/get', location: "body", scopeMode: 'current', pathParameters: [] }, + approve_artifact_candidate: { method: 'POST', path: '/v1/artifact-candidates/approve', location: "body", scopeMode: 'current', pathParameters: [] }, + reject_artifact_candidate: { method: 'POST', path: '/v1/artifact-candidates/reject', location: "body", scopeMode: 'current', pathParameters: [] }, + revise_artifact_candidate: { method: 'POST', path: '/v1/artifact-candidates/revise', location: "body", scopeMode: 'current', pathParameters: [] }, + get_stats: { method: 'POST', path: '/v1/stats', location: "body", scopeMode: 'selection', pathParameters: [] }, + get_handoff_report: { method: 'POST', path: '/v1/handoff-reports/get', location: "body", scopeMode: 'selection', pathParameters: [] }, } as const export type OperationId = keyof typeof OPERATIONS diff --git a/integrations/pi/plugins/powercontext/src/recall.ts b/integrations/pi/plugins/powercontext/src/recall.ts index a9e8e14df..9bad7f57c 100644 --- a/integrations/pi/plugins/powercontext/src/recall.ts +++ b/integrations/pi/plugins/powercontext/src/recall.ts @@ -60,8 +60,19 @@ export async function recallBeforeAgentStart(input: BeforeAgentStartInput): Prom const prompt = input.prompt.trim() if (!prompt) return undefined + let scopeId: string + try { + scopeId = await input.runtime.resolveScope(input.cwd) + } catch (error) { + try { + input.runtime.diagnostic?.('context_prepare', error) + } catch { + // Diagnostics are best effort and must not affect the turn. + } + return undefined + } + try { - const scopeId = await input.runtime.resolveScope(input.cwd) const signals = [createTimeoutSignal(input.runtime.config.httpBudgetMs)] if (input.signal) signals.push(input.signal) const signal = combineSignals(signals) diff --git a/integrations/pi/plugins/powercontext/src/scope.ts b/integrations/pi/plugins/powercontext/src/scope.ts index 90ebcb387..0f5f51d2d 100644 --- a/integrations/pi/plugins/powercontext/src/scope.ts +++ b/integrations/pi/plugins/powercontext/src/scope.ts @@ -15,91 +15,30 @@ */ import { createHash } from 'node:crypto' -import { spawn } from 'node:child_process' import { resolve } from 'node:path' +import type { PowerContextClient } from './client.ts' -const MAX_SCOPE_LENGTH = 256 -const SCP_REMOTE = /^(?:[^@/\s]+@)?(?[^:/\s]+):(?.+)$/ +type ScopeBindingKey = { integration: string; kind: string; external_id: string } -export type GitRunner = (cwd: string, args: string[]) => Promise - -function bounded(prefix: string, value: string): string { - const candidate = `${prefix}:${value}` - if (candidate.length <= MAX_SCOPE_LENGTH) return candidate - return `${prefix}:sha256:${createHash('sha256').update(value).digest('hex')}` -} - -function boundedExplicit(value: string): string { - if (value.length <= MAX_SCOPE_LENGTH) return value - return `sha256:${createHash('sha256').update(value).digest('hex')}` -} - -function normalizePath(path: string): string { - let normalized = path.replaceAll('\\', '/').split('/').filter(Boolean).join('/') - if (normalized.endsWith('.git')) normalized = normalized.slice(0, -4) - return normalized.replace(/\/+$/, '') -} - -export function normalizeGitRemote(remote: string): string | undefined { - const value = remote.trim() - if (!value) return undefined - const scpMatch = !value.includes('://') ? value.match(SCP_REMOTE) : null - if (scpMatch?.groups) { - const host = scpMatch.groups.host.toLowerCase() - const path = normalizePath(scpMatch.groups.path) - return path ? `${host}/${path}` : undefined - } - let parsed: URL - try { - parsed = new URL(value) - } catch { - return undefined +export function workspaceBindingKey(cwd: string): ScopeBindingKey { + return { + integration: 'pi', + kind: 'workspace', + external_id: createHash('sha256').update(resolve(cwd)).digest('hex'), } - if (!['http:', 'https:', 'ssh:', 'git:'].includes(parsed.protocol) || !parsed.hostname) return undefined - const host = parsed.port ? `${parsed.hostname.toLowerCase()}:${parsed.port}` : parsed.hostname.toLowerCase() - const path = normalizePath(parsed.pathname) - return path ? `${host}/${path}` : undefined -} - -export function spawnGit(cwd: string, args: string[]): Promise { - return new Promise((finish) => { - const child = spawn('git', args, { cwd, windowsHide: true }) - const chunks: Buffer[] = [] - let settled = false - const resolveOnce = (result: string | undefined) => { - if (settled) return - settled = true - clearTimeout(timer) - finish(result) - } - const timer = setTimeout(() => { - child.kill() - resolveOnce(undefined) - }, 2000) - timer.unref() - child.stdout.on('data', (chunk: Buffer) => chunks.push(chunk)) - child.on('error', () => resolveOnce(undefined)) - child.on('close', (code) => { - if (code !== 0) { - resolveOnce(undefined) - return - } - const output = Buffer.concat(chunks).toString('utf8').trim() - resolveOnce(output || undefined) - }) - }) } -export async function deriveScopeId( +export async function resolveScopeId( + client: PowerContextClient, cwd: string, - options: { configuredScopeId?: string; git?: GitRunner } = {}, + configuredScopeId?: string, ): Promise { - if (options.configuredScopeId) return boundedExplicit(options.configuredScopeId) - const git = options.git ?? spawnGit - const rootValue = await git(cwd, ['rev-parse', '--show-toplevel']) - const projectRoot = resolve(rootValue || cwd) - const remote = await git(projectRoot, ['config', '--get', 'remote.origin.url']) - const normalized = remote ? normalizeGitRemote(remote) : undefined - if (normalized) return bounded('git', normalized) - return `local:${createHash('sha256').update(projectRoot).digest('hex')}` + const response = await client.request('resolve_scope_binding', { + explicit_scope_id: configuredScopeId, + binding_keys: [workspaceBindingKey(cwd)], + }) + const value = response.value + const scopeId = value && typeof value === 'object' ? (value as { scope_id?: unknown }).scope_id : undefined + if (typeof scopeId !== 'string' || !scopeId.trim()) throw new Error('PowerContext returned an invalid Scope') + return scopeId } diff --git a/integrations/pi/plugins/powercontext/src/tools.ts b/integrations/pi/plugins/powercontext/src/tools.ts index 19d00b428..4dbc28dcd 100644 --- a/integrations/pi/plugins/powercontext/src/tools.ts +++ b/integrations/pi/plugins/powercontext/src/tools.ts @@ -140,7 +140,7 @@ export function registerTools(pi: ExtensionAPI, runtime: PluginRuntime): void { registerOperationTool(pi, runtime, { name: 'pc_memory_list', label: 'PowerContext Memory List', - description: 'List Memory entries in the current project scope.', + description: 'List Memory entries in the current Scope.', parameters: Type.Object({ include_inactive: Type.Optional(Type.Boolean({ description: 'Include retired entries for an explicit audit.' })), }), diff --git a/integrations/pi/plugins/powercontext/tests/client.spec.ts b/integrations/pi/plugins/powercontext/tests/client.spec.ts index 2c3ce2dc0..54d012720 100644 --- a/integrations/pi/plugins/powercontext/tests/client.spec.ts +++ b/integrations/pi/plugins/powercontext/tests/client.spec.ts @@ -18,6 +18,33 @@ import { describe, expect, it, vi } from 'vitest' import { PowerContextClient } from '../src/client.ts' describe('PowerContext Pi HTTP client', () => { + it('binds scope resource paths and omits path values from the request body', async () => { + const requests: Array<{ url: string; init: RequestInit }> = [] + const client = new PowerContextClient({ + baseUrl: 'http://127.0.0.1:8000', + requestTimeoutMs: 1000, + fetch: async (url, init) => { + requests.push({ url, init }) + return new Response(JSON.stringify({ scope_id: 'scope:feature' }), { status: 200 }) + }, + }) + + await client.request('get_scope', { scope_id: 'scope:feature' }) + await client.request('update_scope', { + scope_id: 'scope:feature', + expected_version: 1, + title: 'Feature', + summary: 'Current work', + }) + + expect(requests.map((request) => request.url)).toEqual([ + 'http://127.0.0.1:8000/v1/scopes/scope%3Afeature', + 'http://127.0.0.1:8000/v1/scopes/scope%3Afeature', + ]) + expect(requests[0].init.body).toBeUndefined() + expect(JSON.parse(String(requests[1].init.body))).not.toHaveProperty('scope_id') + }) + it('posts JSON with authorization and rejects redirects', async () => { const fetch = vi.fn(async (url: string, init?: RequestInit) => { expect(url).toBe('http://127.0.0.1:8000/v1/context/prepare') diff --git a/integrations/pi/plugins/powercontext/tests/commands.spec.ts b/integrations/pi/plugins/powercontext/tests/commands.spec.ts index da11dfc1a..69fdbf8d2 100644 --- a/integrations/pi/plugins/powercontext/tests/commands.spec.ts +++ b/integrations/pi/plugins/powercontext/tests/commands.spec.ts @@ -19,7 +19,7 @@ import { handlePcCommand } from '../src/commands.ts' import { PowerContextClient } from '../src/client.ts' import type { PluginRuntime } from '../src/recall.ts' -function runtime(fetch: typeof globalThis.fetch, resolveScope = async () => 'project:demo'): PluginRuntime { +function runtime(fetch: typeof globalThis.fetch, resolveScope = async () => 'scope:demo'): PluginRuntime { return { client: new PowerContextClient({ baseUrl: 'http://127.0.0.1:8000', @@ -46,7 +46,7 @@ afterEach(() => { }) describe('/pc command', () => { - it('dispatches query commands with the current project scope and reports results', async () => { + it('dispatches query commands with the current Scope and reports results', async () => { const requests: Array<{ url: URL; body: unknown }> = [] const notifications: Array<{ message: string; level: 'info' | 'error' }> = [] const fetch = async (url: string | URL | Request, init?: RequestInit) => { @@ -76,9 +76,9 @@ describe('/pc command', () => { const stats = requests.find(({ url }) => url.pathname === '/v1/stats') const live = requests.find(({ url }) => url.pathname === '/health/live') const ready = requests.find(({ url }) => url.pathname === '/health/ready') - expect(search?.body).toEqual({ query: 'prior decision', limit: 8, mode: 'auto', scope_id: 'project:demo' }) - expect(flush?.body).toEqual({ scope_id: 'project:demo' }) - expect(stats?.url.searchParams.get('scope_id')).toBe('project:demo') + expect(search?.body).toEqual({ query: 'prior decision', limit: 8, mode: 'auto', scope_id: 'scope:demo' }) + expect(flush?.body).toEqual({ scope_id: 'scope:demo' }) + expect(stats?.body).toEqual({ selection: { mode: 'exact', scope_ids: ['scope:demo'] } }) expect(live).toBeDefined() expect(ready).toBeDefined() expect(notifications.some(({ message }) => JSON.parse(message).ok === true)).toBe(true) diff --git a/integrations/pi/plugins/powercontext/tests/extension.spec.ts b/integrations/pi/plugins/powercontext/tests/extension.spec.ts index 534f42e0c..f997a8eda 100644 --- a/integrations/pi/plugins/powercontext/tests/extension.spec.ts +++ b/integrations/pi/plugins/powercontext/tests/extension.spec.ts @@ -29,15 +29,27 @@ function installExtension(): Map { return handlers } +function scopeAwareFetch( + handler: (url: string, init?: RequestInit) => Promise, + scopeId = 'project:demo', +) { + return vi.fn(async (url: string, init?: RequestInit) => { + if (url.endsWith('/v1/scope-bindings/resolve')) { + return new Response(JSON.stringify({ scope_id: scopeId })) + } + return handler(url, init) + }) +} + afterEach(() => { vi.unstubAllEnvs() vi.unstubAllGlobals() }) describe('PowerContext Pi extension', () => { - it('injects prepared context and captures the submitted prompt in the current project scope', async () => { + it('injects prepared context and captures the submitted prompt in the current Scope', async () => { vi.stubEnv('POWERCONTEXT_PI_SCOPE_ID', 'project:demo') - const fetch = vi.fn(async (url: string, _init?: RequestInit) => { + const fetch = scopeAwareFetch(async (url: string, _init?: RequestInit) => { if (url.endsWith('/v1/context/prepare')) { return new Response(JSON.stringify({ schema: 'powercontext.prepared-context.v1', @@ -111,7 +123,7 @@ describe('PowerContext Pi extension', () => { it('reports a prepare domain failure from the actual endpoint', async () => { vi.stubEnv('POWERCONTEXT_PI_SCOPE_ID', 'project:demo') vi.stubEnv('POWERCONTEXT_PI_CAPTURE_PROMPTS', 'false') - const fetch = vi.fn(async (url: string) => { + const fetch = scopeAwareFetch(async (url: string) => { expect(url).toBe('http://127.0.0.1:8000/v1/context/prepare') return new Response(JSON.stringify({ error: { code: 'invalid_request' } }), { status: 422 }) }) @@ -137,7 +149,7 @@ describe('PowerContext Pi extension', () => { it('reports a capture domain failure from the actual endpoint', async () => { vi.stubEnv('POWERCONTEXT_PI_SCOPE_ID', 'project:demo') - const fetch = vi.fn(async (url: string) => { + const fetch = scopeAwareFetch(async (url: string) => { if (url === 'http://127.0.0.1:8000/v1/context/prepare') { return new Response(JSON.stringify({ schema: 'powercontext.prepared-context.v1', @@ -173,7 +185,7 @@ describe('PowerContext Pi extension', () => { vi.stubEnv('POWERCONTEXT_PI_SCOPE_ID', 'project:demo') vi.stubEnv('POWERCONTEXT_PI_FLUSH_ON_CAPTURE', 'true') vi.stubEnv('POWERCONTEXT_PI_FLUSH_MAX_CALLS', '1') - const fetch = vi.fn(async (url: string) => { + const fetch = scopeAwareFetch(async (url: string) => { if (url === 'http://127.0.0.1:8000/v1/context/prepare') { return new Response(JSON.stringify({ schema: 'powercontext.prepared-context.v1', @@ -210,7 +222,7 @@ describe('PowerContext Pi extension', () => { it('keeps recalled context when independent prompt capture fails', async () => { vi.stubEnv('POWERCONTEXT_PI_SCOPE_ID', 'project:demo') - const fetch = vi.fn(async (url: string, _init?: RequestInit) => { + const fetch = scopeAwareFetch(async (url: string, _init?: RequestInit) => { if (url.endsWith('/v1/context/prepare')) { return new Response(JSON.stringify({ schema: 'powercontext.prepared-context.v1', @@ -240,7 +252,7 @@ describe('PowerContext Pi extension', () => { it('flushes a captured Source at the compaction boundary', async () => { vi.stubEnv('POWERCONTEXT_PI_SCOPE_ID', 'project:demo') - const fetch = vi.fn(async (url: string, _init?: RequestInit) => { + const fetch = scopeAwareFetch(async (url: string, _init?: RequestInit) => { if (url.endsWith('/v1/context/prepare')) { return new Response(JSON.stringify({ schema: 'powercontext.prepared-context.v1', @@ -277,7 +289,7 @@ describe('PowerContext Pi extension', () => { vi.stubEnv('POWERCONTEXT_PI_FLUSH_ON_CAPTURE', 'true') vi.stubEnv('POWERCONTEXT_PI_FLUSH_MAX_CALLS', '4') let flushAttempts = 0 - const fetch = vi.fn(async (url: string) => { + const fetch = scopeAwareFetch(async (url: string) => { if (url.endsWith('/v1/context/prepare')) { return new Response(JSON.stringify({ schema: 'powercontext.prepared-context.v1', @@ -316,7 +328,7 @@ describe('PowerContext Pi extension', () => { vi.stubEnv('POWERCONTEXT_PI_FLUSH_ON_CAPTURE', 'true') vi.stubEnv('POWERCONTEXT_PI_FLUSH_MAX_CALLS', '1') let flushAttempts = 0 - const fetch = vi.fn(async (url: string) => { + const fetch = scopeAwareFetch(async (url: string) => { if (url.endsWith('/v1/context/prepare')) { return new Response(JSON.stringify({ schema: 'powercontext.prepared-context.v1', @@ -357,7 +369,7 @@ describe('PowerContext Pi extension', () => { it('does not persist a prompt when capture is disabled', async () => { vi.stubEnv('POWERCONTEXT_PI_CAPTURE_PROMPTS', 'false') - const fetch = vi.fn().mockResolvedValue(new Response(JSON.stringify({ + const fetch = scopeAwareFetch(async () => new Response(JSON.stringify({ schema: 'powercontext.prepared-context.v1', status: 'empty', content: null, @@ -381,7 +393,7 @@ describe('PowerContext Pi extension', () => { }) it('does not persist a secret-looking prompt', async () => { - const fetch = vi.fn().mockResolvedValue(new Response(JSON.stringify({ + const fetch = scopeAwareFetch(async () => new Response(JSON.stringify({ schema: 'powercontext.prepared-context.v1', status: 'empty', content: null, @@ -405,7 +417,7 @@ describe('PowerContext Pi extension', () => { }) it('does not persist a prompt containing a conventional password assignment', async () => { - const fetch = vi.fn().mockResolvedValue(new Response(JSON.stringify({ + const fetch = scopeAwareFetch(async () => new Response(JSON.stringify({ schema: 'powercontext.prepared-context.v1', status: 'empty', content: null, @@ -429,7 +441,7 @@ describe('PowerContext Pi extension', () => { }) it('captures ordinary text containing marker-like substrings', async () => { - const fetch = vi.fn(async (url: string) => { + const fetch = scopeAwareFetch(async (url: string) => { if (url.endsWith('/v1/context/prepare')) { return new Response(JSON.stringify({ schema: 'powercontext.prepared-context.v1', @@ -459,7 +471,7 @@ describe('PowerContext Pi extension', () => { }) it('does not persist a prompt above the source size limit', async () => { - const fetch = vi.fn().mockResolvedValue(new Response(JSON.stringify({ + const fetch = scopeAwareFetch(async () => new Response(JSON.stringify({ schema: 'powercontext.prepared-context.v1', status: 'empty', content: null, diff --git a/integrations/pi/plugins/powercontext/tests/invoke.spec.ts b/integrations/pi/plugins/powercontext/tests/invoke.spec.ts index 8e387a38e..64a618759 100644 --- a/integrations/pi/plugins/powercontext/tests/invoke.spec.ts +++ b/integrations/pi/plugins/powercontext/tests/invoke.spec.ts @@ -34,7 +34,7 @@ describe('secret detection', () => { }) describe('Pi native tool invocation', () => { - it('uses the derived scope and refuses secret-bearing writes', async () => { + it('uses the resolved scope and refuses secret-bearing writes', async () => { let body: string | undefined const client = new PowerContextClient({ baseUrl: 'http://127.0.0.1:8000', @@ -47,16 +47,39 @@ describe('Pi native tool invocation', () => { await expect(invokeOperation(client, 'search_memory', { query: 'prior decision', - scope_id: 'project:untrusted', - }, 'project:derived')).resolves.toMatchObject({ ok: true }) - expect(JSON.parse(body ?? '{}')).toMatchObject({ scope_id: 'project:derived' }) + scope_id: 'scope:untrusted', + }, 'scp_resolved')).resolves.toMatchObject({ ok: true }) + expect(JSON.parse(body ?? '{}')).toMatchObject({ scope_id: 'scp_resolved' }) await expect(invokeOperation(client, 'remember_memory', { kind: 'agent-note', text: 'api_key=secret', - }, 'project:derived')).resolves.toMatchObject({ + }, 'scp_resolved')).resolves.toMatchObject({ ok: false, code: 'secret_rejected', }) }) + + it('limits observation requests to the derived Scope', async () => { + const bodies: unknown[] = [] + const client = new PowerContextClient({ + baseUrl: 'http://127.0.0.1:8000', + requestTimeoutMs: 1000, + fetch: async (_url, init) => { + bodies.push(JSON.parse(String(init?.body))) + return new Response(JSON.stringify({}), { status: 200 }) + }, + }) + + await invokeOperation(client, 'get_stats', { selection: { mode: 'all' } }, 'scp_resolved') + await invokeOperation(client, 'get_handoff_report', { + selection: { mode: 'subtree', root_scope_id: 'scope:other' }, + format: 'json', + }, 'scp_resolved') + + expect(bodies).toEqual([ + { selection: { mode: 'exact', scope_ids: ['scp_resolved'] } }, + { selection: { mode: 'exact', scope_ids: ['scp_resolved'] }, format: 'json' }, + ]) + }) }) diff --git a/integrations/pi/plugins/powercontext/tests/scope.spec.ts b/integrations/pi/plugins/powercontext/tests/scope.spec.ts index 3f84c837a..3f0b49484 100644 --- a/integrations/pi/plugins/powercontext/tests/scope.spec.ts +++ b/integrations/pi/plugins/powercontext/tests/scope.spec.ts @@ -14,27 +14,27 @@ * limitations under the License. */ -import { createHash } from 'node:crypto' -import { resolve } from 'node:path' -import { describe, expect, it } from 'vitest' -import { deriveScopeId, normalizeGitRemote } from '../src/scope.ts' +import { describe, expect, it, vi } from 'vitest' +import { resolveScopeId } from '../src/scope.ts' -describe('Pi project scope', () => { - it('uses the normalized Git remote and never retains credentials', async () => { - expect(normalizeGitRemote('https://token@github.com/acme/powercontext.git')).toBe('github.com/acme/powercontext') - const git = async (_cwd: string, args: string[]) => { - if (args[0] === 'rev-parse') return '/workspace/powercontext' - if (args[0] === 'config') return 'git@github.com:acme/powercontext.git' - return undefined - } - await expect(deriveScopeId('/workspace/powercontext', { git })).resolves.toBe('git:github.com/acme/powercontext') - }) +describe('Scope binding', () => { + it('resolves explicit, durable, and default precedence on the Server', async () => { + const request = vi.fn().mockResolvedValue({ value: { scope_id: 'scp_00000000000000000000000000' } }) + const client = { request } as never - it('uses a bounded explicit scope and falls back to the project path', async () => { - await expect(deriveScopeId('/workspace/powercontext', { configuredScopeId: 'project:demo' })).resolves.toBe('project:demo') - const cwd = resolve('/tmp/no-git-project') - await expect(deriveScopeId(cwd, { git: async () => undefined })).resolves.toBe( - `local:${createHash('sha256').update(cwd).digest('hex')}`, + await expect(resolveScopeId(client, '/workspace/powercontext', 'explicit-scope')).resolves.toBe( + 'scp_00000000000000000000000000', ) + const [operation, input] = request.mock.calls[0] + expect(operation).toBe('resolve_scope_binding') + expect(input.explicit_scope_id).toBe('explicit-scope') + expect(input.binding_keys).toHaveLength(1) + expect(input.binding_keys[0]).toMatchObject({ integration: 'pi', kind: 'workspace' }) + expect(input.binding_keys[0].external_id).not.toContain('/workspace/powercontext') + }) + + it('rejects an invalid resolver response', async () => { + const client = { request: vi.fn().mockResolvedValue({ value: {} }) } as never + await expect(resolveScopeId(client, '/workspace/powercontext')).rejects.toThrow('invalid Scope') }) }) diff --git a/integrations/pydantic-ai/README.md b/integrations/pydantic-ai/README.md index 2abb958c9..fad2bd6ae 100644 --- a/integrations/pydantic-ai/README.md +++ b/integrations/pydantic-ai/README.md @@ -45,7 +45,7 @@ Environment variables use the `POWERCONTEXT_PYDANTIC_AI_` prefix. | --- | --- | --- | | `BASE_URL` | `http://127.0.0.1:8000` | PowerContext Server HTTP base URL | | `TOKEN` | unset | Bare Server token; the Client adds the `Bearer` scheme | -| `SCOPE_ID` | derived | Durable project scope | +| `SCOPE_ID` | unset | Existing explicit Server Scope; unset selects the Server default | | `TIMEOUT` | `10` | HTTP timeout in seconds | | `MAX_BYTES` | `8000` | Maximum prepared-context bytes | | `CAPTURE_EVENTS` | `false` | Capture visible agent trajectory events as Sources | @@ -57,8 +57,11 @@ only the opaque token, not `Bearer TOKEN` or a complete `Authorization` header. and passed to `PowerContextClient`, which constructs the header. Both components accept `settings=`, `id=` (default `powercontext`), and `scope_id=`. `scope_id` can be a fixed string -or a callable receiving the current `RunContext`. Resolution order is constructor value or callback, environment -`SCOPE_ID`, normalized Git origin, then `local:`. A callback is evaluated once per run. +or a callable receiving the current `RunContext`. Resolution order is constructor value or callback, then environment +`SCOPE_ID`. The adapter sends that explicit ID, or `None`, to the Server's `resolve_scope_binding` operation once per +run and reuses the returned Scope ID throughout the run. Unset configuration selects the Server default. Explicit +IDs must already identify a Server Scope. The adapter never inspects the working directory, Git repository, or path +to create an ID. A callback is evaluated once per run. ## Recall, capture, and trust diff --git a/integrations/pydantic-ai/src/powercontext_pydantic_ai/capability.py b/integrations/pydantic-ai/src/powercontext_pydantic_ai/capability.py index 2b7445e06..9f7a1206a 100644 --- a/integrations/pydantic-ai/src/powercontext_pydantic_ai/capability.py +++ b/integrations/pydantic-ai/src/powercontext_pydantic_ai/capability.py @@ -218,7 +218,7 @@ async def after_run( async def _prepare_context(self, query: str) -> str | None: state = self._require_state() request = PrepareContextRequest( - scope_id=state.scope_id, + scope_id=state.require_scope_id(), query=query[:8192], max_bytes=self.settings.max_bytes, ) @@ -244,7 +244,8 @@ async def _capture_event( async with state.lock: state.sequence += 1 sequence = state.sequence - source_id = _source_id(state.scope_id, state.run_id, sequence, event) + scope_id = state.require_scope_id() + source_id = _source_id(scope_id, state.run_id, sequence, event) try: content = render_capture_event( event, @@ -266,7 +267,7 @@ async def _capture_event( metadata["conversation_id"] = conversation_id response = await self._toolset._require_client().capture_content_source( CaptureContentSourceRequest( - scope_id=state.scope_id, + scope_id=scope_id, source_id=source_id, content=content, metadata=metadata, @@ -291,6 +292,7 @@ async def _capture_event( async def _flush_locked(self, *, final: bool) -> None: state = self._require_state() + scope_id = state.require_scope_id() target_position = state.captured_position if target_position <= state.flushed_position: return @@ -298,9 +300,7 @@ async def _flush_locked(self, *, final: bool) -> None: async with asyncio.timeout(self.settings.timeout): while state.flushed_position < target_position: previous_position = state.flushed_position - response = await self._toolset._require_client().flush_memory( - FlushMemoryRequest(scope_id=state.scope_id) - ) + response = await self._toolset._require_client().flush_memory(FlushMemoryRequest(scope_id=scope_id)) state.flushed_position = max(state.flushed_position, response.current_cursor) if state.flushed_position <= previous_position: logger.debug( diff --git a/integrations/pydantic-ai/src/powercontext_pydantic_ai/scope.py b/integrations/pydantic-ai/src/powercontext_pydantic_ai/scope.py index 44c455b58..0874c7383 100644 --- a/integrations/pydantic-ai/src/powercontext_pydantic_ai/scope.py +++ b/integrations/pydantic-ai/src/powercontext_pydantic_ai/scope.py @@ -12,100 +12,45 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Stable project scope derivation for Pydantic AI runs.""" +"""Server-backed Scope resolution for Pydantic AI runs.""" from __future__ import annotations -import hashlib -import os -import re -import subprocess from collections.abc import Callable -from pathlib import Path -from shutil import which from typing import Any, TypeAlias, cast -from urllib.parse import urlsplit from pydantic_ai import RunContext -from powercontext.limits import MAX_SCOPE_ID_LENGTH +from powercontext.client import PowerContextClient +from powercontext.http import ResolveScopeBindingRequest ScopeId: TypeAlias = str | Callable[[RunContext[Any]], str] | None -_SCP_REMOTE = re.compile(r"^(?:[^@/\s]+@)?(?P[^:/\s]+):(?P.+)$") - -def resolve_scope_id( +async def resolve_scope_binding( + client: PowerContextClient, ctx: RunContext[Any], constructor_scope_id: ScopeId, settings_scope_id: str | None, - *, - cwd: str | os.PathLike[str] | None = None, ) -> str: - """Resolve one scope using constructor, environment, Git, then local precedence.""" + """Resolve an explicit Scope or the Server default for one run.""" + + explicit_scope_id = _explicit_scope_id(ctx, constructor_scope_id, settings_scope_id) + resolved = await client.resolve_scope_binding(ResolveScopeBindingRequest(explicit_scope_id=explicit_scope_id)) + return resolved.scope_id + +def _explicit_scope_id( + ctx: RunContext[Any], + constructor_scope_id: ScopeId, + settings_scope_id: str | None, +) -> str | None: if isinstance(constructor_scope_id, str): - return _bounded_explicit(_require_scope(constructor_scope_id)) + return _require_scope(constructor_scope_id) if constructor_scope_id is not None: resolver = cast(Callable[[RunContext[Any]], str], constructor_scope_id) - return _bounded_explicit(_require_scope(resolver(ctx))) - if settings_scope_id is not None: - return _bounded_explicit(_require_scope(settings_scope_id)) - return derive_scope_id(cwd) - - -def derive_scope_id(cwd: str | os.PathLike[str] | None = None) -> str: - """Derive a stable scope from the normalized origin or resolved project path.""" - - working_directory = os.fspath(cwd) if cwd is not None else os.getcwd() - root_value = _git_value(working_directory, "rev-parse", "--show-toplevel") - project_root = Path(root_value or working_directory).resolve(strict=False) - remote = _git_value(os.fspath(project_root), "config", "--get", "remote.origin.url") - normalized_remote = normalize_git_remote(remote) if remote else None - if normalized_remote: - return _bounded("git", normalized_remote) - return f"local:{hashlib.sha256(os.fsencode(project_root)).hexdigest()}" - - -def normalize_git_remote(remote: str) -> str | None: - """Normalize common network remotes without retaining credentials.""" - - value = remote.strip() - if not value: - return None - scp_match = _SCP_REMOTE.fullmatch(value) - if scp_match and "://" not in value: - host = scp_match.group("host").lower() - path = _normalize_path(scp_match.group("path")) - return f"{host}/{path}" if path else None - parsed = urlsplit(value) - if parsed.scheme not in {"http", "https", "ssh", "git"} or parsed.hostname is None: - return None - host = parsed.hostname.lower() - if parsed.port is not None: - host = f"{host}:{parsed.port}" - path = _normalize_path(parsed.path) - return f"{host}/{path}" if path else None - - -def _normalize_path(path: str) -> str: - normalized = "/".join(part for part in path.replace("\\", "/").split("/") if part) - if normalized.endswith(".git"): - normalized = normalized[:-4] - return normalized.rstrip("/") - - -def _bounded(prefix: str, value: str) -> str: - candidate = f"{prefix}:{value}" - if len(candidate) <= MAX_SCOPE_ID_LENGTH: - return candidate - return f"{prefix}:sha256:{hashlib.sha256(value.encode()).hexdigest()}" - - -def _bounded_explicit(value: str) -> str: - if len(value) <= MAX_SCOPE_ID_LENGTH: - return value - return f"sha256:{hashlib.sha256(value.encode()).hexdigest()}" + return _require_scope(resolver(ctx)) + return settings_scope_id def _require_scope(value: object) -> str: @@ -115,21 +60,3 @@ def _require_scope(value: object) -> str: if not normalized: raise ValueError("PowerContext scope_id must contain non-whitespace characters") # noqa: TRY003 return normalized - - -def _git_value(cwd: str, *arguments: str) -> str | None: - executable = which("git") - if executable is None: - return None - try: - completed = subprocess.run( # noqa: S603 - executable and arguments are integration-owned. - [executable, *arguments], - cwd=cwd, - check=True, - capture_output=True, - text=True, - timeout=2, - ) - except (OSError, subprocess.SubprocessError): - return None - return completed.stdout.strip() or None diff --git a/integrations/pydantic-ai/src/powercontext_pydantic_ai/settings.py b/integrations/pydantic-ai/src/powercontext_pydantic_ai/settings.py index 36dd40fa3..113c6f85e 100644 --- a/integrations/pydantic-ai/src/powercontext_pydantic_ai/settings.py +++ b/integrations/pydantic-ai/src/powercontext_pydantic_ai/settings.py @@ -21,6 +21,8 @@ from pydantic import Field, HttpUrl, SecretStr, TypeAdapter, field_validator from pydantic_settings import BaseSettings, SettingsConfigDict +from powercontext.limits import MAX_SCOPE_ID_LENGTH + _HTTP_URL_ADAPTER = TypeAdapter(HttpUrl) @@ -37,7 +39,7 @@ class PowerContextSettings(BaseSettings): base_url: str = "http://127.0.0.1:8000" token: SecretStr | None = Field(default=None, repr=False) - scope_id: str | None = Field(default=None, min_length=1) + scope_id: str | None = Field(default=None, min_length=1, max_length=MAX_SCOPE_ID_LENGTH) timeout: float = Field(default=10, gt=0) max_bytes: int = Field(default=8000, ge=512, le=32768) capture_events: bool = False diff --git a/integrations/pydantic-ai/src/powercontext_pydantic_ai/toolset.py b/integrations/pydantic-ai/src/powercontext_pydantic_ai/toolset.py index f288ec1cc..8e4ccca76 100644 --- a/integrations/pydantic-ai/src/powercontext_pydantic_ai/toolset.py +++ b/integrations/pydantic-ai/src/powercontext_pydantic_ai/toolset.py @@ -31,7 +31,7 @@ from powercontext.client import ClientError, PowerContextClient, ServerResponseError from powercontext.http import MemorySearchMode, PrepareContextRequest, RememberMemoryRequest, SearchMemoryRequest -from powercontext_pydantic_ai.scope import ScopeId, resolve_scope_id +from powercontext_pydantic_ai.scope import ScopeId, resolve_scope_binding from powercontext_pydantic_ai.settings import PowerContextSettings logger = logging.getLogger(__name__) @@ -54,9 +54,10 @@ @dataclass(slots=True) class _RunState: - scope_id: str + run_context: RunContext[Any] run_id: str conversation_id: str | None + scope_id: str | None = None lock: asyncio.Lock = field(default_factory=asyncio.Lock) client: PowerContextClient | None = None sequence: int = 0 @@ -66,6 +67,11 @@ class _RunState: prompt_captured: bool = False context_injected: bool = False + def require_scope_id(self) -> str: + if self.scope_id is None: + raise RuntimeError("PowerContext Scope must be resolved before use") # noqa: TRY003 + return self.scope_id + class _AuthFailureReporter: """Log one actionable authentication warning without credential material.""" @@ -123,16 +129,15 @@ def __init__( async def for_run(self, ctx: RunContext[AgentDepsT]) -> PowerContextToolset[AgentDepsT]: if self._state is not None: return self - resolved_scope_id = resolve_scope_id(ctx, self.scope_id, self.settings.scope_id) state = _RunState( - scope_id=resolved_scope_id, + run_context=ctx, run_id=ctx.run_id or f"local-{uuid4().hex}", conversation_id=ctx.conversation_id, ) return PowerContextToolset( settings=self.settings, id=self.id or "powercontext", - scope_id=resolved_scope_id, + scope_id=self.scope_id, _state=state, _auth_reporter=self._auth_reporter, ) @@ -140,13 +145,27 @@ async def for_run(self, ctx: RunContext[AgentDepsT]) -> PowerContextToolset[Agen @override async def __aenter__(self) -> PowerContextToolset[AgentDepsT]: state = self._require_state() + if state.client is not None: + return self token = self.settings.token.get_secret_value() if self.settings.token is not None else None client = PowerContextClient( self.settings.base_url, token=token, timeout=self.settings.timeout, ) - state.client = await client.__aenter__() + await client.__aenter__() + try: + if state.scope_id is None: + state.scope_id = await resolve_scope_binding( + client, + state.run_context, + self.scope_id, + self.settings.scope_id, + ) + except BaseException as exc: + await client.__aexit__(type(exc), exc, exc.__traceback__) + raise + state.client = client return self @override @@ -167,7 +186,7 @@ async def powercontext_search( """Search durable memory, preserving the complete public response.""" request = SearchMemoryRequest( - scope_id=self._require_state().scope_id, + scope_id=self._require_state().require_scope_id(), query=query, limit=limit, mode=MemorySearchMode(mode), @@ -184,7 +203,7 @@ async def powercontext_remember( """Remember durable information, preserving status, citation, and revision fields.""" request = RememberMemoryRequest( - scope_id=self._require_state().scope_id, + scope_id=self._require_state().require_scope_id(), text=text, kind=kind, reason=reason, @@ -196,7 +215,7 @@ async def powercontext_context(self, query: Query) -> dict[str, Any]: """Prepare bounded context, preserving the complete public response.""" request = PrepareContextRequest( - scope_id=self._require_state().scope_id, + scope_id=self._require_state().require_scope_id(), query=query, max_bytes=self.settings.max_bytes, ) diff --git a/integrations/workbuddy/README.md b/integrations/workbuddy/README.md index 1a3d32e63..0a6cfc2bb 100644 --- a/integrations/workbuddy/README.md +++ b/integrations/workbuddy/README.md @@ -72,8 +72,8 @@ cp "$PLUGIN"/hooks/workbuddy_powercontext_hook.py \ "$PLUGIN"/hooks/workbuddy_settings.py \ "$PLUGIN"/hooks/prepared_context.py \ "$WORKBUDDY_HOOKS_DIR"/ -cp "$PLUGIN/scripts/project_scope.py" \ - "$WORKBUDDY_HOOKS_DIR/powercontext_project_scope.py" +cp "$PLUGIN/scripts/workspace_scope.py" \ + "$WORKBUDDY_HOOKS_DIR/powercontext_scope_binding.py" ``` The resulting layout is: @@ -83,7 +83,7 @@ The resulting layout is: workbuddy_powercontext_hook.py workbuddy_settings.py prepared_context.py - powercontext_project_scope.py + powercontext_scope_binding.py ``` #### 2. Register the hook @@ -150,8 +150,8 @@ EOF Then open `~/.workbuddy/skills/project-context/SKILL.md`. Replace `${POWERCONTEXT_PYTHON}` with a shell-safe Python executable argument and -`${POWERCONTEXT_PROJECT_SCOPE_SCRIPT}` with a shell-safe complete path to -`/powercontext_project_scope.py`. +`${POWERCONTEXT_SCOPE_BINDING_SCRIPT}` with a shell-safe complete path to +`/powercontext_scope_binding.py`. #### 5. Start the Server, restart WorkBuddy, and verify @@ -183,7 +183,7 @@ override the defaults; restart WorkBuddy after changing them. | --- | --- | | `POWERCONTEXT_WORKBUDDY_SERVER_URL` | PowerContext server URL (default `http://127.0.0.1:8000`). | | `POWERCONTEXT_WORKBUDDY_AUTHORIZATION` | Complete authorization header, e.g. `Bearer ` | -| `POWERCONTEXT_WORKBUDDY_SCOPE_ID` | Explicit scope or scope template override | +| `POWERCONTEXT_WORKBUDDY_SCOPE_ID` | Explicit server-owned Scope ID | | `POWERCONTEXT_WORKBUDDY_CAPTURE_PROMPTS` | Capture user prompts as Sources (default `true`) | | `POWERCONTEXT_WORKBUDDY_FLUSH_ON_CAPTURE` | Flush until the captured Source is processed (testing only, default `false`) | | `POWERCONTEXT_WORKBUDDY_REQUEST_TIMEOUT_SECONDS` | Per-request HTTP timeout (default `1.0`) | diff --git a/integrations/workbuddy/plugins/powercontext/README.md b/integrations/workbuddy/plugins/powercontext/README.md index 503ebaadd..e19de783f 100644 --- a/integrations/workbuddy/plugins/powercontext/README.md +++ b/integrations/workbuddy/plugins/powercontext/README.md @@ -16,10 +16,9 @@ Automatic recall and prompt capture run on `UserPromptSubmit`. The hook never reads the WorkBuddy transcript or captures WorkBuddy's final response. Prompt Sources are evidence and are never marked as `task-outcome` by the hook. -Project scope is resolved from an explicit override, a Git-private Workstream -binding, the normalized Git origin, or a hash of the resolved local project -directory, in that order. The rules match the Codex and Claude Code plugins so -all three agents can share the same project Memory. +Scope is resolved by the Server from an explicit override, durable session and +workspace bindings, or the Server default, in that order. The plugin hashes a +workspace path only as an external binding key; it never derives a Scope ID. The plugin defaults to `http://127.0.0.1:8000`. Its Hook and MCP transport share `POWERCONTEXT_WORKBUDDY_AUTHORIZATION` when optional bearer authentication is diff --git a/integrations/workbuddy/plugins/powercontext/hooks/powercontext_project_scope.py b/integrations/workbuddy/plugins/powercontext/hooks/powercontext_scope_binding.py similarity index 81% rename from integrations/workbuddy/plugins/powercontext/hooks/powercontext_project_scope.py rename to integrations/workbuddy/plugins/powercontext/hooks/powercontext_scope_binding.py index d0bebeba3..933b06ee1 100644 --- a/integrations/workbuddy/plugins/powercontext/hooks/powercontext_project_scope.py +++ b/integrations/workbuddy/plugins/powercontext/hooks/powercontext_scope_binding.py @@ -12,8 +12,8 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Expose the repository scope resolver under its installed WorkBuddy module name.""" +"""Expose the Server Scope resolver under its installed WorkBuddy module name.""" -from scripts.project_scope import resolve_scope_id +from scripts.workspace_scope import resolve_scope_id __all__ = ["resolve_scope_id"] diff --git a/integrations/workbuddy/plugins/powercontext/hooks/workbuddy_powercontext_hook.py b/integrations/workbuddy/plugins/powercontext/hooks/workbuddy_powercontext_hook.py index 91cbf91bc..a0137c309 100644 --- a/integrations/workbuddy/plugins/powercontext/hooks/workbuddy_powercontext_hook.py +++ b/integrations/workbuddy/plugins/powercontext/hooks/workbuddy_powercontext_hook.py @@ -48,10 +48,10 @@ def override(method: _MethodT, /) -> _MethodT: import prepared_context as _prepared_context # noqa: E402 from workbuddy_settings import WorkBuddyPluginSettings # noqa: E402 -if (_HOOKS_ROOT / "powercontext_project_scope.py").is_file(): - from powercontext_project_scope import resolve_scope_id +if (_HOOKS_ROOT / "powercontext_scope_binding.py").is_file(): + from powercontext_scope_binding import resolve_scope_id else: - from scripts.project_scope import resolve_scope_id + from scripts.workspace_scope import resolve_scope_id _MAX_CONTEXT_BYTES = _prepared_context.MAX_CONTEXT_BYTES _InvalidResponseError = _prepared_context.InvalidPreparedContextResponse @@ -118,12 +118,17 @@ def main(settings: WorkBuddyPluginSettings | None = None) -> int: cwd = payload.get("cwd") context = None if prompt is not None and prompt.strip() and isinstance(cwd, str): + http_deadline = monotonic() + settings.http_budget_seconds try: - scope_id = resolve_scope_id(cwd, configured_scope_id=settings.scope_id) + scope_id = resolve_scope_id( + cwd, + session_id=_payload_identifier(payload, "session_id"), + settings=settings, + deadline=http_deadline, + ) except Exception: scope_id = None if scope_id: - http_deadline = monotonic() + settings.http_budget_seconds with suppress(Exception): context = _recall_context( prompt, diff --git a/integrations/workbuddy/plugins/powercontext/scripts/project_scope.py b/integrations/workbuddy/plugins/powercontext/scripts/project_scope.py deleted file mode 100644 index b63ba7fae..000000000 --- a/integrations/workbuddy/plugins/powercontext/scripts/project_scope.py +++ /dev/null @@ -1,231 +0,0 @@ -#!/usr/bin/env python3 -# Copyright (c) 2026 OceanBase. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -# Adapted for WorkBuddy from the PowerContext Claude Code plugin -# (integrations/claude-code/plugins/powercontext/scripts/project_scope.py). - -"""Derive a stable PowerContext scope for one project directory.""" - -from __future__ import annotations - -import argparse -import hashlib -import json -import os -import re -import subprocess -import sys -from collections.abc import Sequence -from contextlib import suppress -from pathlib import Path -from shutil import which -from urllib.parse import urlsplit - -_SCRIPTS_ROOT = Path(__file__).resolve().parent -_PLUGIN_ROOT = _SCRIPTS_ROOT.parent -# Support both the repository layout (workbuddy_settings.py in hooks/) and the -# installed WorkBuddy layout (workbuddy_settings.py beside scripts/). -sys.path.insert(0, str(_PLUGIN_ROOT / "hooks")) -sys.path.insert(0, str(_PLUGIN_ROOT)) - -from workbuddy_settings import WorkBuddyPluginSettings # noqa: E402 - -_MAX_SCOPE_LENGTH = 256 -_SCP_REMOTE = re.compile(r"^(?:[^@/\s]+@)?(?P[^:/\s]+):(?P.+)$") -_WORKSPACE_STATE_SCHEMA = "powercontext.codex-workspace.v1" -_WORKSPACE_STATE_DIRECTORY = "powercontext" -_WORKSPACE_STATE_FILE = "codex-workspace.json" - - -def resolve_scope_id(cwd: str, *, configured_scope_id: str | None = None) -> str: - """Return the configured, workspace-bound, or derived scope for one checkout.""" - - if configured_scope_id: - return _bounded_explicit(configured_scope_id) - bound_scope_id = read_bound_scope_id(cwd) - if bound_scope_id is not None: - return bound_scope_id - return derive_scope_id(cwd) - - -def derive_scope_id(cwd: str, *, configured_scope_id: str | None = None) -> str: - """Return an explicit, remote-derived, or path-derived project scope.""" - - if configured_scope_id: - return _bounded_explicit(configured_scope_id) - root_value = _git_value(cwd, "rev-parse", "--show-toplevel") - project_root = Path(root_value or cwd).resolve(strict=False) - remote = _git_value(str(project_root), "config", "--get", "remote.origin.url") - normalized_remote = normalize_git_remote(remote) if remote else None - if normalized_remote: - return _bounded("git", normalized_remote) - return f"local:{hashlib.sha256(os.fsencode(project_root)).hexdigest()}" - - -def bind_workstream_scope(cwd: str, scope_id: str, /) -> str: - """Persist one shared Workstream scope in Git-private state.""" - - normalized_scope_id = _bounded_explicit(scope_id.strip()) - if not normalized_scope_id: - raise ValueError("Workstream scope must be non-empty") # noqa: TRY003 - state_path = _workspace_state_path(cwd) - if state_path is None: - raise ValueError("Workstream scope binding requires a Git workspace") # noqa: TRY003 - _write_workspace_state(state_path, normalized_scope_id) - return normalized_scope_id - - -def read_bound_scope_id(cwd: str, /) -> str | None: - """Read the shared Codex/Claude Workstream binding from Git-private state.""" - - state_path = _workspace_state_path(cwd) - if state_path is None: - return None - try: - payload = json.loads(state_path.read_text(encoding="utf-8")) - except (OSError, UnicodeError, json.JSONDecodeError): - return None - if not isinstance(payload, dict) or payload.get("schema") != _WORKSPACE_STATE_SCHEMA: - return None - scope_id = payload.get("scope_id") - if ( - not isinstance(scope_id, str) - or not scope_id - or scope_id != scope_id.strip() - or len(scope_id) > _MAX_SCOPE_LENGTH - ): - return None - return scope_id - - -def clear_workstream_scope(cwd: str, /) -> bool: - """Remove only the Git-private shared Workstream binding file.""" - - state_path = _workspace_state_path(cwd) - if state_path is None: - return False - try: - state_path.unlink() - except FileNotFoundError: - return False - return True - - -def normalize_git_remote(remote: str) -> str | None: - """Normalize common network remotes without retaining credentials.""" - - value = remote.strip() - if not value: - return None - scp_match = _SCP_REMOTE.fullmatch(value) - if scp_match and "://" not in value: - host = scp_match.group("host").lower() - path = _normalize_path(scp_match.group("path")) - return f"{host}/{path}" if path else None - parsed = urlsplit(value) - if parsed.scheme not in {"http", "https", "ssh", "git"} or parsed.hostname is None: - return None - host = parsed.hostname.lower() - if parsed.port is not None: - host = f"{host}:{parsed.port}" - path = _normalize_path(parsed.path) - return f"{host}/{path}" if path else None - - -def _normalize_path(path: str) -> str: - normalized = "/".join(part for part in path.replace("\\", "/").split("/") if part) - if normalized.endswith(".git"): - normalized = normalized[:-4] - return normalized.rstrip("/") - - -def _bounded(prefix: str, value: str) -> str: - candidate = f"{prefix}:{value}" - if len(candidate) <= _MAX_SCOPE_LENGTH: - return candidate - return f"{prefix}:sha256:{hashlib.sha256(value.encode()).hexdigest()}" - - -def _bounded_explicit(value: str) -> str: - if len(value) <= _MAX_SCOPE_LENGTH: - return value - return f"sha256:{hashlib.sha256(value.encode()).hexdigest()}" - - -def _workspace_state_path(cwd: str, /) -> Path | None: - git_directory = _git_value(cwd, "rev-parse", "--absolute-git-dir") - if git_directory is None: - return None - return Path(git_directory) / _WORKSPACE_STATE_DIRECTORY / _WORKSPACE_STATE_FILE - - -def _write_workspace_state(state_path: Path, scope_id: str, /) -> None: - state_path.parent.mkdir(mode=0o700, parents=True, exist_ok=True) - temporary_path = state_path.with_name(f".{state_path.name}.{os.getpid()}.tmp") - encoded = ( - json.dumps({"schema": _WORKSPACE_STATE_SCHEMA, "scope_id": scope_id}, separators=(",", ":")) + "\n" - ).encode() - descriptor: int | None = None - try: - descriptor = os.open(temporary_path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600) - os.write(descriptor, encoded) - os.fsync(descriptor) - os.close(descriptor) - descriptor = None - os.replace(temporary_path, state_path) - finally: - if descriptor is not None: - os.close(descriptor) - with suppress(FileNotFoundError): - temporary_path.unlink() - - -def _git_value(cwd: str, *arguments: str) -> str | None: - executable = which("git") - if executable is None: - return None - try: - completed = subprocess.run( # noqa: S603 - git executable and arguments are integration-owned. - [executable, *arguments], - cwd=cwd, - check=True, - capture_output=True, - text=True, - timeout=2, - ) - except (OSError, subprocess.SubprocessError): - return None - return completed.stdout.strip() or None - - -def main(argv: Sequence[str] | None = None) -> int: - parser = argparse.ArgumentParser() - parser.add_argument("--cwd", default=os.getcwd()) - action = parser.add_mutually_exclusive_group() - action.add_argument("--bind-workstream", metavar="SCOPE_ID") - action.add_argument("--clear-workstream", action="store_true") - arguments = parser.parse_args(argv) - if arguments.bind_workstream is not None: - print(bind_workstream_scope(arguments.cwd, arguments.bind_workstream)) - return 0 - if arguments.clear_workstream: - clear_workstream_scope(arguments.cwd) - settings = WorkBuddyPluginSettings.from_environment() - print(resolve_scope_id(arguments.cwd, configured_scope_id=settings.scope_id)) - return 0 - - -if __name__ == "__main__": - raise SystemExit(main()) diff --git a/integrations/workbuddy/plugins/powercontext/scripts/workspace_scope.py b/integrations/workbuddy/plugins/powercontext/scripts/workspace_scope.py new file mode 100644 index 000000000..70532a45f --- /dev/null +++ b/integrations/workbuddy/plugins/powercontext/scripts/workspace_scope.py @@ -0,0 +1,269 @@ +#!/usr/bin/env python3 +# Copyright (c) 2026 OceanBase. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +"""Resolve WorkBuddy identities through the PowerContext Scope service.""" + +from __future__ import annotations + +import argparse +import json +import os +import subprocess +import sys +from collections.abc import Mapping, Sequence +from hashlib import sha256 +from pathlib import Path +from shutil import which +from time import monotonic +from typing import Any, Protocol +from urllib.error import HTTPError +from urllib.request import HTTPRedirectHandler, Request, build_opener + +from typing_extensions import override + +_SCRIPTS_ROOT = Path(__file__).resolve().parent +_PLUGIN_ROOT = _SCRIPTS_ROOT.parent +sys.path.insert(0, str(_PLUGIN_ROOT / "hooks")) +sys.path.insert(0, str(_PLUGIN_ROOT)) + +from workbuddy_settings import WorkBuddyPluginSettings # noqa: E402 + +_MAX_RESPONSE_BYTES = 1_048_576 +_READ_CHUNK_BYTES = 65_536 +_REQUEST_HEADERS = { + "Accept": "application/json", + "Content-Type": "application/json", + "User-Agent": "powercontext-workbuddy-plugin/0.1.0", +} + + +class ScopeBindingError(RuntimeError): + """Raised when WorkBuddy cannot establish one current Scope.""" + + +class ScopeBindingSettings(Protocol): + """Settings required by the dependency-free binding client.""" + + server_url: str + authorization: str | None + scope_id: str | None + request_timeout_seconds: float + + +class _Response(Protocol): + status: int + + def __enter__(self) -> _Response: ... + + def __exit__(self, *args: object) -> object: ... + + def read(self, amount: int = -1) -> bytes: ... + + +class _RejectRedirects(HTTPRedirectHandler): + @override + def redirect_request( + self, + req: Request, + fp: object, + code: int, + msg: str, + headers: object, + newurl: str, + ) -> Request | None: + return None + + +_URL_OPENER = build_opener(_RejectRedirects) + + +def resolve_scope_id( + cwd: str, + *, + session_id: str | None, + settings: ScopeBindingSettings, + deadline: float, +) -> str: + """Resolve explicit, session, workspace, then server-default binding.""" + + response = _request_json( + "/v1/scope-bindings/resolve", + { + "explicit_scope_id": settings.scope_id, + "binding_keys": binding_keys(cwd, session_id=session_id), + }, + settings=settings, + deadline=deadline, + ) + scope_id = response.get("scope_id") + if not isinstance(scope_id, str) or not scope_id.strip() or scope_id != scope_id.strip(): + raise ScopeBindingError + return scope_id + + +def bind_scope( + cwd: str, + scope_id: str, + /, + *, + settings: ScopeBindingSettings, + deadline: float, +) -> str: + """Persist the workspace identity to one server-owned Scope.""" + + response = _request_json( + "/v1/scope-bindings", + {"key": workspace_binding_key(cwd), "scope_id": scope_id}, + settings=settings, + deadline=deadline, + method="PUT", + ) + resolved = response.get("scope_id") + if not isinstance(resolved, str) or resolved != scope_id: + raise ScopeBindingError + return resolved + + +def clear_scope_binding( + cwd: str, + /, + *, + settings: ScopeBindingSettings, + deadline: float, +) -> bool: + """Remove the durable workspace binding from the Scope service.""" + + response = _request_json( + "/v1/scope-bindings/clear", + {"key": workspace_binding_key(cwd)}, + settings=settings, + deadline=deadline, + ) + cleared = response.get("cleared") + if not isinstance(cleared, bool): + raise ScopeBindingError + return cleared + + +def binding_keys(cwd: str, *, session_id: str | None) -> list[dict[str, str]]: + keys: list[dict[str, str]] = [] + if session_id is not None: + keys.append(session_binding_key(session_id)) + keys.append(workspace_binding_key(cwd)) + return keys + + +def session_binding_key(session_id: str) -> dict[str, str]: + value = session_id.strip() + if not value or len(value) > 256: + raise ScopeBindingError + return {"integration": "workbuddy", "kind": "session", "external_id": value} + + +def workspace_binding_key(cwd: str) -> dict[str, str]: + root_value = _git_value(cwd, "rev-parse", "--show-toplevel") + root = Path(root_value or cwd).resolve(strict=False) + return { + "integration": "workbuddy", + "kind": "workspace", + "external_id": sha256(os.fsencode(root)).hexdigest(), + } + + +def _request_json( + path: str, + payload: Mapping[str, object], + *, + settings: ScopeBindingSettings, + deadline: float, + method: str = "POST", +) -> Mapping[str, object]: + remaining = deadline - monotonic() + if remaining <= 0: + raise ScopeBindingError + headers = dict(_REQUEST_HEADERS) + if settings.authorization is not None: + headers["Authorization"] = settings.authorization + request = Request( # noqa: S310 - settings validates the configured transport. + f"{settings.server_url}{path}", + data=json.dumps(payload, separators=(",", ":")).encode(), + headers=headers, + method=method, + ) + try: + with _URL_OPENER.open(request, timeout=min(settings.request_timeout_seconds, remaining)) as response: + if response.status < 200 or response.status >= 300: + raise ScopeBindingError + raw = _read_bounded(response) + except (HTTPError, OSError, TimeoutError) as error: + raise ScopeBindingError from error + try: + value: Any = json.loads(raw) + except (UnicodeDecodeError, json.JSONDecodeError) as error: + raise ScopeBindingError from error + if not isinstance(value, dict): + raise ScopeBindingError + return value + + +def _read_bounded(response: _Response) -> bytes: + chunks: list[bytes] = [] + size = 0 + while chunk := response.read(_READ_CHUNK_BYTES): + size += len(chunk) + if size > _MAX_RESPONSE_BYTES: + raise ScopeBindingError + chunks.append(chunk) + return b"".join(chunks) + + +def _git_value(cwd: str, *arguments: str) -> str | None: + executable = which("git") + if executable is None: + return None + try: + completed = subprocess.run( # noqa: S603 - git executable and arguments are integration-owned. + [executable, *arguments], + cwd=cwd, + check=True, + capture_output=True, + text=True, + timeout=2, + ) + except (OSError, subprocess.SubprocessError): + return None + return completed.stdout.strip() or None + + +def main(argv: Sequence[str] | None = None) -> int: + parser = argparse.ArgumentParser() + parser.add_argument("--cwd", default=os.getcwd()) + action = parser.add_mutually_exclusive_group() + action.add_argument("--bind-scope", metavar="SCOPE_ID") + action.add_argument("--clear-scope", action="store_true") + arguments = parser.parse_args(argv) + settings = WorkBuddyPluginSettings.from_environment() + deadline = monotonic() + settings.http_budget_seconds + if arguments.bind_scope is not None: + print(bind_scope(arguments.cwd, arguments.bind_scope, settings=settings, deadline=deadline)) + return 0 + if arguments.clear_scope: + clear_scope_binding(arguments.cwd, settings=settings, deadline=deadline) + print(resolve_scope_id(arguments.cwd, session_id=None, settings=settings, deadline=deadline)) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/integrations/workbuddy/plugins/powercontext/skills/project-context/SKILL.md b/integrations/workbuddy/plugins/powercontext/skills/project-context/SKILL.md index ee12870fe..e24b315a6 100644 --- a/integrations/workbuddy/plugins/powercontext/skills/project-context/SKILL.md +++ b/integrations/workbuddy/plugins/powercontext/skills/project-context/SKILL.md @@ -5,9 +5,9 @@ description: Create and commit a current-work Handoff when the user says "交接 # Project Context @@ -25,36 +25,29 @@ to duplicate the current prompt. Ordinary prompt Sources are not task outcomes. Before the first memory tool call, run: ```bash -${POWERCONTEXT_PYTHON} ${POWERCONTEXT_PROJECT_SCOPE_SCRIPT} --cwd "$PWD" +${POWERCONTEXT_PYTHON} ${POWERCONTEXT_SCOPE_BINDING_SCRIPT} --cwd "$PWD" ``` Reuse that exact `scope_id` for the task. -The resolver first honors an explicit plugin scope, then the same Git-private -Workstream binding used by Codex, and finally the normalized remote or project -path. When the user explicitly asks to bind the current checkout to a known -Handoff Report Workstream, run: +The Server resolves an explicit Scope first, then durable session and workspace +bindings, and finally its default Scope. When the user explicitly asks to bind +the current checkout to a known Scope, run: ```bash -${POWERCONTEXT_PYTHON} ${POWERCONTEXT_PROJECT_SCOPE_SCRIPT} \ - --cwd "$PWD" --bind-workstream "WORKSTREAM_SCOPE_ID" +${POWERCONTEXT_PYTHON} ${POWERCONTEXT_SCOPE_BINDING_SCRIPT} \ + --cwd "$PWD" --bind-scope "SCOPE_ID" ``` -Then run the normal resolver command again and verify the same scope. The -binding is stored below the checkout's Git directory and is not committed. -Never infer one Workstream when multiple candidates remain consequential. - -Before a durable one-turn Handoff or a `latest` Continue without an exact -Workstream, call `select_handoff_workstream` when that MCP tool is available. -Clients with MCP elicitation can present a native picker; otherwise the tool -returns structured choices. On `selected`, bind the returned `scope_id` with -`--bind-workstream`, run the normal resolver again, and require the resolved -scope to match before any Handoff write. On `needs_selection`, present the -returned choices and call the tool again with the user's exact `project_id` and -`work_id`; never choose a fallback candidate silently. On `cancelled` or -`declined`, stop the Handoff flow. If the tool is unavailable or returns -`empty`, preserve the existing resolver behavior. The picker is read-only and -selecting work does not itself prepare or commit a Handoff. +Then run the normal resolver command again and verify the same Scope. The +binding is stored by PowerContext; the plugin never derives a Scope ID from a +Git remote or directory. Never infer a Scope when multiple candidates remain +consequential. + +Before a durable one-turn Handoff or a `latest` Continue, resolve the intended +Scope explicitly. If the current binding is not the intended boundary, ask the +user or host for the exact Scope ID, bind it, and verify the resolver result +before any Handoff write. Never infer a Scope from a report view. ## Read @@ -75,8 +68,7 @@ Handoff, a design discussion, or a preview request does not authorize a write. When the one-turn flow applies: -1. Select the Workstream when the picker is available, then resolve and verify - the exact scope using the commands above. +1. Resolve and verify the exact Scope using the commands above. 2. Inspect the current conversation and repository before writing. Ground the objective, branch and worktree state, changed files, checks, blockers, omissions, and next executable action without reading or including secrets. From 14278d262bde3c8803cfe033e0d400d9382eec85 Mon Sep 17 00:00:00 2001 From: Chojan Shang Date: Wed, 2 Sep 2026 16:13:16 +0800 Subject: [PATCH 06/17] test(scope): verify selection and plugin contracts --- .../builtin/artifacts/handoff/test_service.py | 28 + .../builtin/runtime/test_prepared_context.py | 39 +- tests/builtin/runtime/test_statistics.py | 49 ++ tests/builtin/test_scope_application.py | 93 +++- tests/claude_code_plugin/conftest.py | 4 +- tests/claude_code_plugin/test_contract.py | 67 ++- tests/claude_code_plugin/test_hook.py | 14 +- tests/codex_plugin/conftest.py | 12 +- tests/codex_plugin/test_contract.py | 111 ++-- tests/codex_plugin/test_recall.py | 12 +- tests/codex_plugin/test_scope_binding.py | 223 ++++++++ tests/e2e/test_builtin_runtime.py | 107 +++- tests/e2e/test_candidate_review.py | 39 +- tests/e2e/test_claude_code_service_chain.py | 41 +- tests/e2e/test_codex_service_chain.py | 229 +++++++- tests/e2e/test_dsh_http_chain.py | 10 +- tests/e2e/test_external_skill_registry.py | 16 +- tests/e2e/test_langgraph_chain.py | 25 +- tests/e2e/test_mcp_transport.py | 61 ++- tests/e2e/test_observability.py | 65 ++- tests/e2e/test_pydantic_ai_chain.py | 24 +- tests/e2e/test_reviewed_generation.py | 14 +- tests/e2e/test_runtime_server.py | 211 ++++++-- .../test_scheduled_experience_incubation.py | 2 +- tests/e2e/test_statistics_flow.py | 30 +- tests/e2e/test_workbuddy_service_chain.py | 19 +- tests/integrations/test_hermes_provider.py | 115 +++-- tests/langchain_middleware/test_middleware.py | 40 +- tests/langchain_middleware/test_scope.py | 46 -- tests/langgraph_adapter/test_recall.py | 63 ++- tests/langgraph_adapter/test_scope.py | 106 ++-- tests/langgraph_adapter/test_tools.py | 20 +- tests/pydantic_ai_adapter/fakes.py | 19 + .../test_settings_scope.py | 74 +-- tests/pydantic_ai_adapter/test_toolset.py | 1 + tests/test_api_contract.py | 37 +- tests/test_cli.py | 98 ++-- tests/test_cli_workbuddy.py | 14 +- tests/test_client.py | 57 +- tests/test_config_cli.py | 16 +- tests/test_dashboard.py | 156 ++++-- tests/test_handoff_report.py | 152 ++++++ tests/test_handoff_report_canonical.py | 86 --- tests/test_handoff_report_catalog.py | 248 --------- tests/test_handoff_report_http.py | 289 ----------- tests/test_handoff_report_models.py | 199 ------- tests/test_handoff_report_repository.py | 280 ---------- tests/test_handoff_report_selection.py | 208 -------- tests/test_handoff_report_service.py | 488 ------------------ tests/test_handoff_report_workspace.py | 173 ------- tests/test_js_operations.py | 10 +- tests/test_mcp.py | 246 +-------- tests/test_openclaw_cli.py | 14 +- tests/test_openclaw_configure_script.py | 6 +- tests/test_scope_api.py | 200 +++++++ tests/test_server.py | 30 +- tests/test_server_metrics.py | 27 +- tests/test_server_tracing.py | 3 +- tests/test_setup_select.py | 6 +- 59 files changed, 2158 insertions(+), 2914 deletions(-) create mode 100644 tests/codex_plugin/test_scope_binding.py delete mode 100644 tests/langchain_middleware/test_scope.py create mode 100644 tests/test_handoff_report.py delete mode 100644 tests/test_handoff_report_canonical.py delete mode 100644 tests/test_handoff_report_catalog.py delete mode 100644 tests/test_handoff_report_http.py delete mode 100644 tests/test_handoff_report_models.py delete mode 100644 tests/test_handoff_report_repository.py delete mode 100644 tests/test_handoff_report_selection.py delete mode 100644 tests/test_handoff_report_service.py delete mode 100644 tests/test_handoff_report_workspace.py create mode 100644 tests/test_scope_api.py diff --git a/tests/builtin/artifacts/handoff/test_service.py b/tests/builtin/artifacts/handoff/test_service.py index 0c5cd1477..3ebbb5863 100644 --- a/tests/builtin/artifacts/handoff/test_service.py +++ b/tests/builtin/artifacts/handoff/test_service.py @@ -77,6 +77,7 @@ async def generate(self, request, /): class _HandoffBackend(HandoffBackend): def __init__(self) -> None: self.history: list[Handoff] = [] + self.published: dict[tuple[str, int], Handoff] = {} async def create(self, artifact_id: str, draft: HandoffArtifactDraft, /) -> Handoff: if self.history: @@ -89,9 +90,14 @@ async def revise(self, base: Handoff, draft: HandoffArtifactDraft, /) -> Handoff return self._append(base.artifact_id, draft) async def get(self, reference: ArtifactRef, /) -> Handoff: + if reference.artifact_id != "handoff": + return self.published[(reference.artifact_id, reference.revision)] return self.history[reference.revision - 1] async def latest(self, artifact_id: str, /) -> Handoff | None: + published = [handoff for (current_id, _), handoff in self.published.items() if current_id == artifact_id] + if published: + return max(published, key=lambda handoff: handoff.revision) if not self.history: return None assert self.history[-1].artifact_id == artifact_id @@ -373,6 +379,28 @@ async def scenario() -> None: asyncio.run(scenario()) +def test_exact_published_revision_is_continuation_input_without_becoming_the_local_head() -> None: + async def scenario() -> None: + service, backend, _ = _service() + published = Handoff( + artifact_id="pub_01kcontinuation", + revision=1, + content=_draft("Published state.").as_content(), + ) + backend.published[(published.artifact_id, published.revision)] = published + + continued = await service.continue_from(published.as_ref()) + + assert continued.status == "resolved" + assert continued.selection == "exact" + assert continued.selected_revision == published.as_ref() + assert continued.current_revision == published.as_ref() + assert continued.content == published.content + assert await service.latest() is None + + asyncio.run(scenario()) + + def test_cross_scope_prepared_handoff_is_rejected() -> None: async def scenario() -> None: service, _, _ = _service() diff --git a/tests/builtin/runtime/test_prepared_context.py b/tests/builtin/runtime/test_prepared_context.py index 44fad2374..25f242dd9 100644 --- a/tests/builtin/runtime/test_prepared_context.py +++ b/tests/builtin/runtime/test_prepared_context.py @@ -25,13 +25,20 @@ from powercontext.builtin.artifacts.memory import MemoryHit from powercontext.builtin.runtime import PrepareContextRequest from powercontext.builtin.runtime.errors import PreparedContextInvariantError -from powercontext.builtin.runtime.prepared_context import PreparedContextBuilder +from powercontext.builtin.runtime.prepared_context import ( + PreparedContextBuilder, + PreparedExperienceCandidates, + PreparedMemoryCandidates, +) MEMORY_REF = ArtifactRef(family="memory", artifact_id="memory", revision=3) -class _PreparedCitation(TypedDict): +class _PreparedCitation(TypedDict, total=False): entry_id: str + memory_ref: object + memory: object + artifact: object class _PreparedItem(TypedDict): @@ -173,6 +180,34 @@ def test_builder_prepares_experience_without_a_memory_head_and_keeps_v1_envelope assert item["content"].endswith("Lesson: Regenerate and inspect the client before contract tests.") +def test_builder_qualifies_only_cross_scope_citations() -> None: + builder = PreparedContextBuilder() + prepared = builder.build_scopes_result( + request=PrepareContextRequest(query="shared evidence"), + current_scope_id="current", + memory_candidates=( + PreparedMemoryCandidates(scope_id="current", memory_ref=MEMORY_REF, hits=(_hit("local", "Local"),)), + PreparedMemoryCandidates(scope_id="shared", memory_ref=MEMORY_REF, hits=(_hit("shared", "Shared"),)), + ), + experience_candidates=(PreparedExperienceCandidates(scope_id="shared", hits=(_experience_hit(),)),), + ).context + + local, experience, shared = _items(prepared.content) + assert local["citation"]["memory_ref"] == MEMORY_REF.model_dump(mode="json") + assert shared["citation"]["memory"] == { + "scope_id": "shared", + "artifact": MEMORY_REF.model_dump(mode="json"), + } + assert experience["citation"]["artifact"] == { + "scope_id": "shared", + "artifact": { + "family": "experience", + "artifact_id": "experience-1", + "revision": 1, + }, + } + + def test_builder_keeps_memory_primary_and_bounds_experience_share() -> None: experiences = tuple(_experience_hit(f"experience-{index}") for index in range(1, 5)) prepared = PreparedContextBuilder().build( diff --git a/tests/builtin/runtime/test_statistics.py b/tests/builtin/runtime/test_statistics.py index a75721225..00a65ecd5 100644 --- a/tests/builtin/runtime/test_statistics.py +++ b/tests/builtin/runtime/test_statistics.py @@ -30,6 +30,7 @@ StatisticsPeriod, open_builtin_runtime, ) +from powercontext.builtin.scope import ScopeDraft, ScopeSelection from powercontext.builtin.sources import ContentSource @@ -149,3 +150,51 @@ async def scenario() -> None: assert result.recall.totals.baseline_tokens == estimator.estimate("a") + estimator.estimate("b") == 2 asyncio.run(scenario()) + + +def test_statistics_uses_the_same_all_exact_and_subtree_selection() -> None: + async def scenario() -> None: + async with open_builtin_runtime(BuiltinConfig(database=SQLiteConfig())) as runtime: + assert runtime.scopes is not None + root = await runtime.scopes.create(ScopeDraft(title="Root", summary="Root result", idempotency_key="root")) + child = await runtime.scopes.create( + ScopeDraft( + title="Child", + summary="Child result", + parent_scope_id=root.scope_id, + idempotency_key="child", + ) + ) + other = await runtime.scopes.create( + ScopeDraft(title="Other", summary="Other result", idempotency_key="other") + ) + for scope_id in (root.scope_id, child.scope_id, other.scope_id): + await runtime.memory.for_scope(scope_id).remember( + RememberMemoryRequest(entries=(MemoryEntryInput(kind="fact", text=f"Fact for {scope_id}."),)) + ) + + all_statistics = await runtime.statistics.overview( + ScopeSelection(mode="all"), + period=StatisticsPeriod.TODAY, + ) + subtree = await runtime.statistics.overview( + ScopeSelection(mode="subtree", root_scope_id=root.scope_id), + period=StatisticsPeriod.TODAY, + ) + exact = await runtime.statistics.overview( + ScopeSelection(mode="exact", scope_ids=(child.scope_id,)), + period=StatisticsPeriod.TODAY, + ) + + assert set(all_statistics.scope_ids) >= {root.scope_id, child.scope_id, other.scope_id} + assert all_statistics.inventory.memory.entries.total == 3 + assert subtree.scope_ids == (root.scope_id, child.scope_id) + assert subtree.inventory.memory.entries.total == 2 + assert tuple(item.scope_id for item in subtree.by_scope) == (root.scope_id, child.scope_id) + assert [item.inventory.memory.entries.total for item in subtree.by_scope] == [1, 1] + assert exact.scope_ids == (child.scope_id,) + assert exact.inventory.memory.entries.total == 1 + assert exact.by_scope[0].scope_id == child.scope_id + assert exact.by_scope[0].inventory == exact.inventory + + asyncio.run(scenario()) diff --git a/tests/builtin/test_scope_application.py b/tests/builtin/test_scope_application.py index c6ccef741..19078cfaa 100644 --- a/tests/builtin/test_scope_application.py +++ b/tests/builtin/test_scope_application.py @@ -18,6 +18,7 @@ import re import pytest +from sqlalchemy.exc import IntegrityError from powercontext.builtin.persistence.sqlite import SQLiteConfig, SQLiteProfile from powercontext.builtin.persistence.tables import BUILTIN_TABLES, SOURCES_TABLE @@ -96,16 +97,104 @@ def test_concurrent_scope_creation_returns_one_scope(tmp_path) -> None: async def scenario() -> None: config = SQLiteConfig(url=f"sqlite+aiosqlite:///{tmp_path / 'runtime.db'}") async with SQLiteProfile.open(config, tables=BUILTIN_TABLES) as profile: - scopes = ScopeApplication(profile.database) + scopes = tuple(ScopeApplication(profile.database) for _ in range(8)) draft = ScopeDraft(title="Feature", summary="Concurrent creation", idempotency_key="concurrent") - created = await asyncio.gather(*(scopes.create(draft) for _ in range(8))) + created = await asyncio.gather(*(application.create(draft) for application in scopes)) assert len({scope.scope_id for scope in created}) == 1 asyncio.run(scenario()) +def test_concurrent_scope_creation_rejects_a_different_request(tmp_path) -> None: + async def scenario() -> None: + config = SQLiteConfig(url=f"sqlite+aiosqlite:///{tmp_path / 'runtime.db'}") + async with SQLiteProfile.open(config, tables=BUILTIN_TABLES) as profile: + left = ScopeApplication(profile.database) + right = ScopeApplication(profile.database) + + results = await asyncio.gather( + left.create(ScopeDraft(title="Feature", summary="Left", idempotency_key="concurrent")), + right.create(ScopeDraft(title="Feature", summary="Right", idempotency_key="concurrent")), + return_exceptions=True, + ) + + assert sum(isinstance(result, ScopeIdempotencyConflictError) for result in results) == 1 + assert sum(not isinstance(result, BaseException) for result in results) == 1 + + asyncio.run(scenario()) + + +def test_scope_creation_does_not_hide_an_unrelated_integrity_error() -> None: + async def scenario() -> None: + async with SQLiteProfile.open(SQLiteConfig(), tables=BUILTIN_TABLES) as profile: + scope_id = "scp_00000000000000000000000000" + left = ScopeApplication(profile.database, id_factory=lambda: scope_id) + right = ScopeApplication(profile.database, id_factory=lambda: scope_id) + await left.create(ScopeDraft(title="Left", summary="Left", idempotency_key="left")) + + with pytest.raises(IntegrityError): + await right.create(ScopeDraft(title="Right", summary="Right", idempotency_key="right")) + + asyncio.run(scenario()) + + +def test_concurrent_default_bootstrap_returns_one_scope(tmp_path) -> None: + async def scenario() -> None: + config = SQLiteConfig(url=f"sqlite+aiosqlite:///{tmp_path / 'runtime.db'}") + async with SQLiteProfile.open(config, tables=BUILTIN_TABLES) as profile: + scopes = tuple(ScopeApplication(profile.database) for _ in range(8)) + + defaults = await asyncio.gather(*(application.bootstrap_default() for application in scopes)) + + assert len({scope.scope_id for scope in defaults}) == 1 + assert await scopes[0].default_scope() == defaults[0] + + asyncio.run(scenario()) + + +def test_concurrent_default_and_binding_writes_remain_valid(tmp_path) -> None: + async def scenario() -> None: + config = SQLiteConfig(url=f"sqlite+aiosqlite:///{tmp_path / 'runtime.db'}") + async with SQLiteProfile.open(config, tables=BUILTIN_TABLES) as profile: + applications = tuple(ScopeApplication(profile.database) for _ in range(8)) + targets = [] + for index in range(len(applications)): + targets.append( + await applications[0].create( + ScopeDraft(title=f"Target {index}", summary="Target", idempotency_key=f"target-{index}") + ) + ) + target_scopes = tuple(targets) + key = ScopeBindingKey(integration="codex", kind="workspace", external_id="shared") + + defaults = await asyncio.gather( + *( + application.set_default(target.scope_id) + for application, target in zip(applications, target_scopes, strict=True) + ) + ) + bindings = await asyncio.gather( + *( + application.bind(key, target.scope_id) + for application, target in zip(applications, target_scopes, strict=True) + ) + ) + + target_ids = {target.scope_id for target in target_scopes} + persisted_default = await applications[0].default_scope() + persisted_binding = await applications[0].binding(key) + assert tuple(defaults) == target_scopes + assert {binding.scope_id for binding in bindings} == target_ids + assert persisted_default is not None + assert persisted_default.scope_id in target_ids + assert persisted_binding is not None + assert persisted_binding.scope_id in target_ids + + asyncio.run(scenario()) + + def test_parent_organizes_without_sharing_and_cannot_form_a_cycle() -> None: async def scenario() -> None: async with SQLiteProfile.open(SQLiteConfig(), tables=BUILTIN_TABLES) as profile: diff --git a/tests/claude_code_plugin/conftest.py b/tests/claude_code_plugin/conftest.py index 0d21db355..48f37d743 100644 --- a/tests/claude_code_plugin/conftest.py +++ b/tests/claude_code_plugin/conftest.py @@ -30,7 +30,7 @@ "hooks", "hooks.prepared_context", "scripts", - "scripts.project_scope", + "scripts.workspace_scope", ) @@ -82,7 +82,7 @@ def isolated_diagnostic_state(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) - def scope_module(plugin_imports: None) -> ModuleType: return _load_module( "powercontext_claude_code_scope", - PLUGIN_ROOT / "scripts" / "project_scope.py", + PLUGIN_ROOT / "scripts" / "workspace_scope.py", ) diff --git a/tests/claude_code_plugin/test_contract.py b/tests/claude_code_plugin/test_contract.py index 03c2d53b6..674e06dbe 100644 --- a/tests/claude_code_plugin/test_contract.py +++ b/tests/claude_code_plugin/test_contract.py @@ -21,8 +21,8 @@ import subprocess import sys from pathlib import Path -from shutil import which from types import ModuleType +from typing import Any, cast import pytest @@ -135,33 +135,42 @@ def test_header_helper_emits_configured_authorization_without_logging_it() -> No assert completed.stderr == "" -@pytest.mark.parametrize( - ("remote", "expected"), - [ - ("https://github.com/OceanBase/powercontext.git", "github.com/OceanBase/powercontext"), - ("ssh://git@github.com/OceanBase/powercontext.git", "github.com/OceanBase/powercontext"), - ("git@github.com:OceanBase/powercontext.git", "github.com/OceanBase/powercontext"), - ], -) -def test_scope_matches_codex_remote_normalization( +def test_scope_resolver_and_workspace_binding_use_the_server( scope_module: ModuleType, - remote: str, - expected: str, + monkeypatch: pytest.MonkeyPatch, + tmp_path: Path, ) -> None: - assert scope_module.normalize_git_remote(remote) == expected - + requests: list[tuple[str, dict[str, object], str]] = [] -def test_scope_override_wins(scope_module: ModuleType, tmp_path: Path) -> None: - assert scope_module.resolve_scope_id(str(tmp_path), configured_scope_id="project:explicit") == "project:explicit" + def request(path, payload, *, settings, deadline, method="POST"): + requests.append((path, payload, method)) + return {"scope_id": "scp_00000000000000000000000000"} + monkeypatch.setattr(scope_module, "_request_json", request) + settings = scope_module.ClaudeCodePluginSettings(scope_id="scp_00000000000000000000000000") -def test_scope_reads_the_shared_git_private_workstream_binding(scope_module: ModuleType, tmp_path: Path) -> None: - git = which("git") - assert git is not None - subprocess.run([git, "init", "-q", str(tmp_path)], check=True) + resolved = scope_module.resolve_scope_id( + str(tmp_path), + session_id="session-1", + settings=settings, + deadline=float("inf"), + ) + bound = scope_module.bind_scope( + str(tmp_path), + resolved, + settings=settings, + deadline=float("inf"), + ) - assert scope_module.bind_workstream_scope(str(tmp_path), "handoff-ui-review") == "handoff-ui-review" - assert scope_module.resolve_scope_id(str(tmp_path)) == "handoff-ui-review" + assert bound == resolved + assert requests[0][0] == "/v1/scope-bindings/resolve" + assert requests[0][1]["explicit_scope_id"] == resolved + binding_keys = cast(list[dict[str, Any]], requests[0][1]["binding_keys"]) + assert [key["kind"] for key in binding_keys] == ["session", "workspace"] + assert binding_keys[0]["external_id"] == "session-1" + assert binding_keys[1]["external_id"] != str(tmp_path) + assert requests[1][0] == "/v1/scope-bindings" + assert requests[1][2] == "PUT" @pytest.mark.parametrize( @@ -189,20 +198,6 @@ def test_environment_override_controls_prompt_capture( assert settings_module.ClaudeCodePluginSettings.from_environment().capture_prompts is False -def test_project_context_skill_preserves_explicit_memory_and_handoff_boundaries() -> None: - content = (PLUGIN_ROOT / "skills" / "project-context" / "SKILL.md").read_text() - - assert "Do not call `remember_memory` merely" in content - assert "Ordinary prompt Sources are not task outcomes" in content - assert "`select_handoff_workstream`" in content - assert "structured choices" in content - assert "`handoff_current_work`" in content - assert "returned `handoff` member unchanged" in content - assert "`continue_handoff`" in content - assert "`acknowledge_handoff`" in content - assert "`record_task_outcome`" in content - - def test_claude_integration_does_not_embed_machine_specific_windows_paths() -> None: roots = ( REPOSITORY_ROOT / ".claude-plugin", diff --git a/tests/claude_code_plugin/test_hook.py b/tests/claude_code_plugin/test_hook.py index c55295be2..0b08a5da4 100644 --- a/tests/claude_code_plugin/test_hook.py +++ b/tests/claude_code_plugin/test_hook.py @@ -84,7 +84,7 @@ def test_user_prompt_submit_injects_prepared_context_and_captures_prompt( monkeypatch.setattr( hook_module, "resolve_scope_id", - lambda _cwd, *, configured_scope_id: "git:github.com/oceanbase/powercontext", + lambda _cwd, **_kwargs: "git:github.com/oceanbase/powercontext", ) captured: list[tuple[str, str]] = [] monkeypatch.setattr( @@ -125,7 +125,7 @@ def test_user_prompt_submit_reads_utf8_stdin_on_windows_encodings( monkeypatch.setattr( hook_module, "resolve_scope_id", - lambda _cwd, *, configured_scope_id: "git:github.com/oceanbase/powercontext", + lambda _cwd, **_kwargs: "git:github.com/oceanbase/powercontext", ) monkeypatch.setattr( hook_module, @@ -163,7 +163,7 @@ def test_user_prompt_compatibility_fallback_is_supported( monkeypatch.setattr( hook_module, "resolve_scope_id", - lambda _cwd, *, configured_scope_id: "project:test", + lambda _cwd, **_kwargs: "project:test", ) captured: list[str] = [] monkeypatch.setattr( @@ -197,7 +197,7 @@ def test_unexpected_recall_failure_does_not_prevent_prompt_capture( monkeypatch.setattr( hook_module, "resolve_scope_id", - lambda _cwd, *, configured_scope_id: "project:test", + lambda _cwd, **_kwargs: "project:test", ) captured: list[str] = [] monkeypatch.setattr( @@ -232,7 +232,7 @@ def test_capture_failure_does_not_prevent_context_injection( monkeypatch.setattr( hook_module, "resolve_scope_id", - lambda _cwd, *, configured_scope_id: "project:test", + lambda _cwd, **_kwargs: "project:test", ) monkeypatch.setattr( hook_module, @@ -305,7 +305,7 @@ def test_recall_and_capture_share_one_http_deadline( monkeypatch.setattr( hook_module, "resolve_scope_id", - lambda _cwd, *, configured_scope_id: "project:test", + lambda _cwd, **_kwargs: "project:test", ) _run_main( @@ -339,7 +339,7 @@ def test_prompt_capture_can_be_disabled( monkeypatch.setattr( hook_module, "resolve_scope_id", - lambda _cwd, *, configured_scope_id: "project:test", + lambda _cwd, **_kwargs: "project:test", ) output = io.StringIO() diff --git a/tests/codex_plugin/conftest.py b/tests/codex_plugin/conftest.py index 68267b997..30c0aee4f 100644 --- a/tests/codex_plugin/conftest.py +++ b/tests/codex_plugin/conftest.py @@ -35,7 +35,7 @@ def _load_module(name: str, path: Path) -> ModuleType: @pytest.fixture def scope_module() -> ModuleType: - return _load_module("powercontext_codex_scope", PLUGIN_ROOT / "scripts" / "project_scope.py") + return _load_module("powercontext_codex_scope", PLUGIN_ROOT / "scripts" / "scope_binding.py") @pytest.fixture @@ -51,3 +51,13 @@ def isolated_diagnostic_state(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) - @pytest.fixture def settings_module() -> ModuleType: return _load_module("powercontext_codex_settings", PLUGIN_ROOT / "settings.py") + + +@pytest.fixture +def bind_tools_module() -> ModuleType: + return _load_module("powercontext_codex_bind_tools", PLUGIN_ROOT / "hooks" / "bind_tools.py") + + +@pytest.fixture +def session_binding_module() -> ModuleType: + return _load_module("powercontext_codex_session_binding", PLUGIN_ROOT / "hooks" / "session_binding.py") diff --git a/tests/codex_plugin/test_contract.py b/tests/codex_plugin/test_contract.py index 211248fb8..c6e37c082 100644 --- a/tests/codex_plugin/test_contract.py +++ b/tests/codex_plugin/test_contract.py @@ -15,9 +15,9 @@ from __future__ import annotations import json -import os from pathlib import Path from types import ModuleType +from typing import Any, cast import pytest from pydantic import ValidationError @@ -25,67 +25,43 @@ PLUGIN_ROOT = Path(__file__).resolve().parents[2] / "integrations" / "codex" / "plugins" / "powercontext" -@pytest.mark.parametrize( - ("remote", "expected"), - [ - ("https://github.com/OceanBase/powercontext.git", "github.com/OceanBase/powercontext"), - ("ssh://git@github.com/OceanBase/powercontext.git", "github.com/OceanBase/powercontext"), - ("git@github.com:OceanBase/powercontext.git", "github.com/OceanBase/powercontext"), - ], -) -def test_scope_normalizes_network_git_remotes( - scope_module: ModuleType, - remote: str, - expected: str, -) -> None: - assert scope_module.normalize_git_remote(remote) == expected - - -def test_scope_override_wins(scope_module: ModuleType, tmp_path: Path) -> None: - assert ( - scope_module.derive_scope_id( - str(tmp_path), - configured_scope_id="project:explicit", - ) - == "project:explicit" - ) - - -def test_scope_binding_is_persisted_in_git_private_state( +def test_scope_resolver_uses_server_binding_and_fixes_new_session( scope_module: ModuleType, monkeypatch: pytest.MonkeyPatch, tmp_path: Path, ) -> None: - git_directory = tmp_path / ".git" - git_directory.mkdir() - monkeypatch.setattr( - scope_module, - "_git_value", - lambda _cwd, *arguments: str(git_directory) if arguments == ("rev-parse", "--absolute-git-dir") else None, - ) - - assert scope_module.bind_workstream_scope(str(tmp_path), "handoff-ui-review") == "handoff-ui-review" - assert scope_module.read_bound_scope_id(str(tmp_path)) == "handoff-ui-review" - assert scope_module.resolve_scope_id(str(tmp_path)) == "handoff-ui-review" - assert scope_module.resolve_scope_id(str(tmp_path), configured_scope_id="scope:override") == "scope:override" - state_path = git_directory / "powercontext" / "codex-workspace.json" - if os.name != "nt": - assert state_path.stat().st_mode & 0o777 == 0o600 - - assert scope_module.clear_workstream_scope(str(tmp_path)) is True - assert scope_module.read_bound_scope_id(str(tmp_path)) is None - assert scope_module.clear_workstream_scope(str(tmp_path)) is False + requests: list[tuple[str, dict[str, object], str]] = [] + def post(path, payload, *, settings, deadline, method="POST"): + requests.append((path, payload, method)) + return {"scope_id": "scp_00000000000000000000000000"} -def test_scope_binding_requires_a_git_workspace( - scope_module: ModuleType, - monkeypatch: pytest.MonkeyPatch, - tmp_path: Path, -) -> None: + monkeypatch.setattr(scope_module, "_post_json", post) monkeypatch.setattr(scope_module, "_git_value", lambda *_args: None) - with pytest.raises(ValueError, match="requires a Git workspace"): - scope_module.bind_workstream_scope(str(tmp_path), "handoff-ui-review") + resolved = scope_module.resolve_scope_id( + str(tmp_path), + session_id="session-1", + settings=scope_module.CodexPluginSettings(), + deadline=float("inf"), + persist_session=True, + ) + + assert resolved == "scp_00000000000000000000000000" + assert requests[0][0] == "/v1/scope-bindings/resolve" + binding_keys = cast(list[dict[str, Any]], requests[0][1]["binding_keys"]) + assert [key["kind"] for key in binding_keys] == ["session", "workspace"] + assert binding_keys[0]["external_id"] == "session-1" + assert binding_keys[1]["external_id"] != str(tmp_path) + assert not binding_keys[1]["external_id"].startswith("scp_") + assert requests[1] == ( + "/v1/scope-bindings", + { + "key": {"integration": "codex", "kind": "session", "external_id": "session-1"}, + "scope_id": resolved, + }, + "PUT", + ) def test_codex_settings_precedence_and_validation( @@ -177,26 +153,13 @@ def test_codex_settings_normalize_the_mcp_path_to_http_base( assert settings_module._http_base_url("https://memory.example/api/mcp/") == "https://memory.example/api" -def test_project_context_skill_uses_the_high_level_work_continuity_loop() -> None: - content = (PLUGIN_ROOT / "skills" / "project-context" / "SKILL.md").read_text(encoding="utf-8") - - assert 'description: Create and commit a current-work Handoff when the user says "交接"' in content - assert '"$PLUGIN_ROOT/.venv/bin/python" "$PLUGIN_ROOT/scripts/project_scope.py"' in content - assert "uv run --frozen" not in content - assert "create_work_contract" in content - assert "select_handoff_workstream" in content - assert "handoff_current_work" in content - assert "acknowledge_handoff" in content - assert "record_task_outcome" in content - assert "Complete a one-turn durable Handoff" in content - assert "do not ask for a second confirmation" in content - assert "native\npicker" in content - assert "Pass the returned `handoff` member unchanged" in content - assert "no durable Handoff milestone was committed" in content - assert "canonical temporary carrier" in content - assert 'selection: "prepared"' in content - assert "call `commit_handoff` only when" in content - assert "Do not treat every session stop as task completion" in content +def test_codex_hooks_fix_session_and_data_plane_bindings() -> None: + configuration = json.loads((PLUGIN_ROOT / "hooks" / "hooks.json").read_text()) + + assert "session_binding.py" in configuration["hooks"]["SessionStart"][0]["hooks"][0]["command"] + pre_tool_use = configuration["hooks"]["PreToolUse"][0] + assert pre_tool_use["matcher"] == "mcp__powercontext__.*" + assert "bind_tools.py" in pre_tool_use["hooks"][0]["command"] def test_powercontext_plugin_advertises_the_one_turn_handoff() -> None: diff --git a/tests/codex_plugin/test_recall.py b/tests/codex_plugin/test_recall.py index bd2650790..39b3fac0a 100644 --- a/tests/codex_plugin/test_recall.py +++ b/tests/codex_plugin/test_recall.py @@ -71,7 +71,7 @@ def test_recall_emits_bounded_untrusted_context( monkeypatch.setattr( recall_module, "resolve_scope_id", - lambda _cwd, *, configured_scope_id: "project:test", + lambda _cwd, **_kwargs: "project:test", ) captured: list[tuple[str, str]] = [] monkeypatch.setattr( @@ -116,7 +116,7 @@ def test_recall_reads_utf8_stdin_on_windows_encodings( monkeypatch.setattr( recall_module, "resolve_scope_id", - lambda _cwd, *, configured_scope_id: "project:test", + lambda _cwd, **_kwargs: "project:test", ) monkeypatch.setattr( recall_module, @@ -154,7 +154,7 @@ def test_recall_failure_is_non_blocking( monkeypatch.setattr( recall_module, "resolve_scope_id", - lambda _cwd, *, configured_scope_id: "project:test", + lambda _cwd, **_kwargs: "project:test", ) monkeypatch.setattr(recall_module, "_capture_prompt", lambda *_args, **_kwargs: {"position": 1}) monkeypatch.setattr( @@ -303,7 +303,7 @@ def test_recall_records_exact_injected_context_only_when_eval_trace_is_enabled( monkeypatch.setattr( recall_module, "resolve_scope_id", - lambda _cwd, *, configured_scope_id: "eval:run-1:on", + lambda _cwd, **_kwargs: "eval:run-1:on", ) monkeypatch.setattr(recall_module, "_capture_prompt", lambda *_args, **_kwargs: {"position": 1}) monkeypatch.setattr( @@ -356,7 +356,7 @@ def test_recall_does_not_write_an_evaluation_trace_by_default( monkeypatch.setattr( recall_module, "resolve_scope_id", - lambda _cwd, *, configured_scope_id: "project:test", + lambda _cwd, **_kwargs: "project:test", ) monkeypatch.setattr(recall_module, "_capture_prompt", lambda *_args, **_kwargs: {"position": 1}) monkeypatch.setattr( @@ -428,7 +428,7 @@ def test_hook_accepts_codex_event_name_variants( monkeypatch.setattr( recall_module, "resolve_scope_id", - lambda _cwd, *, configured_scope_id: "project:test", + lambda _cwd, **_kwargs: "project:test", ) monkeypatch.setattr( sys, diff --git a/tests/codex_plugin/test_scope_binding.py b/tests/codex_plugin/test_scope_binding.py new file mode 100644 index 000000000..4f60f253a --- /dev/null +++ b/tests/codex_plugin/test_scope_binding.py @@ -0,0 +1,223 @@ +# Copyright (c) 2026 OceanBase. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +from __future__ import annotations + +import io +import json +import sys +from types import ModuleType + +import pytest + + +def test_pre_tool_hook_overwrites_agent_scope_with_session_binding( + bind_tools_module: ModuleType, + monkeypatch: pytest.MonkeyPatch, +) -> None: + monkeypatch.setattr( + bind_tools_module, + "resolve_scope_id", + lambda _cwd, *, session_id, **_kwargs: f"scope-for-{session_id}", + ) + monkeypatch.setattr( + sys, + "stdin", + io.StringIO( + json.dumps({ + "hook_event_name": "PreToolUse", + "session_id": "session-a", + "cwd": "/workspace", + "tool_name": "mcp__powercontext__remember_memory", + "tool_input": {"scope_id": "agent-selected", "kind": "decision", "text": "Use Scope binding."}, + }) + ), + ) + output = io.StringIO() + monkeypatch.setattr(sys, "stdout", output) + + assert bind_tools_module.main() == 0 + result = json.loads(output.getvalue())["hookSpecificOutput"] + assert result["permissionDecision"] == "allow" + assert result["updatedInput"]["scope_id"] == "scope-for-session-a" + assert result["updatedInput"]["text"] == "Use Scope binding." + + +def test_pre_tool_hook_fixes_control_binding_to_current_session( + bind_tools_module: ModuleType, + monkeypatch: pytest.MonkeyPatch, +) -> None: + monkeypatch.setattr( + sys, + "stdin", + io.StringIO( + json.dumps({ + "hook_event_name": "PreToolUse", + "session_id": "session-a", + "cwd": "/workspace", + "tool_name": "mcp__powercontext__set_scope_binding", + "tool_input": { + "key": {"integration": "other", "kind": "session", "external_id": "session-b"}, + "scope_id": "target-scope", + }, + }) + ), + ) + output = io.StringIO() + monkeypatch.setattr(sys, "stdout", output) + + assert bind_tools_module.main() == 0 + updated = json.loads(output.getvalue())["hookSpecificOutput"]["updatedInput"] + assert updated == { + "key": {"integration": "codex", "kind": "session", "external_id": "session-a"}, + "scope_id": "target-scope", + } + + +def test_pre_tool_hook_resolves_only_the_current_session_scope( + bind_tools_module: ModuleType, + monkeypatch: pytest.MonkeyPatch, +) -> None: + monkeypatch.setattr( + bind_tools_module, + "binding_keys", + lambda cwd, *, session_id: [ + {"integration": "codex", "kind": "session", "external_id": session_id}, + {"integration": "codex", "kind": "workspace", "external_id": cwd}, + ], + ) + monkeypatch.setattr( + sys, + "stdin", + io.StringIO( + json.dumps({ + "hook_event_name": "PreToolUse", + "session_id": "session-a", + "cwd": "/workspace", + "tool_name": "mcp__powercontext__resolve_scope_binding", + "tool_input": { + "explicit_scope_id": "agent-selected", + "binding_keys": [{"integration": "other", "kind": "session", "external_id": "session-b"}], + }, + }) + ), + ) + output = io.StringIO() + monkeypatch.setattr(sys, "stdout", output) + + assert bind_tools_module.main() == 0 + updated = json.loads(output.getvalue())["hookSpecificOutput"]["updatedInput"] + assert updated == { + "explicit_scope_id": None, + "binding_keys": [ + {"integration": "codex", "kind": "session", "external_id": "session-a"}, + {"integration": "codex", "kind": "workspace", "external_id": "/workspace"}, + ], + } + + +def test_pre_tool_hook_preserves_explicit_publication_boundaries( + bind_tools_module: ModuleType, + monkeypatch: pytest.MonkeyPatch, +) -> None: + tool_input = { + "source": { + "scope_id": "source-scope", + "artifact": {"family": "handoff", "artifact_id": "handoff", "revision": 3}, + }, + "target_scope_id": "target-scope", + "idempotency_key": "handoff-3", + } + monkeypatch.setattr( + sys, + "stdin", + io.StringIO( + json.dumps({ + "hook_event_name": "PreToolUse", + "session_id": "session-a", + "cwd": "/workspace", + "tool_name": "mcp__powercontext__publish_artifact", + "tool_input": tool_input, + }) + ), + ) + output = io.StringIO() + monkeypatch.setattr(sys, "stdout", output) + + assert bind_tools_module.main() == 0 + result = json.loads(output.getvalue())["hookSpecificOutput"] + assert result["permissionDecision"] == "allow" + assert result["updatedInput"] == tool_input + + +def test_pre_tool_hook_limits_handoff_report_to_the_bound_scope( + bind_tools_module: ModuleType, + monkeypatch: pytest.MonkeyPatch, +) -> None: + monkeypatch.setattr( + bind_tools_module, + "resolve_scope_id", + lambda _cwd, *, session_id, **_kwargs: f"scope-for-{session_id}", + ) + monkeypatch.setattr( + sys, + "stdin", + io.StringIO( + json.dumps({ + "hook_event_name": "PreToolUse", + "session_id": "session-a", + "cwd": "/workspace", + "tool_name": "mcp__powercontext__get_handoff_report", + "tool_input": {"selection": {"mode": "all"}, "format": "json"}, + }) + ), + ) + output = io.StringIO() + monkeypatch.setattr(sys, "stdout", output) + + assert bind_tools_module.main() == 0 + updated = json.loads(output.getvalue())["hookSpecificOutput"]["updatedInput"] + assert updated == { + "selection": {"mode": "exact", "scope_ids": ["scope-for-session-a"]}, + "format": "json", + } + + +def test_pre_tool_hook_denies_data_plane_when_binding_is_unavailable( + bind_tools_module: ModuleType, + monkeypatch: pytest.MonkeyPatch, +) -> None: + def fail(*_args, **_kwargs): + raise bind_tools_module.ScopeBindingError + + monkeypatch.setattr(bind_tools_module, "resolve_scope_id", fail) + monkeypatch.setattr( + sys, + "stdin", + io.StringIO( + json.dumps({ + "hook_event_name": "PreToolUse", + "session_id": "session-a", + "cwd": "/workspace", + "tool_name": "mcp__powercontext__search_memory", + "tool_input": {"query": "current state"}, + }) + ), + ) + output = io.StringIO() + monkeypatch.setattr(sys, "stdout", output) + + assert bind_tools_module.main() == 0 + result = json.loads(output.getvalue())["hookSpecificOutput"] + assert result["permissionDecision"] == "deny" diff --git a/tests/e2e/test_builtin_runtime.py b/tests/e2e/test_builtin_runtime.py index b18f47584..8de6b301a 100644 --- a/tests/e2e/test_builtin_runtime.py +++ b/tests/e2e/test_builtin_runtime.py @@ -28,6 +28,7 @@ SearchMemoryRequest, open_builtin_runtime, ) +from powercontext.builtin.scope import ScopeDraft, ScopeMutation from powercontext.builtin.sources import ContentSource @@ -56,22 +57,29 @@ async def scenario() -> None: BuiltinConfig(database=SQLiteConfig()), candidate_pipeline=_ContentCandidatePipeline(), ) as runtime: - captured = await runtime.sources.for_scope("project").capture( + assert runtime.scopes is not None + project = await runtime.scopes.create( + ScopeDraft(title="Project", summary="Runtime acceptance", idempotency_key="project") + ) + empty = await runtime.scopes.create( + ScopeDraft(title="Empty", summary="Empty acceptance", idempotency_key="empty-project") + ) + captured = await runtime.sources.for_scope(project.scope_id).capture( CaptureSource( source_id="turn-1", content="PowerContext composes an atomic SQL provider.", metadata={"origin": "e2e"}, ) ) - flushed = await runtime.memory.for_scope("project").flush() - found = await runtime.memory.for_scope("project").search(SearchMemoryRequest(query="atomic SQL provider")) - prepared = await runtime.context.for_scope("project").prepare( - PrepareContextRequest(query="atomic SQL provider") + flushed = await runtime.memory.for_scope(project.scope_id).flush() + found = await runtime.memory.for_scope(project.scope_id).search( + SearchMemoryRequest(query="atomic SQL provider") ) - no_memory = await runtime.context.for_scope("empty-project").prepare( - PrepareContextRequest(query="anything") + prepared = await runtime.context.for_scope(project.scope_id).prepare( + PrepareContextRequest(query="atomic SQL provider") ) - no_match = await runtime.context.for_scope("project").prepare( + no_memory = await runtime.context.for_scope(empty.scope_id).prepare(PrepareContextRequest(query="anything")) + no_match = await runtime.context.for_scope(project.scope_id).prepare( PrepareContextRequest(query="unrelated-zebra-phrase") ) @@ -92,6 +100,83 @@ async def scenario() -> None: asyncio.run(scenario()) +def test_prepare_context_reads_only_direct_context_references() -> None: + async def scenario() -> None: + async with open_builtin_runtime(BuiltinConfig(database=SQLiteConfig())) as runtime: + assert runtime.scopes is not None + shared = await runtime.scopes.create( + ScopeDraft(title="Shared", summary="Reusable evidence", idempotency_key="shared") + ) + middle = await runtime.scopes.create( + ScopeDraft( + title="Middle", + summary="Reads shared evidence", + context_references=(shared.scope_id,), + idempotency_key="middle", + ) + ) + reader = await runtime.scopes.create( + ScopeDraft( + title="Reader", + summary="Reads middle only", + context_references=(middle.scope_id,), + idempotency_key="reader", + ) + ) + child = await runtime.scopes.create( + ScopeDraft( + title="Child", + summary="Organized under shared", + parent_scope_id=shared.scope_id, + idempotency_key="child", + ) + ) + await runtime.memory.for_scope(shared.scope_id).remember( + RememberMemoryRequest(entries=(MemoryEntryInput(kind="fact", text="Shared direct context evidence."),)) + ) + await runtime.memory.for_scope(middle.scope_id).remember( + RememberMemoryRequest(entries=(MemoryEntryInput(kind="fact", text="Middle reverse-only evidence."),)) + ) + + direct = await runtime.context.for_scope(middle.scope_id).prepare( + PrepareContextRequest(query="direct context evidence") + ) + transitive = await runtime.context.for_scope(reader.scope_id).prepare( + PrepareContextRequest(query="direct context evidence") + ) + reverse = await runtime.context.for_scope(shared.scope_id).prepare( + PrepareContextRequest(query="middle reverse-only evidence") + ) + parent_only = await runtime.context.for_scope(child.scope_id).prepare( + PrepareContextRequest(query="direct context evidence") + ) + + assert direct.status == "ready" + assert direct.content is not None + item = json.loads(direct.content.splitlines()[-2])["items"][0] + assert item["citation"]["memory"]["scope_id"] == shared.scope_id + assert transitive.status == "empty" + assert reverse.status == "empty" + assert parent_only.status == "empty" + + updated = await runtime.scopes.update( + reader.scope_id, + ScopeMutation( + expected_version=reader.version, + title=reader.title, + summary=reader.summary, + context_references=(shared.scope_id,), + ), + ) + assert updated.context_references == (shared.scope_id,) + now_direct = await runtime.context.for_scope(reader.scope_id).prepare( + PrepareContextRequest(query="direct context evidence") + ) + assert now_direct.status == "ready" + + asyncio.run(scenario()) + + class _ConcurrentReranker: policy_id = "test.concurrent-rerank.v1" @@ -114,7 +199,11 @@ def test_same_scope_read_only_searches_do_not_serialize_reranking() -> None: async def scenario() -> None: reranker = _ConcurrentReranker() async with open_builtin_runtime(BuiltinConfig(), memory_reranker=reranker) as runtime: - memory = runtime.memory.for_scope("parallel-search") + assert runtime.scopes is not None + scope = await runtime.scopes.create( + ScopeDraft(title="Parallel", summary="Concurrent read acceptance", idempotency_key="parallel-search") + ) + memory = runtime.memory.for_scope(scope.scope_id) await memory.remember( RememberMemoryRequest(entries=(MemoryEntryInput(kind="fact", text="Parallel search fact."),)) ) diff --git a/tests/e2e/test_candidate_review.py b/tests/e2e/test_candidate_review.py index 49ab5eac7..3236cc0a4 100644 --- a/tests/e2e/test_candidate_review.py +++ b/tests/e2e/test_candidate_review.py @@ -34,6 +34,7 @@ ApproveArtifactCandidateRequest, CandidateFamily, CaptureContentSourceRequest, + CreateScopeRequest, ExperienceProposal, GetArtifactCandidateRequest, GetExperienceRequest, @@ -94,7 +95,6 @@ def test_http_sdk_experience_review_vertical_slice(database_kind: str, tmp_path: else: settings = _settings(tmp_path / "review.db") app = create_server_app(settings=settings) - scope_id = f"candidate-review-{uuid4()}" async def scenario() -> None: async with ( @@ -106,6 +106,14 @@ async def scenario() -> None: ): client = PowerContextClient("http://testserver", http_client=transport, trust_transport_security=True) capabilities = await client.get_capabilities() + scope = await client.create_scope( + CreateScopeRequest( + title="Candidate review", + summary="Isolated candidate review acceptance workflow.", + idempotency_key=f"candidate-review-{uuid4()}", + ) + ) + scope_id = scope.scope_id captured = await client.capture_content_source( CaptureContentSourceRequest( scope_id=scope_id, @@ -298,15 +306,18 @@ async def get_skill(self, request): cli = create_cli([]) runner = CliRunner() with TestClient(app) as transport: + default_scope = transport.get("/v1/scopes/default") + default_scope.raise_for_status() + scope_id = default_scope.json()["scope_id"] captured = transport.post( "/v1/sources/content", - json={"scope_id": "project", "source_id": "task-1", "content": "bounded evidence"}, + json={"scope_id": scope_id, "source_id": "task-1", "content": "bounded evidence"}, ).json() proposal = _proposal("Initial lesson.").model_dump(mode="json") first = transport.post( "/v1/experience/propose", json={ - "scope_id": "project", + "scope_id": scope_id, "proposal": proposal, "source_refs": [captured["source"]], "artifact_refs": [], @@ -315,16 +326,16 @@ async def get_skill(self, request): second = transport.post( "/v1/experience/propose", json={ - "scope_id": "project", + "scope_id": scope_id, "proposal": proposal, "source_refs": [captured["source"]], "artifact_refs": [], }, ).json() - listed = runner.invoke(cli, ["candidate", "list", "--scope-id", "project"]) + listed = runner.invoke(cli, ["candidate", "list", "--scope-id", scope_id]) shown = runner.invoke( cli, - ["candidate", "show", "--scope-id", "project", first["candidate_id"]], + ["candidate", "show", "--scope-id", scope_id, first["candidate_id"]], ) revised = runner.invoke( cli, @@ -333,7 +344,7 @@ async def get_skill(self, request): "revise", "experience", "--scope-id", - "project", + scope_id, "--expected-version", "1", "--situation", @@ -355,7 +366,7 @@ async def get_skill(self, request): "candidate", "approve", "--scope-id", - "project", + scope_id, "--expected-version", "2", first["candidate_id"], @@ -367,7 +378,7 @@ async def get_skill(self, request): "candidate", "reject", "--scope-id", - "project", + scope_id, "--expected-version", "1", "--reason", @@ -377,13 +388,13 @@ async def get_skill(self, request): ) approved_head = transport.post( "/v1/artifact-candidates/get", - json={"scope_id": "project", "candidate_id": first["candidate_id"]}, + json={"scope_id": scope_id, "candidate_id": first["candidate_id"]}, ).json() experience_ref = approved_head["result_artifact"] skill_candidate = transport.post( "/v1/skill/propose", json={ - "scope_id": "project", + "scope_id": scope_id, "proposal": _skill_proposal().model_dump(mode="json"), "source_refs": [], "artifact_refs": [experience_ref], @@ -392,7 +403,7 @@ async def get_skill(self, request): skill_approved = transport.post( "/v1/artifact-candidates/approve", json={ - "scope_id": "project", + "scope_id": scope_id, "candidate_id": skill_candidate["candidate_id"], "expected_version": 1, }, @@ -405,7 +416,7 @@ async def get_skill(self, request): "skill", "show", "--scope-id", - "project", + scope_id, "--revision", str(skill_ref["revision"]), skill_ref["artifact_id"], @@ -419,7 +430,7 @@ async def get_skill(self, request): "--target", "codex", "--scope-id", - "project", + scope_id, "--revision", str(skill_ref["revision"]), "--destination", diff --git a/tests/e2e/test_claude_code_service_chain.py b/tests/e2e/test_claude_code_service_chain.py index caa5ea4ea..7c909a388 100644 --- a/tests/e2e/test_claude_code_service_chain.py +++ b/tests/e2e/test_claude_code_service_chain.py @@ -26,6 +26,7 @@ import time from pathlib import Path +import httpx import pytest import uvicorn from fastmcp import Client @@ -42,7 +43,6 @@ PROJECT_ROOT = Path(__file__).resolve().parents[2] CLAUDE_PLUGIN = PROJECT_ROOT / "integrations" / "claude-code" / "plugins" / "powercontext" CODEX_PLUGIN = PROJECT_ROOT / "integrations" / "codex" / "plugins" / "powercontext" -SCOPE_ID = "git:github.com/oceanbase/powercontext" AUTH_TOKEN = "claude-code-e2e-token" # noqa: S105 - non-secret test credential. AUTHORIZATION = f"Bearer {AUTH_TOKEN}" @@ -107,6 +107,10 @@ def test_claude_sessions_and_codex_share_one_project_memory( mcp_configuration = json.loads((codex_plugin / ".mcp.json").read_text()) mcp_configuration["mcpServers"]["powercontext"]["url"] = f"{base_url}/mcp" (codex_plugin / ".mcp.json").write_text(json.dumps(mcp_configuration)) + scope_id = _create_scope( + base_url, + authorization=AUTHORIZATION if authentication_enabled else None, + ) captured = _run_claude_hook( prompt="Remember the shared project context service.", @@ -114,6 +118,7 @@ def test_claude_sessions_and_codex_share_one_project_memory( prompt_id="prompt-1", base_url=base_url, authorization=AUTHORIZATION if authentication_enabled else None, + scope_id=scope_id, ) assert captured.stdout == "" assert AUTH_TOKEN not in captured.stderr @@ -124,6 +129,7 @@ def test_claude_sessions_and_codex_share_one_project_memory( prompt_id="prompt-2", base_url=base_url, authorization=AUTHORIZATION if authentication_enabled else None, + scope_id=scope_id, ) claude_context = json.loads(recalled_by_claude.stdout)["hookSpecificOutput"]["additionalContext"] claude_envelope = json.loads(claude_context.splitlines()[-2]) @@ -134,6 +140,7 @@ def test_claude_sessions_and_codex_share_one_project_memory( codex_plugin, prompt="Which shared project context service should we use?", authorization=AUTHORIZATION if authentication_enabled else None, + scope_id=scope_id, ) codex_context = json.loads(recalled_by_codex.stdout)["hookSpecificOutput"]["additionalContext"] codex_envelope = json.loads(codex_context.splitlines()[-2]) @@ -214,8 +221,16 @@ def _claude_mcp_connection(base_url: str, *, authorization: str | None) -> tuple async def _exercise_explicit_mcp_workflows(endpoint: str, headers: dict[str, str]) -> dict[str, object]: - scope_id = "project:claude-code-mcp" async with Client(StreamableHttpTransport(endpoint, headers=headers)) as client: + created_scope = await client.call_tool( + "create_scope", + { + "title": "Claude Code MCP workflow", + "summary": "Explicit memory and Handoff workflow acceptance.", + "idempotency_key": "claude-code-mcp-workflow", + }, + ) + scope_id = (created_scope.structured_content or {})["scope_id"] remembered_result = await client.call_tool( "remember_memory", { @@ -302,6 +317,7 @@ def _run_claude_hook( prompt_id: str, base_url: str, authorization: str | None, + scope_id: str, ) -> subprocess.CompletedProcess[str]: environment: dict[str, str] = { **os.environ, @@ -309,7 +325,7 @@ def _run_claude_hook( "POWERCONTEXT_CLAUDE_FLUSH_ON_CAPTURE": "true", "POWERCONTEXT_CLAUDE_HTTP_BUDGET_SECONDS": "10", "POWERCONTEXT_CLAUDE_REQUEST_TIMEOUT_SECONDS": "5", - "POWERCONTEXT_CLAUDE_SCOPE_ID": SCOPE_ID, + "POWERCONTEXT_CLAUDE_SCOPE_ID": scope_id, } environment.pop("POWERCONTEXT_CLAUDE_AUTHORIZATION", None) if authorization is not None: @@ -337,10 +353,11 @@ def _run_codex_hook( *, prompt: str, authorization: str | None, + scope_id: str, ) -> subprocess.CompletedProcess[str]: environment: dict[str, str] = { **os.environ, - "POWERCONTEXT_CODEX_SCOPE_ID": SCOPE_ID, + "POWERCONTEXT_CODEX_SCOPE_ID": scope_id, "POWERCONTEXT_CODEX_CAPTURE_PROMPTS": "false", "POWERCONTEXT_CODEX_HTTP_BUDGET_SECONDS": "10", "POWERCONTEXT_CODEX_REQUEST_TIMEOUT_SECONDS": "5", @@ -366,6 +383,22 @@ def _run_codex_hook( ) +def _create_scope(base_url: str, *, authorization: str | None) -> str: + headers = {"Authorization": authorization} if authorization is not None else None + response = httpx.post( + f"{base_url}/v1/scopes", + headers=headers, + json={ + "title": "Shared agent work", + "summary": "Shared memory for the Claude Code and Codex sessions.", + "idempotency_key": "shared-agent-work", + }, + timeout=5, + ) + response.raise_for_status() + return response.json()["scope_id"] + + def _wait_until_started(server: uvicorn.Server, thread: threading.Thread) -> None: deadline = time.monotonic() + 10 while thread.is_alive() and not server.started and time.monotonic() < deadline: diff --git a/tests/e2e/test_codex_service_chain.py b/tests/e2e/test_codex_service_chain.py index 48a94bd96..994cf0b05 100644 --- a/tests/e2e/test_codex_service_chain.py +++ b/tests/e2e/test_codex_service_chain.py @@ -25,6 +25,7 @@ import time from pathlib import Path +import httpx import pytest import uvicorn from fastmcp import Client @@ -46,7 +47,6 @@ PROJECT_ROOT = Path(__file__).resolve().parents[2] CODEX_PLUGIN = PROJECT_ROOT / "integrations" / "codex" / "plugins" / "powercontext" -SCOPE_ID = "project:codex-e2e" AUTH_TOKEN = "codex-e2e-token" # noqa: S105 - non-secret test credential. AUTHORIZATION = f"Bearer {AUTH_TOKEN}" @@ -112,12 +112,17 @@ def test_codex_hook_http_sdk_and_mcp_share_one_composed_context( mcp_configuration = json.loads((plugin / ".mcp.json").read_text()) mcp_configuration["mcpServers"]["powercontext"]["url"] = f"{base_url}/mcp" (plugin / ".mcp.json").write_text(json.dumps(mcp_configuration)) + scope_id = _create_scope( + base_url, + authorization=AUTHORIZATION if authentication_enabled else None, + ) first = _run_hook( plugin, prompt="Remember which object is the composition root.", turn_id="turn-1", authorization=AUTHORIZATION if authentication_enabled else None, + scope_id=scope_id, ) assert first.stdout == "" assert AUTH_TOKEN not in first.stderr @@ -127,6 +132,7 @@ def test_codex_hook_http_sdk_and_mcp_share_one_composed_context( prompt="Which composition root should this project use?", turn_id="turn-2", authorization=AUTHORIZATION if authentication_enabled else None, + scope_id=scope_id, ) context = json.loads(recalled.stdout)["hookSpecificOutput"]["additionalContext"] envelope = json.loads(context.splitlines()[-2]) @@ -138,18 +144,18 @@ async def verify_transport_surfaces() -> None: async with PowerContextClient(base_url, token=AUTH_TOKEN if authentication_enabled else None) as sdk: found = await sdk.search_memory( SearchMemoryRequest( - scope_id=SCOPE_ID, + scope_id=scope_id, query="PowerContext composition root", ) ) prepared = await sdk.prepare_context( PrepareContextRequest( - scope_id=SCOPE_ID, + scope_id=scope_id, query="PowerContext composition root", ) ) entries = await sdk.list_memory_entries( - ListMemoryEntriesRequest(scope_id=SCOPE_ID), + ListMemoryEntriesRequest(scope_id=scope_id), ) assert found.hits assert {hit.text for hit in found.hits} == {"Use PowerContext as the composition root."} @@ -169,7 +175,7 @@ async def verify_transport_surfaces() -> None: result = await mcp.call_tool( "search_memory", { - "scope_id": SCOPE_ID, + "scope_id": scope_id, "query": "PowerContext composition root", }, ) @@ -183,7 +189,7 @@ async def verify_transport_surfaces() -> None: while current.entries: retired = await sdk.retire_memory_entry( RetireMemoryEntryRequest( - scope_id=SCOPE_ID, + scope_id=scope_id, citation=current.entries[0].citation, reason="superseded", ), @@ -191,10 +197,10 @@ async def verify_transport_surfaces() -> None: assert retired.entry is not None retired_entry_ids.add(retired.entry.citation.entry_id) current = await sdk.list_memory_entries( - ListMemoryEntriesRequest(scope_id=SCOPE_ID), + ListMemoryEntriesRequest(scope_id=scope_id), ) audited = await sdk.list_memory_entries( - ListMemoryEntriesRequest(scope_id=SCOPE_ID, include_inactive=True), + ListMemoryEntriesRequest(scope_id=scope_id, include_inactive=True), ) assert current.entries == [] assert {entry.citation.entry_id for entry in audited.entries} == retired_entry_ids @@ -207,6 +213,7 @@ async def verify_transport_surfaces() -> None: prompt="Which composition root should this project use?", turn_id="turn-3", authorization=AUTHORIZATION if authentication_enabled else None, + scope_id=scope_id, ) assert excluded.stdout == "" assert AUTH_TOKEN not in excluded.stderr @@ -217,19 +224,132 @@ async def verify_transport_surfaces() -> None: assert not thread.is_alive() +def test_codex_session_binding_switch_resume_and_child_scope_flow(tmp_path: Path) -> None: + app = create_server_app( + settings=ServerSettings( + database=SQLiteConfig(url=f"sqlite+aiosqlite:///{tmp_path / 'scope-flow.db'}"), + mcp=McpConfig(enabled=True), + ) + ) + listener = socket.socket() + listener.bind(("127.0.0.1", 0)) + host, port = listener.getsockname() + base_url = f"http://{host}:{port}" + server = uvicorn.Server(uvicorn.Config(app, log_level="critical", lifespan="on")) + thread = threading.Thread(target=server.run, kwargs={"sockets": [listener]}, daemon=True) + thread.start() + try: + _wait_until_started(server, thread) + plugin = _copy_plugin(tmp_path, base_url) + root_scope_id = _create_named_scope(base_url, title="Feature", key="codex-feature") + first_child_id = _create_named_scope( + base_url, + title="Research result", + key="codex-research", + parent_scope_id=root_scope_id, + ) + second_child_id = _create_named_scope( + base_url, + title="Validation result", + key="codex-validation", + parent_scope_id=root_scope_id, + ) + + _run_codex_plugin_hook(plugin, "session_binding.py", session_id="session-a") + default_resolution = _run_codex_plugin_hook( + plugin, + "bind_tools.py", + session_id="session-a", + tool_name="mcp__powercontext__resolve_scope_binding", + tool_input={"binding_keys": []}, + ) + default_input = json.loads(default_resolution.stdout)["hookSpecificOutput"]["updatedInput"] + default_scope_id = httpx.post( + f"{base_url}/v1/scope-bindings/resolve", + json=default_input, + timeout=5, + ).json()["scope_id"] + + _set_session_binding(base_url, "session-a", first_child_id) + _run_codex_plugin_hook(plugin, "session_binding.py", session_id="session-a") + first_tool = _run_codex_plugin_hook( + plugin, + "bind_tools.py", + session_id="session-a", + tool_name="mcp__powercontext__search_memory", + tool_input={"scope_id": second_child_id, "query": "current state"}, + ) + first_input = json.loads(first_tool.stdout)["hookSpecificOutput"]["updatedInput"] + assert first_input["scope_id"] == first_child_id + + _run_codex_plugin_hook(plugin, "session_binding.py", session_id="session-b") + second_tool = _run_codex_plugin_hook( + plugin, + "bind_tools.py", + session_id="session-b", + tool_name="mcp__powercontext__search_memory", + tool_input={"scope_id": first_child_id, "query": "current state"}, + ) + second_input = json.loads(second_tool.stdout)["hookSpecificOutput"]["updatedInput"] + assert second_input["scope_id"] == default_scope_id + + _set_session_binding(base_url, "session-b", second_child_id) + switched_tool = _run_codex_plugin_hook( + plugin, + "bind_tools.py", + session_id="session-b", + tool_name="mcp__powercontext__search_memory", + tool_input={"query": "current state"}, + ) + switched_input = json.loads(switched_tool.stdout)["hookSpecificOutput"]["updatedInput"] + assert switched_input["scope_id"] == second_child_id + + _set_session_binding(base_url, "session-a", second_child_id) + _run_codex_plugin_hook(plugin, "session_binding.py", session_id="session-a") + resumed_after_switch = _run_codex_plugin_hook( + plugin, + "bind_tools.py", + session_id="session-a", + tool_name="mcp__powercontext__search_memory", + tool_input={"scope_id": first_child_id, "query": "current state"}, + ) + resumed_after_switch_input = json.loads(resumed_after_switch.stdout)["hookSpecificOutput"]["updatedInput"] + assert resumed_after_switch_input["scope_id"] == second_child_id + + peer_agent = _run_codex_plugin_hook( + plugin, + "bind_tools.py", + session_id="session-b", + tool_name="mcp__powercontext__remember_memory", + tool_input={"scope_id": first_child_id, "kind": "decision", "text": "Shared result"}, + ) + peer_agent_input = json.loads(peer_agent.stdout)["hookSpecificOutput"]["updatedInput"] + assert peer_agent_input["scope_id"] == second_child_id + + scopes = {scope["scope_id"]: scope for scope in httpx.get(f"{base_url}/v1/scopes", timeout=5).json()["items"]} + assert scopes[first_child_id]["parent_scope_id"] == root_scope_id + assert scopes[second_child_id]["parent_scope_id"] == root_scope_id + finally: + server.should_exit = True + thread.join(timeout=10) + listener.close() + assert not thread.is_alive() + + def _run_hook( plugin: Path, *, prompt: str, turn_id: str, authorization: str | None, + scope_id: str, ) -> subprocess.CompletedProcess[str]: environment: dict[str, str] = { **os.environ, "POWERCONTEXT_CODEX_FLUSH_ON_CAPTURE": "true", "POWERCONTEXT_CODEX_HTTP_BUDGET_SECONDS": "10", "POWERCONTEXT_CODEX_REQUEST_TIMEOUT_SECONDS": "5", - "POWERCONTEXT_CODEX_SCOPE_ID": SCOPE_ID, + "POWERCONTEXT_CODEX_SCOPE_ID": scope_id, } environment.pop("POWERCONTEXT_CODEX_AUTHORIZATION", None) if authorization is not None: @@ -252,6 +372,97 @@ def _run_hook( ) +def _create_scope(base_url: str, *, authorization: str | None) -> str: + headers = {"Authorization": authorization} if authorization is not None else None + response = httpx.post( + f"{base_url}/v1/scopes", + headers=headers, + json={ + "title": "Codex end-to-end work", + "summary": "Shared context for the Codex integration test.", + "idempotency_key": "codex-e2e-work", + }, + timeout=5, + ) + response.raise_for_status() + return response.json()["scope_id"] + + +def _copy_plugin(tmp_path: Path, base_url: str) -> Path: + plugin = tmp_path / "scope-plugin" + shutil.copytree(CODEX_PLUGIN, plugin, ignore=shutil.ignore_patterns("__pycache__", ".venv")) + configuration = json.loads((plugin / ".mcp.json").read_text()) + configuration["mcpServers"]["powercontext"]["url"] = f"{base_url}/mcp" + (plugin / ".mcp.json").write_text(json.dumps(configuration)) + return plugin + + +def _create_named_scope( + base_url: str, + *, + title: str, + key: str, + parent_scope_id: str | None = None, +) -> str: + response = httpx.post( + f"{base_url}/v1/scopes", + json={ + "title": title, + "summary": f"Codex integration test Scope for {title}.", + "parent_scope_id": parent_scope_id, + "idempotency_key": key, + }, + timeout=5, + ) + response.raise_for_status() + return response.json()["scope_id"] + + +def _set_session_binding(base_url: str, session_id: str, scope_id: str) -> None: + response = httpx.put( + f"{base_url}/v1/scope-bindings", + json={ + "key": {"integration": "codex", "kind": "session", "external_id": session_id}, + "scope_id": scope_id, + }, + timeout=5, + ) + response.raise_for_status() + + +def _run_codex_plugin_hook( + plugin: Path, + script: str, + *, + session_id: str, + tool_name: str | None = None, + tool_input: dict[str, object] | None = None, +) -> subprocess.CompletedProcess[str]: + payload: dict[str, object] = { + "session_id": session_id, + "cwd": str(PROJECT_ROOT), + } + if tool_name is not None: + payload.update({"tool_name": tool_name, "tool_input": tool_input or {}}) + environment: dict[str, str] = { + **os.environ, + "POWERCONTEXT_CODEX_HTTP_BUDGET_SECONDS": "10", + "POWERCONTEXT_CODEX_REQUEST_TIMEOUT_SECONDS": "5", + } + environment.pop("POWERCONTEXT_CODEX_SCOPE_ID", None) + environment.pop("POWERCONTEXT_CODEX_AUTHORIZATION", None) + return subprocess.run( + [sys.executable, str(plugin / "hooks" / script)], + cwd=PROJECT_ROOT, + env=environment, + input=json.dumps(payload), + text=True, + capture_output=True, + check=True, + timeout=15, + ) + + def _wait_until_started(server: uvicorn.Server, thread: threading.Thread) -> None: deadline = time.monotonic() + 10 while thread.is_alive() and not server.started and time.monotonic() < deadline: diff --git a/tests/e2e/test_dsh_http_chain.py b/tests/e2e/test_dsh_http_chain.py index ebf8a4fa1..b88726d42 100644 --- a/tests/e2e/test_dsh_http_chain.py +++ b/tests/e2e/test_dsh_http_chain.py @@ -31,7 +31,6 @@ from powercontext.server.factory import create_server_app from powercontext.server.settings import McpConfig, ServerSettings -SCOPE_ID = "project:dsh-e2e" TEXT = "Keep the DSH plugin on the public HTTP contract." @@ -54,18 +53,19 @@ async def scenario() -> None: client = PowerContextClient("http://testserver", http_client=transport, trust_transport_security=True) live = await client.get_liveness() ready = await client.get_readiness() + scope_id = (await client.get_default_scope()).scope_id remembered = await client.remember_memory( - RememberMemoryRequest(scope_id=SCOPE_ID, kind="decision", text=TEXT), + RememberMemoryRequest(scope_id=scope_id, kind="decision", text=TEXT), ) found = await client.search_memory( - SearchMemoryRequest(scope_id=SCOPE_ID, query="DSH plugin HTTP contract"), + SearchMemoryRequest(scope_id=scope_id, query="DSH plugin HTTP contract"), ) prepared = await client.prepare_context( - PrepareContextRequest(scope_id=SCOPE_ID, query="DSH plugin HTTP contract"), + PrepareContextRequest(scope_id=scope_id, query="DSH plugin HTTP contract"), ) captured = await client.capture_content_source( CaptureContentSourceRequest( - scope_id=SCOPE_ID, + scope_id=scope_id, source_id="dsh-e2e-turn-1", content="Call through the plugin client without a model.", metadata={"origin": "dsh", "event": "e2e"}, diff --git a/tests/e2e/test_external_skill_registry.py b/tests/e2e/test_external_skill_registry.py index f8e6a1aea..ec711e1e3 100644 --- a/tests/e2e/test_external_skill_registry.py +++ b/tests/e2e/test_external_skill_registry.py @@ -74,20 +74,19 @@ async def scenario() -> None: capabilities = await client.get_capabilities() assert capabilities.external_skill_registry is True assert capabilities.managed_skill_generation is False + scope_id = (await client.get_default_scope()).scope_id - scan = await client.scan_external_skills(ScanExternalSkillsRequest(scope_id="project:example")) + scan = await client.scan_external_skills(ScanExternalSkillsRequest(scope_id=scope_id)) registration = scan.registrations[0] - available = await client.list_external_skills(ListExternalSkillsRequest(scope_id="project:example")) + available = await client.list_external_skills(ListExternalSkillsRequest(scope_id=scope_id)) assert available.skills[0].entrypoint == str(manifest) manifest.write_text(manifest.read_text(encoding="utf-8") + "Changed.\n", encoding="utf-8") - assert ( - await client.list_external_skills(ListExternalSkillsRequest(scope_id="project:example")) - ).skills == [] + assert (await client.list_external_skills(ListExternalSkillsRequest(scope_id=scope_id))).skills == [] stale = await client.resolve_external_skill( ResolveExternalSkillRequest( - scope_id="project:example", + scope_id=scope_id, external_skill_id=registration.external_skill_id, fingerprint=registration.fingerprint, ) @@ -132,13 +131,14 @@ async def scenario() -> None: base_url="http://testserver", ) as transport: client = PowerContextClient("http://testserver", http_client=transport, trust_transport_security=True) + scope_id = (await client.get_default_scope()).scope_id registration = ( - await client.scan_external_skills(ScanExternalSkillsRequest(scope_id="project:example")) + await client.scan_external_skills(ScanExternalSkillsRequest(scope_id=scope_id)) ).registrations[0] imported = await client.import_external_skill( ImportExternalSkillRequest( - scope_id="project:example", + scope_id=scope_id, external_skill_id=registration.external_skill_id, fingerprint=registration.fingerprint, mode=ExternalSkillImportMode.IMPORT, diff --git a/tests/e2e/test_langgraph_chain.py b/tests/e2e/test_langgraph_chain.py index d52e066f9..ce62dd7d7 100644 --- a/tests/e2e/test_langgraph_chain.py +++ b/tests/e2e/test_langgraph_chain.py @@ -45,6 +45,8 @@ from powercontext.builtin.persistence.sqlite import SQLiteConfig from powercontext.builtin.runtime import InferenceConfig +from powercontext.client import PowerContextClient +from powercontext.http import ResolveScopeBindingRequest from powercontext.server.factory import create_server_app from powercontext.server.settings import BearerAuthConfig, McpConfig, ServerSettings @@ -52,7 +54,6 @@ from powercontext_langgraph import PowerContextRecall, PowerContextScope, powercontext_remember -SCOPE_ID = "project:langgraph-e2e" AUTH_TOKEN = "langgraph-e2e-token" # noqa: S105 - non-secret test credential. MEMORY_TEXT = "Adopt hexagonal architecture for the payment gateway." UNTRUSTED_LABEL = "untrusted historical evidence" @@ -119,16 +120,11 @@ def test_langgraph_write_then_recall_over_real_http(tmp_path: Path, authenticati _wait_until_started(server, thread) model_inputs: list[list[BaseMessage]] = [] graph = _build_graph(model_inputs) - scope = PowerContextScope( - scope_id=SCOPE_ID, - base_url=base_url, - token=AUTH_TOKEN if authentication_enabled else None, - ) - result = asyncio.run( - graph.ainvoke( - {"messages": [HumanMessage(content="What architecture should the payment gateway use?")]}, - context=scope, + _invoke_with_explicit_server_scope( + graph, + base_url=base_url, + token=AUTH_TOKEN if authentication_enabled else None, ) ) @@ -155,6 +151,15 @@ def test_langgraph_write_then_recall_over_real_http(tmp_path: Path, authenticati assert not thread.is_alive() +async def _invoke_with_explicit_server_scope(graph, *, base_url: str, token: str | None): # type: ignore[no-untyped-def] + async with PowerContextClient(base_url, token=token) as client: + scope_id = (await client.resolve_scope_binding(ResolveScopeBindingRequest())).scope_id + return await graph.ainvoke( + {"messages": [HumanMessage(content="What architecture should the payment gateway use?")]}, + context=PowerContextScope(scope_id=scope_id, base_url=base_url, token=token), + ) + + def _wait_until_started(server: uvicorn.Server, thread: threading.Thread) -> None: deadline = time.monotonic() + 10 while thread.is_alive() and not server.started and time.monotonic() < deadline: diff --git a/tests/e2e/test_mcp_transport.py b/tests/e2e/test_mcp_transport.py index 0bf2325f8..44f9e24be 100644 --- a/tests/e2e/test_mcp_transport.py +++ b/tests/e2e/test_mcp_transport.py @@ -77,19 +77,41 @@ async def exercise_tools() -> set[str]: include_inactive = projected_tools["list_memory_entries"].inputSchema["properties"]["include_inactive"] assert include_inactive["type"] == "boolean" assert include_inactive["default"] is False + created_scope = await client.call_tool( + "create_scope", + { + "title": "MCP feature", + "summary": "Scope resource path acceptance", + "idempotency_key": "mcp-feature", + }, + ) + scope = created_scope.structured_content or {} + fetched_scope = await client.call_tool("get_scope", {"scope_id": scope["scope_id"]}) + assert fetched_scope.structured_content == scope + empty_list = await client.call_tool( "list_memory_entries", { - "scope_id": "project:empty", + "scope_id": scope["scope_id"], "include_inactive": True, }, ) assert empty_list.structured_content == {"memory": None, "entries": []} + created_review_scope = await client.call_tool( + "create_scope", + { + "title": "MCP review", + "summary": "Candidate review tool acceptance.", + "idempotency_key": "mcp-review", + }, + ) + review_scope_id = (created_review_scope.structured_content or {})["scope_id"] + captured_response = await http_client.post( "/v1/sources/content", json={ - "scope_id": "project:review", + "scope_id": review_scope_id, "source_id": "task-1", "content": "api-generate and contract-test passed", }, @@ -98,7 +120,7 @@ async def exercise_tools() -> set[str]: candidate_response = await http_client.post( "/v1/experience/propose", json={ - "scope_id": "project:review", + "scope_id": review_scope_id, "proposal": { "situation": "The public OpenAPI contract changes.", "action": "Regenerate the Client and run contract tests.", @@ -115,7 +137,7 @@ async def exercise_tools() -> set[str]: approved = await client.call_tool( "approve_artifact_candidate", { - "scope_id": "project:review", + "scope_id": review_scope_id, "candidate_id": candidate["candidate_id"], "expected_version": candidate["version"], }, @@ -131,26 +153,30 @@ async def exercise_tools() -> set[str]: "activate_handoff", "approve_artifact_candidate", "capture_content_source", + "clear_scope_binding", "commit_handoff", "continue_handoff", + "create_scope", "create_work_contract", "finalize_handoff", "get_artifact_candidate", "get_handoff_report", - "get_handoff_report_workspace", + "get_scope", "get_memory_entry", "handoff_current_work", "list_artifact_candidates", - "list_handoff_report_known_scopes", "list_memory_entries", + "list_scopes", + "publish_artifact", "record_task_outcome", + "resolve_scope_binding", "reject_artifact_candidate", "remember_memory", "retire_memory_entry", "revise_artifact_candidate", "revise_memory_entry", "search_memory", - "select_handoff_workstream", + "set_scope_binding", } @@ -184,10 +210,19 @@ async def exercise_handoff() -> None: httpx_client_factory=create_http_client, ) async with app.router.lifespan_context(app), Client(transport) as client: + created_scope = await client.call_tool( + "create_scope", + { + "title": "MCP Handoff", + "summary": "Source-to-artifact Handoff lifecycle acceptance.", + "idempotency_key": "mcp-handoff", + }, + ) + scope_id = (created_scope.structured_content or {})["scope_id"] captured_result = await client.call_tool( "capture_content_source", { - "scope_id": "project:handoff", + "scope_id": scope_id, "source_id": "turn-1", "content": "MCP must expose the same explicit lifecycle as the SDK.", }, @@ -196,7 +231,7 @@ async def exercise_handoff() -> None: activation_result = await client.call_tool( "activate_handoff", { - "scope_id": "project:handoff", + "scope_id": scope_id, "boundary_source": captured["source"], "objective": "Transfer the MCP integration state.", }, @@ -207,7 +242,7 @@ async def exercise_handoff() -> None: prepared_result = await client.call_tool( "finalize_handoff", { - "scope_id": "project:handoff", + "scope_id": scope_id, "draft": draft, }, ) @@ -215,7 +250,7 @@ async def exercise_handoff() -> None: temporary_result = await client.call_tool( "continue_handoff", { - "scope_id": "project:handoff", + "scope_id": scope_id, "selection": "prepared", "prepared": prepared, }, @@ -223,14 +258,14 @@ async def exercise_handoff() -> None: committed_result = await client.call_tool( "commit_handoff", { - "scope_id": "project:handoff", + "scope_id": scope_id, "handoff": prepared, }, ) latest_result = await client.call_tool( "continue_handoff", { - "scope_id": "project:handoff", + "scope_id": scope_id, "selection": "latest", }, ) diff --git a/tests/e2e/test_observability.py b/tests/e2e/test_observability.py index cc667dc5f..8c26446ba 100644 --- a/tests/e2e/test_observability.py +++ b/tests/e2e/test_observability.py @@ -101,6 +101,7 @@ "powercontext.operation.name", "powercontext.operation.unit", "powercontext.operation.outcome", + "powercontext.context.build.scope_count", "powercontext.context.build.memory_candidate_count", "powercontext.context.build.experience_candidate_count", "powercontext.context.build.selected_count", @@ -242,7 +243,6 @@ def test_observability_signals_correlate_without_counting_the_mcp_bridge(caplog, ), tracing=tracing, ) - scope_id = "project:sensitive-evaluation" def create_http_client( headers: dict[str, str] | None = None, @@ -259,7 +259,7 @@ def create_http_client( follow_redirects=True, ) - async def scenario() -> str: + async def scenario() -> tuple[str, str]: transport = StreamableHttpTransport( "http://testserver/mcp/", httpx_client_factory=create_http_client, @@ -271,14 +271,17 @@ async def scenario() -> str: ): direct = await http_client.get("/v1/capabilities") assert direct.status_code == 200 + default_scope = await http_client.get("/v1/scopes/default") + assert default_scope.status_code == 200 + scope_id = default_scope.json()["scope_id"] await mcp_client.call_tool("list_memory_entries", {"scope_id": scope_id}) - return (await http_client.get("/metrics")).text + return scope_id, (await http_client.get("/metrics")).text correlation_filter = OperationalContextFilter() caplog.handler.addFilter(correlation_filter) try: with caplog.at_level(logging.INFO): - metrics = asyncio.run(scenario()) + scope_id, metrics = asyncio.run(scenario()) finally: caplog.handler.removeFilter(correlation_filter) @@ -332,6 +335,7 @@ def test_database_failure_log_does_not_include_memory_content(caplog, tmp_path) memory_content = "PROBE-SENSITIVE-MEMORY-1318" with TestClient(app, raise_server_exceptions=False) as client: + scope_id = _get_default_scope_id(client) with sqlite3.connect(database_path) as connection: connection.executescript(""" CREATE TRIGGER reject_memory_insert @@ -344,7 +348,7 @@ def test_database_failure_log_does_not_include_memory_content(caplog, tmp_path) with caplog.at_level(logging.ERROR, logger="powercontext.server.app"): response = client.post( "/v1/memory/remember", - json={"scope_id": "project:failure-log", "kind": "fact", "text": memory_content}, + json={"scope_id": scope_id, "kind": "fact", "text": memory_content}, ) records = [ @@ -413,12 +417,22 @@ def test_memory_read_stage_spans_are_bounded_and_nested(monkeypatch, tmp_path) - ), tracing=ServerTracing(provider, instrumented=True), ) - scope_id = "project:private-trace-scope" memory_content = "Private trace sentinel evidence." query = "private trace sentinel" no_match_query = "unmatched giraffe phrase" with TestClient(app) as client: + scope_id = _create_scope(client, title="Memory trace", idempotency_key="memory-trace") + empty_search_scope_id = _create_scope( + client, + title="Empty memory search", + idempotency_key="empty-memory-search", + ) + empty_context_scope_id = _create_scope( + client, + title="Empty context", + idempotency_key="empty-context", + ) remembered = client.post( "/v1/memory/remember", json={"scope_id": scope_id, "kind": "fact", "text": memory_content}, @@ -434,7 +448,7 @@ def test_memory_read_stage_spans_are_bounded_and_nested(monkeypatch, tmp_path) - no_memory = client.post( "/v1/memory/search", json={ - "scope_id": "project:private-empty-search-scope", + "scope_id": empty_search_scope_id, "query": query, "limit": 1, "mode": "fts", @@ -446,7 +460,7 @@ def test_memory_read_stage_spans_are_bounded_and_nested(monkeypatch, tmp_path) - ) empty = client.post( "/v1/context/prepare", - json={"scope_id": "project:private-empty-scope", "query": query}, + json={"scope_id": empty_context_scope_id, "query": query}, ) assert remembered.status_code == 200 @@ -589,8 +603,8 @@ def test_memory_read_stage_spans_are_bounded_and_nested(monkeypatch, tmp_path) - exported = _exported_span_data(spans) assert scope_id not in exported - assert "project:private-empty-scope" not in exported - assert "project:private-empty-search-scope" not in exported + assert empty_context_scope_id not in exported + assert empty_search_scope_id not in exported assert memory_content not in exported assert query not in exported assert no_match_query not in exported @@ -705,10 +719,10 @@ def test_scheduled_source_window_starts_an_independent_trace_root(tmp_path) -> N candidate_pipeline=_EmptyCandidatePipeline(), tracing=ServerTracing(provider), ) - scope_id = "project:private-scheduled-trace" content = "private scheduled evidence" with TestClient(app) as client: + scope_id = _get_default_scope_id(client) captured = client.post( "/v1/sources/content", json={"scope_id": scope_id, "source_id": "task-1", "content": content}, @@ -736,10 +750,10 @@ def test_scheduled_experience_starts_an_independent_trace_root(tmp_path) -> None experience_pipeline=_EmptyExperiencePipeline(), tracing=ServerTracing(provider), ) - scope_id = "project:private-scheduled-experience" content = "private scheduled incubation evidence" with TestClient(app) as client: + scope_id = _get_default_scope_id(client) captured = client.post( "/v1/sources/content", json={"scope_id": scope_id, "source_id": "task-1", "content": content}, @@ -780,11 +794,11 @@ def test_vector_search_exports_embedding_under_memory_search_without_recording_t ), tracing=ServerTracing(provider, instrumented=True), ) - scope_id = "project:private-vector-scope" memory_content = "Private vector memory sentinel." private_text = "private embedding sentinel" with TestClient(app) as client: + scope_id = _get_default_scope_id(client) remembered = client.post( "/v1/memory/remember", json={"scope_id": scope_id, "kind": "fact", "text": memory_content}, @@ -850,14 +864,13 @@ def test_injected_always_on_embedding_skips_readiness_but_traces_vector_search(m embedding_model=embedding_model, tracing=tracing, ) - scope_id = "project:injected-always-on" - with TestClient(app) as client: readiness = client.get("/health/ready") readiness_spans = list(exporter.get_finished_spans()) assert not [span for span in readiness_spans if span.parent is None] assert not any(_is_inference_span(span) for span in readiness_spans) + scope_id = _get_default_scope_id(client) remembered = client.post( "/v1/memory/remember", json={"scope_id": scope_id, "kind": "fact", "text": "Private injected vector memory."}, @@ -893,9 +906,8 @@ def _flush_memory_spans(database_path: Path, *, instrumented: bool) -> list[Read ), tracing=ServerTracing(provider, instrumented=instrumented), ) - scope_id = "project:inference-tracing" - with TestClient(app) as client: + scope_id = _get_default_scope_id(client) captured = client.post( "/v1/sources/content", json={"scope_id": scope_id, "source_id": "task-1", "content": "bounded evidence"}, @@ -907,6 +919,25 @@ def _flush_memory_spans(database_path: Path, *, instrumented: bool) -> list[Read return list(exporter.get_finished_spans()) +def _get_default_scope_id(client: TestClient) -> str: + response = client.get("/v1/scopes/default") + assert response.status_code == 200 + return response.json()["scope_id"] + + +def _create_scope(client: TestClient, *, title: str, idempotency_key: str) -> str: + response = client.post( + "/v1/scopes", + json={ + "title": title, + "summary": "Observability acceptance test scope", + "idempotency_key": idempotency_key, + }, + ) + assert response.status_code == 201 + return response.json()["scope_id"] + + def _is_inference_span(span: ReadableSpan) -> bool: return span.instrumentation_scope is not None and span.instrumentation_scope.name == "pydantic-ai" diff --git a/tests/e2e/test_pydantic_ai_chain.py b/tests/e2e/test_pydantic_ai_chain.py index a5b7b5834..b45fc75c1 100644 --- a/tests/e2e/test_pydantic_ai_chain.py +++ b/tests/e2e/test_pydantic_ai_chain.py @@ -32,7 +32,7 @@ from powercontext.builtin.runtime import InferenceConfig, RuntimeConfig from powercontext.builtin.sources import ContentSource from powercontext.client import PowerContextClient -from powercontext.http import CaptureContentSourceRequest +from powercontext.http import CaptureContentSourceRequest, CreateScopeRequest, ResolveScopeBindingRequest from powercontext.server.factory import create_server_app from powercontext.server.settings import McpConfig, ServerSettings @@ -57,7 +57,6 @@ def test_pydantic_ai_capture_checkpoint_recall_and_search_chain( monkeypatch: pytest.MonkeyPatch, tmp_path: Path, ) -> None: - scope_id = "pydantic-ai-chain" app = create_server_app( settings=ServerSettings( database=SQLiteConfig(url=f"sqlite+aiosqlite:///{tmp_path / 'pydantic-ai.db'}"), @@ -109,6 +108,18 @@ async def scenario() -> str: base_url="http://testserver", ) as transport, ): + scope_client = PowerContextClient( + "http://testserver", + http_client=transport, + trust_transport_security=True, + ) + scope = await scope_client.create_scope( + CreateScopeRequest( + title="Pydantic AI chain", + summary="Explicit Scope for the Pydantic AI capture and recall chain.", + idempotency_key="pydantic-ai-chain", + ) + ) class AsgiPowerContextClient(PowerContextClient): def __init__( @@ -132,7 +143,7 @@ def __init__( output_type=str, deps_type=object, tools=[produce_evidence], - capabilities=[PowerContext[object](settings=settings, scope_id=scope_id)], + capabilities=[PowerContext[object](settings=settings, scope_id=scope.scope_id)], ) return (await agent.run("Find checkpoint-evidence with a tool, then recall and search it.")).output @@ -149,7 +160,6 @@ def test_pydantic_ai_final_flush_catches_up_across_more_than_ten_source_windows( monkeypatch: pytest.MonkeyPatch, tmp_path: Path, ) -> None: - scope_id = "pydantic-ai-deep-backlog" evidence = "deep-backlog-evidence is immediately recallable" app = create_server_app( settings=ServerSettings( @@ -197,6 +207,8 @@ async def scenario() -> str: ) as transport, ): seed_client = PowerContextClient("http://testserver", http_client=transport, trust_transport_security=True) + resolved_scope = await seed_client.resolve_scope_binding(ResolveScopeBindingRequest()) + scope_id = resolved_scope.scope_id for index in range(20): await seed_client.capture_content_source( CaptureContentSourceRequest( @@ -230,7 +242,7 @@ def __init__( output_type=str, deps_type=object, tools=[produce_evidence], - capabilities=[PowerContext[object](settings=capture_settings, scope_id=scope_id)], + capabilities=[PowerContext[object](settings=capture_settings)], ) assert ( await capture_agent.run("Capture deep-backlog-evidence with the tool.") @@ -239,7 +251,7 @@ def __init__( recall_settings = PowerContextSettings(base_url="http://testserver") recall_agent = Agent( FunctionModel(recall_respond), - capabilities=[PowerContext(settings=recall_settings, scope_id=scope_id)], + capabilities=[PowerContext(settings=recall_settings)], ) return (await recall_agent.run("Recall deep-backlog-evidence now.")).output diff --git a/tests/e2e/test_reviewed_generation.py b/tests/e2e/test_reviewed_generation.py index d886a864f..81512229d 100644 --- a/tests/e2e/test_reviewed_generation.py +++ b/tests/e2e/test_reviewed_generation.py @@ -70,16 +70,17 @@ async def scenario() -> None: base_url="http://testserver", ) as transport: client = PowerContextClient("http://testserver", http_client=transport, trust_transport_security=True) + scope_id = (await client.get_default_scope()).scope_id captured = await client.capture_content_source( CaptureContentSourceRequest( - scope_id="project", + scope_id=scope_id, source_id="task-1", content="The contract checks passed.", ) ) generated_experience = await client.generate_experience( GenerateExperienceRequest( - scope_id="project", + scope_id=scope_id, source_refs=[captured.source], artifact_refs=[], ) @@ -88,7 +89,7 @@ async def scenario() -> None: assert generated_experience.candidate is not None approved_experience = await client.approve_artifact_candidate( ApproveArtifactCandidateRequest( - scope_id="project", + scope_id=scope_id, candidate_id=generated_experience.candidate.candidate_id, expected_version=1, ) @@ -97,7 +98,7 @@ async def scenario() -> None: generated_skill = await client.generate_skill( GenerateSkillRequest( - scope_id="project", + scope_id=scope_id, origin=SkillGenerationOrigin.EXPERIENCE, source_refs=[], artifact_refs=[approved_experience.result_artifact], @@ -121,9 +122,10 @@ async def scenario() -> None: base_url="http://testserver", ) as transport: client = PowerContextClient("http://testserver", http_client=transport, trust_transport_security=True) + scope_id = (await client.get_default_scope()).scope_id captured = await client.capture_content_source( CaptureContentSourceRequest( - scope_id="project", + scope_id=scope_id, source_id="task-1", content="Bounded evidence.", ) @@ -131,7 +133,7 @@ async def scenario() -> None: with pytest.raises(ServerResponseError) as unavailable: await client.generate_experience( GenerateExperienceRequest( - scope_id="project", + scope_id=scope_id, source_refs=[captured.source], artifact_refs=[], ) diff --git a/tests/e2e/test_runtime_server.py b/tests/e2e/test_runtime_server.py index 06de49167..d1ef304fd 100644 --- a/tests/e2e/test_runtime_server.py +++ b/tests/e2e/test_runtime_server.py @@ -57,10 +57,13 @@ from powercontext.http import ( AcknowledgeHandoffRequest, ActivateHandoffRequest, + ArtifactAddress, CaptureContentSourceRequest, CommitHandoffRequest, ContinueHandoffRequest, + CreateScopeRequest, CreateWorkContractRequest, + ExactScopeSelection, FinalizeHandoffRequest, FlushMemoryRequest, GetHandoffReportRequest, @@ -71,12 +74,14 @@ ListMemoryChangesRequest, ListMemoryEntriesRequest, PrepareContextRequest, + PublishArtifactRequest, ReadinessStatus, RecordTaskOutcomeRequest, RememberMemoryRequest, ReportFormat, RetireMemoryEntryRequest, ReviseMemoryEntryRequest, + ScopeSelection, SearchMemoryRequest, ) from powercontext.http import MemorySearchMode as HttpMemorySearchMode @@ -168,7 +173,6 @@ def test_server_databases_share_source_to_memory_search_behavior( database = OceanBaseConfig(url=SecretStr(OCEANBASE_URL)) else: database = SQLiteConfig(url=f"sqlite+aiosqlite:///{tmp_path / 'runtime.db'}") - scope_id = f"database-e2e-{uuid4()}" app = create_server_app( settings=ServerSettings( database=database, @@ -188,6 +192,14 @@ async def scenario() -> None: client = PowerContextClient("http://testserver", http_client=transport, trust_transport_security=True) readiness = await client.get_readiness() capabilities = await client.get_capabilities() + scope = await client.create_scope( + CreateScopeRequest( + title="Database acceptance", + summary="Isolated source-to-memory search acceptance.", + idempotency_key=f"database-e2e-{uuid4()}", + ) + ) + scope_id = scope.scope_id captured = await client.capture_content_source( CaptureContentSourceRequest( scope_id=scope_id, @@ -241,10 +253,6 @@ def test_server_databases_keep_case_and_accent_variant_identities_distinct( else: database = SQLiteConfig(url=f"sqlite+aiosqlite:///{tmp_path / 'identity.db'}") marker = uuid4().hex[:12] - writer_scope = f"PC-{marker}-Alpha" - reader_scope = writer_scope.lower() - accent_scope = f"{marker}-café" - plain_scope = f"{marker}-cafe" memory_text = "Rotate the production signing key every ninety days." app = create_server_app( settings=ServerSettings(database=database, mcp=McpConfig(enabled=False)), @@ -259,18 +267,74 @@ async def scenario() -> None: ) as transport, ): client = PowerContextClient("http://testserver", http_client=transport, trust_transport_security=True) - await client.remember_memory(RememberMemoryRequest(scope_id=writer_scope, kind="fact", text=memory_text)) - leaked = await client.list_memory_entries(ListMemoryEntriesRequest(scope_id=reader_scope)) + writer_scope = await client.create_scope( + CreateScopeRequest( + title=f"PC {marker} Alpha", + summary="Writer Scope for case-sensitive isolation acceptance.", + idempotency_key=f"PC-{marker}-Alpha", + ) + ) + reader_scope = await client.create_scope( + CreateScopeRequest( + title=f"pc {marker} alpha", + summary="Reader Scope for case-sensitive isolation acceptance.", + idempotency_key=f"pc-{marker}-alpha", + ) + ) + accent_scope = await client.create_scope( + CreateScopeRequest( + title=f"{marker} café", + summary="Writer Scope for accent-sensitive isolation acceptance.", + idempotency_key=f"{marker}-café", + ) + ) + plain_scope = await client.create_scope( + CreateScopeRequest( + title=f"{marker} cafe", + summary="Reader Scope for accent-sensitive isolation acceptance.", + idempotency_key=f"{marker}-cafe", + ) + ) + source_scope = await client.create_scope( + CreateScopeRequest( + title=f"{marker} source identity", + summary="Source identity case-sensitivity acceptance.", + idempotency_key=f"{marker}-src", + ) + ) + scope_ids = { + writer_scope.scope_id, + reader_scope.scope_id, + accent_scope.scope_id, + plain_scope.scope_id, + source_scope.scope_id, + } + assert len(scope_ids) == 5 await client.remember_memory( - RememberMemoryRequest(scope_id=accent_scope, kind="fact", text="Espresso is on the third floor.") + RememberMemoryRequest(scope_id=writer_scope.scope_id, kind="fact", text=memory_text) ) - accent_leaked = await client.list_memory_entries(ListMemoryEntriesRequest(scope_id=plain_scope)) - source_scope = f"{marker}-src" + leaked = await client.list_memory_entries(ListMemoryEntriesRequest(scope_id=reader_scope.scope_id)) + await client.remember_memory( + RememberMemoryRequest( + scope_id=accent_scope.scope_id, + kind="fact", + text="Espresso is on the third floor.", + ) + ) + accent_leaked = await client.list_memory_entries(ListMemoryEntriesRequest(scope_id=plain_scope.scope_id)) await client.capture_content_source( - CaptureContentSourceRequest(scope_id=source_scope, source_id="Turn-1", content="uppercase turn") + CaptureContentSourceRequest( + scope_id=source_scope.scope_id, + source_id="Turn-1", + content="uppercase turn", + ) ) second = await client.capture_content_source( - CaptureContentSourceRequest(scope_id=source_scope, source_id="turn-1", content="lowercase turn") + CaptureContentSourceRequest( + scope_id=source_scope.scope_id, + source_id="turn-1", + content="lowercase turn", + ) ) assert not leaked.entries @@ -297,9 +361,10 @@ async def scenario() -> None: ): client = PowerContextClient("http://testserver", http_client=transport, trust_transport_security=True) readiness = await client.get_readiness() + scope_id = (await client.get_default_scope()).scope_id captured = await client.capture_content_source( CaptureContentSourceRequest( - scope_id="degraded-readiness", + scope_id=scope_id, source_id="turn-1", content="Database-backed capture remains available.", ) @@ -317,7 +382,6 @@ async def scenario() -> None: def test_sdk_handoff_lifecycle_reaches_generation_and_persistence(tmp_path: Path) -> None: - scope_id = "handoff-e2e" app = create_server_app( settings=_server_settings(tmp_path / "handoff.db"), handoff_pipeline=DeterministicHandoffPipeline(), @@ -332,6 +396,21 @@ async def scenario() -> None: ) as transport, ): client = PowerContextClient("http://testserver", http_client=transport, trust_transport_security=True) + source_scope = await client.create_scope( + CreateScopeRequest( + title="Source work", + summary="Work prepared for an exact Handoff publication.", + idempotency_key="handoff-e2e-source", + ) + ) + target_scope = await client.create_scope( + CreateScopeRequest( + title="Target work", + summary="Work continued from an exact Handoff publication.", + idempotency_key="handoff-e2e-target", + ) + ) + scope_id = source_scope.scope_id capabilities = await client.get_capabilities() captured = await client.capture_content_source( CaptureContentSourceRequest( @@ -387,6 +466,20 @@ async def scenario() -> None: selection=HandoffSelection.LATEST, ) ) + publication = await client.publish_artifact( + PublishArtifactRequest( + source=ArtifactAddress(scope_id=scope_id, artifact=committed.reference), + target_scope_id=target_scope.scope_id, + idempotency_key="handoff-e2e-publication", + ) + ) + published = await client.continue_handoff( + ContinueHandoffRequest( + scope_id=target_scope.scope_id, + selection=HandoffSelection.EXACT, + revision=publication.target.artifact, + ) + ) assert capabilities.artifact_families == ["memory", "experience", "skill", "handoff"] assert capabilities.handoff_generation is True @@ -405,12 +498,15 @@ async def scenario() -> None: assert exact.selected_revision == committed.reference assert latest.selection == "latest" assert latest.selected_revision == committed.reference + assert published.selection == "exact" + assert published.selected_revision == publication.target.artifact + assert published.current_revision == publication.target.artifact + assert published.content == committed.content asyncio.run(scenario()) def test_sdk_closes_the_delegation_handoff_and_outcome_loop(tmp_path: Path) -> None: - scope_id = "work-continuity-e2e" app = create_server_app(settings=_server_settings(tmp_path / "work-continuity.db", handoff_report=True)) async def scenario() -> None: @@ -422,6 +518,16 @@ async def scenario() -> None: ) as transport, ): client = PowerContextClient("http://testserver", http_client=transport, trust_transport_security=True) + scope_response = await transport.post( + "/v1/scopes", + json={ + "title": "Work continuity", + "summary": "Delegation Handoff and outcome loop", + "idempotency_key": "work-continuity-e2e", + }, + ) + scope_response.raise_for_status() + scope_id = scope_response.json()["scope_id"] contract = await client.create_work_contract( CreateWorkContractRequest.model_validate({ "scope_id": scope_id, @@ -534,8 +640,7 @@ async def scenario() -> None: ) report = await client.get_handoff_report( GetHandoffReportRequest( - scope_id=scope_id, - include_evidence_checks=False, + selection=ScopeSelection(root=ExactScopeSelection(mode="exact", scope_ids=[scope_id])), format=ReportFormat.JSON, ) ) @@ -558,17 +663,12 @@ async def scenario() -> None: assert outcome.position == 5 assert not isinstance(report, str) assert report.report is not None - continuity = report.report["workstreams"][0]["continuity"] - assert continuity["coverage"]["transfer_state"] == "accepted" - assert continuity["coverage"]["outcome_state"] == "covered" - assert continuity["coverage"]["handoff_result_covered"] is True - assert [event["kind"] for event in continuity["events"]] == [ - "work-contract", - "handoff-boundary", - "handoff-receipt", - "handoff-receipt", - "task-outcome", - ] + assert report.report["scope_ids"] == [scope_id] + assert report.report["scopes"][0]["handoff"] == { + "scope_id": scope_id, + "artifact": committed.reference.model_dump(mode="json"), + } + assert report.report["scopes"][0]["content"]["objective"] == ("Implement and verify the work-continuity loop.") asyncio.run(scenario()) @@ -584,7 +684,6 @@ def test_server_databases_share_vector_and_hybrid_search_behavior( database = OceanBaseConfig(url=SecretStr(OCEANBASE_URL)) else: database = SQLiteConfig(url=f"sqlite+aiosqlite:///{tmp_path / 'vector-runtime.db'}") - scope_id = f"vector-e2e-{uuid4()}" app = create_server_app( settings=ServerSettings( database=database, @@ -604,6 +703,14 @@ async def scenario() -> None: ): client = PowerContextClient("http://testserver", http_client=transport, trust_transport_security=True) capabilities = await client.get_capabilities() + scope = await client.create_scope( + CreateScopeRequest( + title="Vector search acceptance", + summary="Isolated vector and hybrid search acceptance.", + idempotency_key=f"vector-e2e-{uuid4()}", + ) + ) + scope_id = scope.scope_id await client.capture_content_source( CaptureContentSourceRequest( scope_id=scope_id, @@ -656,9 +763,10 @@ async def scenario() -> None: ) as transport, ): client = PowerContextClient("http://testserver", http_client=transport, trust_transport_security=True) + scope_id = (await client.get_default_scope()).scope_id remembered = await client.remember_memory( RememberMemoryRequest( - scope_id="project:powercontext", + scope_id=scope_id, kind="decision", text="Use strict transport models.", ) @@ -666,13 +774,13 @@ async def scenario() -> None: assert remembered.entry is not None exact = await client.get_memory_entry( GetMemoryEntryRequest( - scope_id="project:powercontext", + scope_id=scope_id, citation=remembered.entry.citation, ) ) revised = await client.revise_memory_entry( ReviseMemoryEntryRequest( - scope_id="project:powercontext", + scope_id=scope_id, citation=remembered.entry.citation, kind="decision", text="Keep strict Pydantic transport models.", @@ -681,43 +789,43 @@ async def scenario() -> None: assert revised.entry is not None changes = await client.list_memory_changes( ListMemoryChangesRequest( - scope_id="project:powercontext", + scope_id=scope_id, since_revision=remembered.memory.revision, ) ) retired = await client.retire_memory_entry( RetireMemoryEntryRequest( - scope_id="project:powercontext", + scope_id=scope_id, citation=revised.entry.citation, reason="superseded", ) ) assert retired.entry is not None current = await client.list_memory_entries( - ListMemoryEntriesRequest(scope_id="project:powercontext"), + ListMemoryEntriesRequest(scope_id=scope_id), ) audited = await client.list_memory_entries( ListMemoryEntriesRequest( - scope_id="project:powercontext", + scope_id=scope_id, include_inactive=True, ), ) retired_search = await client.search_memory( SearchMemoryRequest( - scope_id="project:powercontext", + scope_id=scope_id, query="strict Pydantic transport models", ), ) retired_exact = await client.get_memory_entry( GetMemoryEntryRequest( - scope_id="project:powercontext", + scope_id=scope_id, citation=retired.entry.citation, ), ) with pytest.raises(ServerResponseError) as inactive: await client.revise_memory_entry( ReviseMemoryEntryRequest( - scope_id="project:powercontext", + scope_id=scope_id, citation=retired.entry.citation, kind="decision", text="Inactive entries cannot be revised.", @@ -726,7 +834,7 @@ async def scenario() -> None: with pytest.raises(ServerResponseError) as missing: await client.get_memory_entry( GetMemoryEntryRequest( - scope_id="project:powercontext", + scope_id=scope_id, citation=retired.entry.citation.model_copy(update={"entry_id": "missing-entry"}), ) ) @@ -752,13 +860,16 @@ def test_runtime_conflicts_keep_http_and_sdk_error_context(tmp_path: Path) -> No app = create_server_app(settings=_server_settings(tmp_path / "runtime.db")) with TestClient(app) as transport: + default_scope = transport.get("/v1/scopes/default") + default_scope.raise_for_status() + scope_id = default_scope.json()["scope_id"] first = transport.post( "/v1/sources/content", - json={"scope_id": "project", "source_id": "turn-1", "content": "first"}, + json={"scope_id": scope_id, "source_id": "turn-1", "content": "first"}, ) conflict = transport.post( "/v1/sources/content", - json={"scope_id": "project", "source_id": "turn-1", "content": "changed"}, + json={"scope_id": scope_id, "source_id": "turn-1", "content": "changed"}, ) assert first.status_code == 202 @@ -777,12 +888,12 @@ async def stale_revision() -> None: ): client = PowerContextClient("http://testserver", http_client=transport, trust_transport_security=True) remembered = await client.remember_memory( - RememberMemoryRequest(scope_id="project", kind="decision", text="first") + RememberMemoryRequest(scope_id=scope_id, kind="decision", text="first") ) with pytest.raises(ServerResponseError) as caught: await client.remember_memory( RememberMemoryRequest( - scope_id="project", + scope_id=scope_id, kind="decision", text="stale", expected_revision=remembered.memory.revision + 1, @@ -810,9 +921,12 @@ async def conflicting_search( app = create_server_app(settings=_server_settings(tmp_path / "runtime.db")) with TestClient(app) as transport: + default_scope = transport.get("/v1/scopes/default") + default_scope.raise_for_status() + scope_id = default_scope.json()["scope_id"] response = transport.post( "/v1/memory/search", - json={"scope_id": "project", "query": "stable searchable"}, + json={"scope_id": scope_id, "query": "stable searchable"}, ) assert response.status_code == 409 @@ -829,10 +943,13 @@ def test_runtime_server_rejects_non_strict_transport_values(tmp_path: Path) -> N app = create_server_app(settings=_server_settings(tmp_path / "runtime.db")) with TestClient(app) as transport: + default_scope = transport.get("/v1/scopes/default") + default_scope.raise_for_status() + scope_id = default_scope.json()["scope_id"] responses = [ transport.post( "/v1/memory/search", - json={"scope_id": "project", "query": "query", "limit": True}, + json={"scope_id": scope_id, "query": "query", "limit": True}, ), transport.post( "/v1/memory/search", @@ -840,7 +957,7 @@ def test_runtime_server_rejects_non_strict_transport_values(tmp_path: Path) -> N ), transport.post( "/v1/memory/remember", - json={"scope_id": "project", "kind": "decision", "text": "🧠" * 3_000}, + json={"scope_id": scope_id, "kind": "decision", "text": "🧠" * 3_000}, ), ] diff --git a/tests/e2e/test_scheduled_experience_incubation.py b/tests/e2e/test_scheduled_experience_incubation.py index 9e7cff2ff..6014222d7 100644 --- a/tests/e2e/test_scheduled_experience_incubation.py +++ b/tests/e2e/test_scheduled_experience_incubation.py @@ -84,7 +84,6 @@ def test_scheduler_incubates_task_outcome_once_and_preserves_review_gating(tmp_p async def scenario() -> None: database = tmp_path / "powercontext.db" scheduler = tmp_path / "scheduler.db" - scope_id = "scheduled-experience-e2e" app = _app(database, scheduler) async with ( app.router.lifespan_context(app), @@ -94,6 +93,7 @@ async def scenario() -> None: ) as transport, ): client = PowerContextClient("http://testserver", http_client=transport, trust_transport_security=True) + scope_id = (await client.get_default_scope()).scope_id captured = await client.capture_content_source( CaptureContentSourceRequest( scope_id=scope_id, diff --git a/tests/e2e/test_statistics_flow.py b/tests/e2e/test_statistics_flow.py index d3b516549..c8c8d891e 100644 --- a/tests/e2e/test_statistics_flow.py +++ b/tests/e2e/test_statistics_flow.py @@ -98,6 +98,13 @@ def _client(app) -> tuple[httpx.AsyncClient, PowerContextClient]: ) +def _stats_request(scope_id: str, period: StatsPeriod) -> GetStatsRequest: + return GetStatsRequest.model_validate({ + "selection": {"mode": "exact", "scope_ids": [scope_id]}, + "period": period, + }) + + @pytest.mark.parametrize("database_kind", ["sqlite", "oceanbase"]) def test_statistics_survive_the_authenticated_http_business_flow_and_restart( database_kind: str, @@ -125,9 +132,17 @@ def test_statistics_survive_the_authenticated_http_business_flow_and_restart( first_app = create_server_app(settings=settings) async def scenario() -> None: + nonlocal scope_id async with first_app.router.lifespan_context(first_app): transport, client = _client(first_app) async with transport: + created_scope = await transport.post( + "/v1/scopes", + json={"title": "Statistics", "summary": "Statistics flow", "idempotency_key": scope_id}, + headers={"Authorization": f"Bearer {_AUTH_TOKEN}"}, + ) + assert created_scope.status_code == 201 + scope_id = created_scope.json()["scope_id"] source = await client.capture_content_source( CaptureContentSourceRequest( scope_id=scope_id, @@ -201,12 +216,15 @@ async def scenario() -> None: empty = await client.prepare_context( PrepareContextRequest(scope_id=scope_id, query="unrelated-zebra-phrase") ) - first = await client.get_stats(GetStatsRequest(scope_id=scope_id, period=StatsPeriod.TODAY)) + first = await client.get_stats(_stats_request(scope_id, StatsPeriod.TODAY)) - unauthorized = await transport.get("/v1/stats", params={"scope_id": scope_id}) - raw = await transport.get( + unauthorized = await transport.post( + "/v1/stats", + json={"selection": {"mode": "exact", "scope_ids": [scope_id]}}, + ) + raw = await transport.post( "/v1/stats", - params={"scope_id": scope_id, "period": "today"}, + json={"selection": {"mode": "exact", "scope_ids": [scope_id]}, "period": "today"}, headers={"Authorization": f"Bearer {_AUTH_TOKEN}"}, ) @@ -233,11 +251,11 @@ async def scenario() -> None: async with second_app.router.lifespan_context(second_app): transport, client = _client(second_app) async with transport: - restored = await client.get_stats(GetStatsRequest(scope_id=scope_id, period=StatsPeriod.FIELD_7D)) + restored = await client.get_stats(_stats_request(scope_id, StatsPeriod.FIELD_7D)) prepared_again = await client.prepare_context( PrepareContextRequest(scope_id=scope_id, query="statistics contract") ) - updated = await client.get_stats(GetStatsRequest(scope_id=scope_id, period=StatsPeriod.FIELD_7D)) + updated = await client.get_stats(_stats_request(scope_id, StatsPeriod.FIELD_7D)) assert restored.inventory == first.inventory assert restored.usage.totals == first.usage.totals diff --git a/tests/e2e/test_workbuddy_service_chain.py b/tests/e2e/test_workbuddy_service_chain.py index efe315210..5270482b2 100644 --- a/tests/e2e/test_workbuddy_service_chain.py +++ b/tests/e2e/test_workbuddy_service_chain.py @@ -29,6 +29,7 @@ import uvicorn from fastmcp import Client from fastmcp.client.transports import StreamableHttpTransport +from httpx import Client as HttpClient from pydantic import SecretStr from pydantic_ai.models.test import TestModel @@ -40,7 +41,6 @@ PROJECT_ROOT = Path(__file__).resolve().parents[2] WORKBUDDY_PLUGIN = PROJECT_ROOT / "integrations" / "workbuddy" / "plugins" / "powercontext" -SCOPE_ID = "project:workbuddy-e2e" AUTH_TOKEN = "workbuddy-e2e-token" # noqa: S105 - non-secret test credential. AUTHORIZATION = f"Bearer {AUTH_TOKEN}" _SERVER_URL_TEMPLATE = "${POWERCONTEXT_WORKBUDDY_SERVER_URL:-http://127.0.0.1:8000}/mcp" @@ -98,6 +98,7 @@ def test_workbuddy_hook_and_mcp_share_one_service_configuration( command = _powercontext_hook_command(settings) authorization = AUTHORIZATION if authentication_enabled else None environment = _workbuddy_environment(base_url, authorization=authorization) + scope_id = _resolve_default_scope(base_url, authorization=authorization) captured = _run_hook( command, @@ -132,7 +133,7 @@ async def verify_mcp() -> None: result = await client.call_tool( "search_memory", { - "scope_id": SCOPE_ID, + "scope_id": scope_id, "query": "WorkBuddy service chain", }, ) @@ -172,7 +173,6 @@ def _workbuddy_environment(base_url: str, *, authorization: str | None) -> dict[ "POWERCONTEXT_WORKBUDDY_FLUSH_ON_CAPTURE": "true", "POWERCONTEXT_WORKBUDDY_HTTP_BUDGET_SECONDS": "10", "POWERCONTEXT_WORKBUDDY_REQUEST_TIMEOUT_SECONDS": "5", - "POWERCONTEXT_WORKBUDDY_SCOPE_ID": SCOPE_ID, "POWERCONTEXT_WORKBUDDY_SERVER_URL": base_url, } environment.pop("POWERCONTEXT_WORKBUDDY_AUTHORIZATION", None) @@ -181,6 +181,19 @@ def _workbuddy_environment(base_url: str, *, authorization: str | None) -> dict[ return environment +def _resolve_default_scope(base_url: str, *, authorization: str | None) -> str: + headers = {} if authorization is None else {"Authorization": authorization} + with HttpClient(base_url=base_url, headers=headers) as client: + response = client.post( + "/v1/scope-bindings/resolve", + json={"binding_keys": []}, + ) + response.raise_for_status() + scope_id = response.json()["scope_id"] + assert isinstance(scope_id, str) + return scope_id + + def _run_hook( command: list[str], *, diff --git a/tests/integrations/test_hermes_provider.py b/tests/integrations/test_hermes_provider.py index b309a1301..ad00ce5d6 100644 --- a/tests/integrations/test_hermes_provider.py +++ b/tests/integrations/test_hermes_provider.py @@ -33,7 +33,6 @@ "plugins.powercontext.provider", "plugins.powercontext.commands", "plugins.powercontext.trace", - "plugins.powercontext.workstream", "plugins.powercontext.operations", "plugins.powercontext.helpers", "plugins.powercontext.client", @@ -65,6 +64,31 @@ def __init__(self) -> None: self._revision = 0 self._memory_entries: dict[str, dict[str, Any]] = {} self.memory_extraction = True + self.default_scope_id = "scp_00000000000000000000000000" + self.scope_bindings: dict[tuple[str, str, str], str] = {} + self.resolved_binding_keys: list[dict[str, str]] = [] + + def resolve_scope_binding(self, *, explicit_scope_id, binding_keys): + self.resolved_binding_keys = binding_keys + if explicit_scope_id: + return {"scope_id": explicit_scope_id} + for key in binding_keys: + identity = (key["integration"], key["kind"], key["external_id"]) + if identity in self.scope_bindings: + return {"scope_id": self.scope_bindings[identity]} + return {"scope_id": self.default_scope_id} + + def set_scope_binding(self, key, scope_id): + identity = (key["integration"], key["kind"], key["external_id"]) + self.scope_bindings[identity] = scope_id + self.calls.append(("set_scope_binding", (key, scope_id), {})) + return {"key": key, "scope_id": scope_id} + + def clear_scope_binding(self, key): + identity = (key["integration"], key["kind"], key["external_id"]) + cleared = self.scope_bindings.pop(identity, None) is not None + self.calls.append(("clear_scope_binding", (key,), {})) + return {"cleared": cleared} def prepare_context(self, scope_id, query, *, max_bytes): self.calls.append(("prepare_context", (scope_id, query), {"max_bytes": max_bytes})) @@ -145,7 +169,7 @@ def provider_and_client(tmp_path, hermes_modules): provider_module, _cli_module = hermes_modules client = FakeClient() provider = provider_module.PowerContextMemoryProvider( - {"scope_id": "hermes:{profile}:{user_id}"}, + {}, client_factory=lambda _config: client, ) provider.initialize("session-1", hermes_home=str(tmp_path), agent_identity="coder", user_id="user-7") @@ -161,7 +185,7 @@ def test_prefetch_uses_profile_and_user_scoped_context(provider_and_client): assert "remembered project context" in recalled assert client.calls[0] == ( "prepare_context", - ("hermes:coder:user-7", "What did we decide about the deployment?"), + ("scp_00000000000000000000000000", "What did we decide about the deployment?"), {"max_bytes": 8000}, ) @@ -392,7 +416,7 @@ def test_queue_prefetch_honors_max_bytes_environment_override(provider_and_clien assert client.calls[0] == ( "prepare_context", - ("hermes:coder:user-7", "What did we decide about the deployment?"), + ("scp_00000000000000000000000000", "What did we decide about the deployment?"), {"max_bytes": 16000}, ) @@ -431,7 +455,6 @@ def test_json_config_is_loaded_from_hermes_home(tmp_path, hermes_modules): config_path.write_text( json.dumps({ "base_url": "http://powercontext.test:9000", - "scope_id": "hermes:{profile}:{user_id}", "max_bytes": 1200, "capture_turns": False, }), @@ -444,7 +467,7 @@ def test_json_config_is_loaded_from_hermes_home(tmp_path, hermes_modules): assert provider._config["base_url"] == "http://powercontext.test:9000" assert provider._config["max_bytes"] == 1200 assert provider._config["capture_turns"] is False - assert provider._scope_id == "hermes:coder:user-7" + assert provider._scope_id == "scp_00000000000000000000000000" provider.shutdown() @@ -461,7 +484,8 @@ def test_memory_setup_schema_exposes_powercontext_configuration(hermes_modules): assert fields["capture_pre_compress"]["choices"] == ["true", "false"] assert "capture_turns" in fields assert "flush_on_session_end" in fields - assert fields["workstream_persistence"]["default"] == "true" + assert fields["scope_id"]["default"] == "" + assert "scope_binding" not in fields def test_memory_setup_saves_powercontext_json_and_preserves_existing_values(tmp_path, hermes_modules): @@ -495,7 +519,7 @@ def test_sync_turn_is_flushed_before_session_end(provider_and_client): names = [call[0] for call in client.calls] assert names == ["capture_content", "get_capabilities", "flush_memory"] - assert client.calls[0][1][0] == "hermes:coder:user-7" + assert client.calls[0][1][0] == "scp_00000000000000000000000000" assert client.calls[0][2]["metadata"]["kind"] == "hermes-turn" @@ -776,13 +800,13 @@ def test_extended_tools_are_registered_and_scope_bound(provider_and_client): assert result["operation"] == "list_memory_entries" assert result["payload"] == { "include_inactive": True, - "scope_id": "hermes:coder:user-7", + "scope_id": "scp_00000000000000000000000000", } assert client.calls[-1] == ( "request_operation", ( "list_memory_entries", - {"include_inactive": True, "scope_id": "hermes:coder:user-7"}, + {"include_inactive": True, "scope_id": "scp_00000000000000000000000000"}, ), {}, ) @@ -800,11 +824,11 @@ def test_extended_slash_commands_dispatch_json_operations(provider_and_client): help_text = provider.handle_slash_command("help") assert result["operation"] == "prepare_handoff" - assert result["payload"]["scope_id"] == "hermes:coder:user-7" + assert result["payload"]["scope_id"] == "scp_00000000000000000000000000" assert result["payload"]["objective"] == "finish integration" assert stats["operation"] == "get_stats" - assert stats["payload"] == {"period": "7d", "scope_id": "hermes:coder:user-7"} - assert "/pc workstream" in help_text + assert stats["payload"] == {"period": "7d", "scope_id": "scp_00000000000000000000000000"} + assert "/pc scope" in help_text assert [call[0] for call in client.calls] == ["request_operation", "request_operation"] @@ -846,23 +870,12 @@ def test_slash_commands_parse_unwrapped_citation_json_from_readme(provider_and_c ] -def test_workstream_binding_is_shared_with_hermes_scope(tmp_path, hermes_modules, monkeypatch): +def test_scope_resolution_uses_session_workspace_and_server_default(tmp_path, hermes_modules): provider_module, _cli_module = hermes_modules - git_directory = tmp_path / ".git" - state_path = git_directory / "powercontext" / "codex-workspace.json" - state_path.parent.mkdir(parents=True) - state_path.write_text( - json.dumps({ - "schema": "powercontext.codex-workspace.v1", - "scope_id": "git:example/project", - }), - encoding="utf-8", - ) - workstream_module = importlib.import_module("plugins.powercontext.workstream") - monkeypatch.setattr(workstream_module, "git_value", lambda _cwd, *_args: str(git_directory)) + client = FakeClient() provider = provider_module.PowerContextMemoryProvider( - {"scope_id": "hermes:{profile}:{user_id}"}, - client_factory=lambda _config: FakeClient(), + {}, + client_factory=lambda _config: client, ) provider.initialize( "session-1", @@ -872,21 +885,33 @@ def test_workstream_binding_is_shared_with_hermes_scope(tmp_path, hermes_modules user_id="user-7", ) - status = json.loads(provider.handle_slash_command("workstream status")) - assert status["bound_scope_id"] == "git:example/project" + status = json.loads(provider.handle_slash_command("scope status")) + assert status["active_scope_id"] == client.default_scope_id + assert [key["kind"] for key in client.resolved_binding_keys] == ["session", "workspace"] + assert all(key["integration"] == "hermes" for key in client.resolved_binding_keys) + provider.shutdown() + + +def test_explicit_scope_precedes_server_bindings(tmp_path, hermes_modules): + provider_module, _cli_module = hermes_modules + client = FakeClient() + provider = provider_module.PowerContextMemoryProvider( + {"scope_id": "scp_explicit"}, + client_factory=lambda _config: client, + ) + + provider.initialize("session-1", hermes_home=str(tmp_path), cwd=str(tmp_path)) + + assert provider._scope_id == "scp_explicit" provider.shutdown() -def test_workstream_clear_restores_default_scope(tmp_path, hermes_modules, monkeypatch): +def test_scope_binding_clear_restores_default_scope(tmp_path, hermes_modules): provider_module, _cli_module = hermes_modules - git_directory = tmp_path / ".git" - git_directory.mkdir() - workstream_module = importlib.import_module("plugins.powercontext.workstream") - monkeypatch.setattr(workstream_module, "git_value", lambda _cwd, *_args: str(git_directory)) client = FakeClient() provider = provider_module.PowerContextMemoryProvider( - {"scope_id": "hermes:{profile}:{user_id}"}, + {}, client_factory=lambda _config: client, ) provider.initialize( @@ -899,13 +924,13 @@ def test_workstream_clear_restores_default_scope(tmp_path, hermes_modules, monke default_scope_id = provider._scope_id try: - bound = json.loads(provider.handle_slash_command("workstream bind shared:scope")) + bound = json.loads(provider.handle_slash_command("scope bind shared:scope")) assert bound["scope_id"] == "shared:scope" - cleared = json.loads(provider.handle_slash_command("workstream clear")) + cleared = json.loads(provider.handle_slash_command("scope clear")) assert cleared["status"] == "cleared" - status = json.loads(provider.handle_slash_command("workstream status")) + status = json.loads(provider.handle_slash_command("scope status")) assert status["bound_scope_id"] is None assert status["active_scope_id"] == default_scope_id @@ -916,16 +941,12 @@ def test_workstream_clear_restores_default_scope(tmp_path, hermes_modules, monke provider.shutdown() -def test_workstream_bind_isolates_queued_background_work(tmp_path, hermes_modules, monkeypatch): +def test_scope_binding_isolates_queued_background_work(tmp_path, hermes_modules, monkeypatch): provider_module, _cli_module = hermes_modules - git_directory = tmp_path / ".git" - git_directory.mkdir() - workstream_module = importlib.import_module("plugins.powercontext.workstream") - monkeypatch.setattr(workstream_module, "git_value", lambda _cwd, *_args: str(git_directory)) client = FakeClient() provider = provider_module.PowerContextMemoryProvider( - {"scope_id": "hermes:{profile}:{user_id}", "shutdown_timeout": 0.01}, + {"shutdown_timeout": 0.01}, client_factory=lambda _config: client, ) provider.initialize( @@ -937,7 +958,7 @@ def test_workstream_bind_isolates_queued_background_work(tmp_path, hermes_module ) release = threading.Event() started = threading.Event() - old_scope_id = "hermes:coder:user-7" + old_scope_id = "scp_00000000000000000000000000" def blocked_prepare(*args: Any, **kwargs: Any) -> dict[str, Any]: scope_id = args[0] @@ -953,7 +974,7 @@ def blocked_prepare(*args: Any, **kwargs: Any) -> dict[str, Any]: assert started.wait(timeout=1) provider.sync_turn("old user", "old assistant") - result = json.loads(provider.handle_slash_command("workstream bind new:scope")) + result = json.loads(provider.handle_slash_command("scope bind new:scope")) assert result["status"] == "bound" release.set() diff --git a/tests/langchain_middleware/test_middleware.py b/tests/langchain_middleware/test_middleware.py index aade92392..115d48b61 100644 --- a/tests/langchain_middleware/test_middleware.py +++ b/tests/langchain_middleware/test_middleware.py @@ -48,6 +48,7 @@ ListMemoryEntriesRequest, ProposeExperienceRequest, RememberMemoryRequest, + ResolveScopeBindingRequest, ) from powercontext.server.factory import create_server_app from powercontext.server.settings import McpConfig, ServerSettings @@ -139,6 +140,10 @@ def _system_texts(messages: list[BaseMessage]) -> list[str]: return [message.text for message in messages if message.type == "system"] +async def _default_scope_id(client: PowerContextClient) -> str: + return (await client.resolve_scope_binding(ResolveScopeBindingRequest())).scope_id + + def test_middleware_injects_recall_without_persisting_it(tmp_path: Path) -> None: model = _RecordingModel() agent = create_agent( @@ -150,11 +155,12 @@ def test_middleware_injects_recall_without_persisting_it(tmp_path: Path) -> None app = _server_app(tmp_path) async def scenario(client: PowerContextClient) -> None: - await client.remember_memory(RememberMemoryRequest(scope_id=SCOPE, kind="decision", text=MEMORY_TEXT)) + scope_id = await _default_scope_id(client) + await client.remember_memory(RememberMemoryRequest(scope_id=scope_id, kind="decision", text=MEMORY_TEXT)) result = await agent.ainvoke( {"messages": [HumanMessage(content="How should we deploy the application and its migrations?")]}, - context=PowerContextScope(scope_id=SCOPE), + context=PowerContextScope(scope_id=scope_id), ) system_texts = _system_texts(model.inputs[-1]) @@ -178,16 +184,17 @@ def test_middleware_injects_only_approved_experience(tmp_path: Path) -> None: query = f"What deployment order does {EXPERIENCE_MARKER} require?" async def scenario(client: PowerContextClient) -> None: + scope_id = await _default_scope_id(client) source = await client.capture_content_source( CaptureContentSourceRequest( - scope_id=SCOPE, + scope_id=scope_id, source_id="approved-experience-evidence", content="The migration-first deployment completed without schema errors.", ) ) candidate = await client.propose_experience( ProposeExperienceRequest( - scope_id=SCOPE, + scope_id=scope_id, proposal=ExperienceProposal( situation=f"A {EXPERIENCE_MARKER} deployment includes schema changes.", action="Apply database migrations before deploying the application.", @@ -198,7 +205,7 @@ async def scenario(client: PowerContextClient) -> None: artifact_refs=[], ) ) - scope = PowerContextScope(scope_id=SCOPE) + scope = PowerContextScope(scope_id=scope_id) pending_result = await agent.ainvoke({"messages": [HumanMessage(content=query)]}, context=scope) @@ -207,7 +214,7 @@ async def scenario(client: PowerContextClient) -> None: await client.approve_artifact_candidate( ApproveArtifactCandidateRequest( - scope_id=SCOPE, + scope_id=scope_id, candidate_id=candidate.candidate_id, expected_version=candidate.version, ) @@ -237,13 +244,14 @@ def test_middleware_does_not_capture_completed_turn_by_default(tmp_path: Path) - app = _server_app(tmp_path) async def scenario(client: PowerContextClient) -> None: + scope_id = await _default_scope_id(client) await agent.ainvoke( {"messages": [HumanMessage(content="Use api_key=sk-probe-default-capture-disabled.")]}, - context=PowerContextScope(scope_id=SCOPE), + context=PowerContextScope(), ) - flushed = await client.flush_memory(FlushMemoryRequest(scope_id=SCOPE)) - entries = await client.list_memory_entries(ListMemoryEntriesRequest(scope_id=SCOPE)) + flushed = await client.flush_memory(FlushMemoryRequest(scope_id=scope_id)) + entries = await client.list_memory_entries(ListMemoryEntriesRequest(scope_id=scope_id)) assert flushed.memory is None assert entries.entries == [] @@ -263,13 +271,14 @@ def test_middleware_captures_completed_turn_when_enabled(tmp_path: Path) -> None user_text = "What is the safe deployment order?" async def scenario(client: PowerContextClient) -> None: + scope_id = await _default_scope_id(client) await agent.ainvoke( {"messages": [HumanMessage(content=user_text)]}, - context=PowerContextScope(scope_id=SCOPE), + context=PowerContextScope(scope_id=scope_id), ) - flushed = await client.flush_memory(FlushMemoryRequest(scope_id=SCOPE)) - entries = await client.list_memory_entries(ListMemoryEntriesRequest(scope_id=SCOPE)) + flushed = await client.flush_memory(FlushMemoryRequest(scope_id=scope_id)) + entries = await client.list_memory_entries(ListMemoryEntriesRequest(scope_id=scope_id)) assert flushed.memory is not None assert len(entries.entries) == 1 @@ -295,13 +304,14 @@ def test_middleware_captures_tool_strategy_structured_response(tmp_path: Path) - user_text = "Return the deployment plan." async def scenario(client: PowerContextClient) -> None: + scope_id = await _default_scope_id(client) result = await agent.ainvoke( {"messages": [HumanMessage(content=user_text)]}, - context=PowerContextScope(scope_id=SCOPE), + context=PowerContextScope(scope_id=scope_id), ) - flushed = await client.flush_memory(FlushMemoryRequest(scope_id=SCOPE)) - entries = await client.list_memory_entries(ListMemoryEntriesRequest(scope_id=SCOPE)) + flushed = await client.flush_memory(FlushMemoryRequest(scope_id=scope_id)) + entries = await client.list_memory_entries(ListMemoryEntriesRequest(scope_id=scope_id)) assert result["structured_response"] == _DeploymentPlan(order=STRUCTURED_ORDER) assert flushed.memory is not None diff --git a/tests/langchain_middleware/test_scope.py b/tests/langchain_middleware/test_scope.py deleted file mode 100644 index 68c2a47a8..000000000 --- a/tests/langchain_middleware/test_scope.py +++ /dev/null @@ -1,46 +0,0 @@ -# Copyright (c) 2026 OceanBase. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -"""Scope resolution tests for the standalone LangChain package.""" - -import pytest -from powercontext_langchain import MissingScopeError, resolve_scope_id -from powercontext_langchain.scope import normalize_git_remote - - -def test_missing_scope_names_langchain_configuration(monkeypatch: pytest.MonkeyPatch) -> None: - monkeypatch.setattr("powercontext_langchain.scope._git_remote", lambda _cwd: None) - - with pytest.raises(MissingScopeError, match="POWERCONTEXT_LANGCHAIN_SCOPE_ID"): - resolve_scope_id(None, cwd="/irrelevant") - - -@pytest.mark.parametrize( - ("remote", "expected"), - [ - ("git@github.com:acme/api.git", "github.com/acme/api"), - ("https://credential@github.com/acme/api.git", "github.com/acme/api"), - ("ssh://git@example.com:2222/acme/api.git", "example.com:2222/acme/api"), - ], -) -def test_normalize_git_remote_removes_credentials(remote: str, expected: str) -> None: - assert normalize_git_remote(remote) == expected - - -@pytest.mark.parametrize("remote", [r"C:\work\tenant-repo.git", "C:/work/tenant-repo.git"]) -def test_resolve_scope_id_rejects_windows_local_remote(monkeypatch: pytest.MonkeyPatch, remote: str) -> None: - monkeypatch.setattr("powercontext_langchain.scope._git_remote", lambda _cwd: remote) - - with pytest.raises(MissingScopeError): - resolve_scope_id(None, cwd="/irrelevant") diff --git a/tests/langgraph_adapter/test_recall.py b/tests/langgraph_adapter/test_recall.py index 31b1b73f4..a9a1379ca 100644 --- a/tests/langgraph_adapter/test_recall.py +++ b/tests/langgraph_adapter/test_recall.py @@ -38,16 +38,15 @@ from powercontext.builtin.persistence.sqlite import SQLiteConfig from powercontext.builtin.runtime import InferenceConfig from powercontext.client import PowerContextClient -from powercontext.http import RememberMemoryRequest +from powercontext.http import CreateScopeRequest, RememberMemoryRequest, ResolveScopeBindingRequest from powercontext.server.factory import create_server_app from powercontext.server.settings import McpConfig, ServerSettings pytest.importorskip("powercontext_langgraph") -from powercontext_langgraph import MissingScopeError, PowerContextRecall, PowerContextScope +from powercontext_langgraph import PowerContextRecall, PowerContextScope UNTRUSTED_LABEL = "untrusted historical evidence" -SCOPE = "project:langgraph-adapter-test" DEPLOY_MEMORY = "Deploy database migrations before rollout." @@ -112,9 +111,18 @@ def _system_positions(messages: list[BaseMessage]) -> list[int]: return [index for index, message in enumerate(messages) if getattr(message, "type", None) == "system"] -async def _seed(client: PowerContextClient) -> None: +async def _default_scope_id(client: PowerContextClient) -> str: + return (await client.resolve_scope_binding(ResolveScopeBindingRequest())).scope_id + + +async def _seed(client: PowerContextClient, scope_id: str) -> None: await client.remember_memory( - RememberMemoryRequest(scope_id=SCOPE, kind="decision", text=DEPLOY_MEMORY, reason="seeded for the recall test") + RememberMemoryRequest( + scope_id=scope_id, + kind="decision", + text=DEPLOY_MEMORY, + reason="seeded for the recall test", + ) ) @@ -126,7 +134,7 @@ def test_recall_supplies_no_prefix_when_context_is_empty(tmp_path: Path) -> None async def scenario(_: PowerContextClient) -> None: await agent.ainvoke( {"messages": [HumanMessage(content="How do we deploy the database?")]}, - context=PowerContextScope(scope_id=SCOPE), + context=PowerContextScope(), ) assert model.inputs, "the model was invoked" assert _system_texts(model.inputs[-1]) == [] @@ -140,10 +148,10 @@ def test_recall_injects_context_labelled_untrusted(tmp_path: Path) -> None: app = _server_app(tmp_path) async def scenario(client: PowerContextClient) -> None: - await _seed(client) + await _seed(client, await _default_scope_id(client)) result = await agent.ainvoke( {"messages": [HumanMessage(content="How do we deploy the database migrations?")]}, - context=PowerContextScope(scope_id=SCOPE), + context=PowerContextScope(), ) model_input = model.inputs[-1] system_texts = _system_texts(model_input) @@ -166,16 +174,16 @@ def test_recall_does_not_accumulate_across_turns(tmp_path: Path) -> None: app = _server_app(tmp_path) async def scenario(client: PowerContextClient) -> None: - await _seed(client) + await _seed(client, await _default_scope_id(client)) config = {"configurable": {"thread_id": "regression"}} await agent.ainvoke( {"messages": [HumanMessage(content="How do we deploy the database migrations?")]}, - context=PowerContextScope(scope_id=SCOPE), + context=PowerContextScope(), config=config, ) result = await agent.ainvoke( {"messages": [HumanMessage(content="And what should we double-check about the migrations first?")]}, - context=PowerContextScope(scope_id=SCOPE), + context=PowerContextScope(), config=config, ) @@ -206,10 +214,10 @@ def test_recall_completes_graph_for_over_limit_prompt(tmp_path: Path) -> None: assert len(long_prompt) > 8192 async def scenario(client: PowerContextClient) -> None: - await _seed(client) + await _seed(client, await _default_scope_id(client)) result = await agent.ainvoke( {"messages": [HumanMessage(content=long_prompt)]}, - context=PowerContextScope(scope_id=SCOPE), + context=PowerContextScope(), ) # The graph completed: the model ran and produced an answer despite the over-limit prompt. assert model.inputs @@ -226,8 +234,6 @@ def test_recall_isolates_cached_context_across_scopes(tmp_path: Path) -> None: # Regression for the multi-tenant case: one shared PowerContextRecall serves many runs. Two runs carrying the same # human turn (identical id and text) but different scopes must each receive only their own scope's context. If the # per-turn cache keyed on the turn alone, the first scope's prepared content would be replayed to the second. - scope_alpha = "project:tenant-alpha" - scope_bravo = "project:tenant-bravo" marker_alpha = "ALPHA_SECRET_RUNBOOK" marker_bravo = "BRAVO_SECRET_RUNBOOK" turn = HumanMessage(content="How do we deploy the database migrations?", id="shared-turn") @@ -243,6 +249,24 @@ def test_recall_isolates_cached_context_across_scopes(tmp_path: Path) -> None: app = _server_app(tmp_path) async def scenario(client: PowerContextClient) -> None: + scope_alpha = ( + await client.create_scope( + CreateScopeRequest( + title="Tenant alpha", + summary="LangGraph cache-isolation test Scope", + idempotency_key="langgraph-cache-isolation-alpha", + ) + ) + ).scope_id + scope_bravo = ( + await client.create_scope( + CreateScopeRequest( + title="Tenant bravo", + summary="LangGraph cache-isolation test Scope", + idempotency_key="langgraph-cache-isolation-bravo", + ) + ) + ).scope_id await client.remember_memory( RememberMemoryRequest( scope_id=scope_alpha, @@ -283,16 +307,9 @@ async def driver() -> None: # No shared client is installed, so the recall hook opens a real client against a closed port. result = await agent.ainvoke( {"messages": [HumanMessage(content="anything at all")]}, - context=PowerContextScope(scope_id=SCOPE, base_url="http://127.0.0.1:9", timeout=2.0), + context=PowerContextScope(base_url="http://127.0.0.1:9", timeout=2.0), ) assert model.inputs and _system_texts(model.inputs[-1]) == [] assert any(message.type == "ai" for message in result["messages"]) asyncio.run(driver()) - - -def test_missing_scope_outside_repository_raises(tmp_path: Path) -> None: - from powercontext_langgraph import resolve_scope_id - - with pytest.raises(MissingScopeError): - resolve_scope_id(None, cwd=str(tmp_path)) diff --git a/tests/langgraph_adapter/test_scope.py b/tests/langgraph_adapter/test_scope.py index 74bc26192..49c2bc1b5 100644 --- a/tests/langgraph_adapter/test_scope.py +++ b/tests/langgraph_adapter/test_scope.py @@ -12,90 +12,54 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Scope-resolution tests for the PowerContext LangGraph adapter. - -The adapter inverts the Codex priority: an explicit scope wins, a network Git remote is the fallback, and neither -available is an error rather than a silent shared-local default. -""" +"""Scope configuration tests for the PowerContext LangGraph adapter.""" from __future__ import annotations -import subprocess -from pathlib import Path -from shutil import which - import pytest pytest.importorskip("powercontext_langgraph") -from powercontext_langgraph import MissingScopeError, resolve_scope_id -from powercontext_langgraph.scope import normalize_git_remote +from powercontext_langgraph import PowerContextScope +from powercontext_langgraph.client import resolve_config +from powercontext_langgraph.settings import PowerContextLangGraphSettings + +TEST_TOKEN = "langgraph-scope-test-token" # noqa: S105 - non-secret test credential. + -from powercontext.limits import MAX_SCOPE_ID_LENGTH +def test_run_scope_overrides_environment_settings() -> None: + settings = PowerContextLangGraphSettings( + base_url="https://server.example", + scope_id="scp_environment", + timeout=20, + ) + config = resolve_config( + PowerContextScope( + scope_id=" scp_run ", + base_url="https://run.example", + token=TEST_TOKEN, + timeout=3, + ), + settings=settings, + ) -def test_explicit_scope_takes_priority() -> None: - assert resolve_scope_id("project:acme") == "project:acme" + assert config.base_url == "https://run.example" + assert config.scope_id == "scp_run" + assert config.token == TEST_TOKEN + assert config.timeout == 3 -def test_explicit_scope_over_length_is_hashed() -> None: - resolved = resolve_scope_id("x" * (MAX_SCOPE_ID_LENGTH + 1)) - assert resolved.startswith("sha256:") - assert len(resolved) <= MAX_SCOPE_ID_LENGTH +def test_blank_scope_uses_server_default() -> None: + config = resolve_config( + PowerContextScope(scope_id=" "), + settings=PowerContextLangGraphSettings(scope_id=None), + ) + assert config.scope_id is None -def test_missing_scope_outside_repository_raises(tmp_path: Path) -> None: - with pytest.raises(MissingScopeError): - resolve_scope_id(None, cwd=str(tmp_path)) +def test_scope_token_is_hidden_from_repr() -> None: + scope = PowerContextScope(token=TEST_TOKEN) -@pytest.mark.skipif(which("git") is None, reason="git is required to derive a scope from a remote") -def test_git_remote_is_derived_and_credentials_dropped(tmp_path: Path) -> None: - git = which("git") - assert git is not None - subprocess.run([git, "init", "--quiet"], cwd=tmp_path, check=True) - subprocess.run( - [git, "remote", "add", "origin", "https://user:secret@github.com/oceanbase/powercontext.git"], - cwd=tmp_path, - check=True, - ) - resolved = resolve_scope_id(None, cwd=str(tmp_path)) - assert resolved == "git:github.com/oceanbase/powercontext" - assert "secret" not in resolved - - -@pytest.mark.parametrize( - ("remote", "expected"), - [ - ("https://github.com/oceanbase/powercontext.git", "github.com/oceanbase/powercontext"), - ("git@github.com:oceanbase/powercontext.git", "github.com/oceanbase/powercontext"), - ("ssh://git@example.com:2222/team/repo.git", "example.com:2222/team/repo"), - ("https://user:token@github.com/oceanbase/powercontext.git", "github.com/oceanbase/powercontext"), - ], -) -def test_normalize_git_remote_forms(remote: str, expected: str) -> None: - assert normalize_git_remote(remote) == expected - - -@pytest.mark.parametrize( - "remote", - [ - "", - "not-a-remote", - "/local/path/only", - # Windows drive-letter paths parse as an SCP ``host:path`` whose host is the drive letter. They are local - # filesystem paths, not network remotes, and must not be turned into a scope. - r"C:\work\tenant-repo.git", - "C:/work/tenant-repo.git", - r"D:\repos\api", - ], -) -def test_normalize_git_remote_rejects_non_network_remotes(remote: str) -> None: - assert normalize_git_remote(remote) is None - - -@pytest.mark.parametrize("remote", [r"C:\work\tenant-repo.git", "C:/work/tenant-repo.git"]) -def test_resolve_scope_id_rejects_windows_local_remote(monkeypatch: pytest.MonkeyPatch, remote: str) -> None: - monkeypatch.setattr("powercontext_langgraph.scope._git_remote", lambda _cwd: remote) - with pytest.raises(MissingScopeError): - resolve_scope_id(None, cwd="/irrelevant") + assert TEST_TOKEN not in repr(scope) diff --git a/tests/langgraph_adapter/test_tools.py b/tests/langgraph_adapter/test_tools.py index a1752814b..1b4bf2c22 100644 --- a/tests/langgraph_adapter/test_tools.py +++ b/tests/langgraph_adapter/test_tools.py @@ -12,11 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Behavior tests for the PowerContext Memory tools exposed to LangGraph agents. - -The tools resolve their scope and connection from environment settings when invoked outside a graph run, so these -tests set ``POWERCONTEXT_LANGGRAPH_*`` and route the shared HTTP client at an in-process server. -""" +"""Behavior tests for the PowerContext Memory tools exposed to LangGraph agents.""" from __future__ import annotations @@ -45,8 +41,6 @@ ) from powercontext_langgraph.client import shared_http_client -SCOPE = "project:langgraph-tools-test" - def _server_app(tmp_path: Path) -> FastAPI: return create_server_app( @@ -72,8 +66,8 @@ async def driver() -> None: @pytest.fixture(autouse=True) def _env(monkeypatch: pytest.MonkeyPatch) -> None: - monkeypatch.setenv("POWERCONTEXT_LANGGRAPH_SCOPE_ID", SCOPE) monkeypatch.setenv("POWERCONTEXT_LANGGRAPH_BASE_URL", "http://testserver") + monkeypatch.delenv("POWERCONTEXT_LANGGRAPH_SCOPE_ID", raising=False) monkeypatch.delenv("POWERCONTEXT_LANGGRAPH_TOKEN", raising=False) @@ -88,7 +82,7 @@ def test_powercontext_tools_returns_three_base_tools() -> None: } -def test_remember_then_search_roundtrips_through_the_server(tmp_path: Path) -> None: +def test_remember_then_search_roundtrips_through_server_default_scope(tmp_path: Path) -> None: app = _server_app(tmp_path) async def scenario() -> None: @@ -147,11 +141,15 @@ async def scenario() -> None: (powercontext_remember, {"text": "note", "kind": "k" * 200}), # kind above the max length ], ) -def test_tools_reject_out_of_range_arguments_without_raising(tool, arguments) -> None: # type: ignore[no-untyped-def] +def test_tools_reject_out_of_range_arguments_without_raising( # type: ignore[no-untyped-def] + tool, + arguments, + tmp_path: Path, +) -> None: # Request construction is inside the fail-open boundary: a model-supplied argument outside the public contract # returns a tool result instead of raising and aborting the graph. async def scenario() -> None: result = await tool.ainvoke(arguments) assert result.startswith("(PowerContext rejected the request:") - asyncio.run(scenario()) + _run(_server_app(tmp_path), scenario) diff --git a/tests/pydantic_ai_adapter/fakes.py b/tests/pydantic_ai_adapter/fakes.py index f883767b5..722696b75 100644 --- a/tests/pydantic_ai_adapter/fakes.py +++ b/tests/pydantic_ai_adapter/fakes.py @@ -29,6 +29,7 @@ MemoryMutationResponse, MemoryUsedSearchMode, PreparedContext, + ScopeDescriptor, SearchMemoryHit, SearchMemoryResponse, SourceReference, @@ -89,6 +90,17 @@ def prepared_response(content: str | None = "Prepared memory evidence.") -> Prep }) +def scope_descriptor(scope_id: str) -> ScopeDescriptor: + return ScopeDescriptor( + scope_id=scope_id, + title="Test Scope", + summary="Scope returned by the recording client.", + context_references=[], + external_references=[], + version=1, + ) + + class RecordingClient: """Configurable async client double that records the adapter boundary.""" @@ -100,6 +112,7 @@ class RecordingClient: flush_error: ClassVar[Exception | None] = None capture_position_offset: ClassVar[int] = 0 flush_cursors: ClassVar[tuple[int, ...] | None] = None + default_scope_id: ClassVar[str] = "server:default" def __init__( self, @@ -112,6 +125,7 @@ def __init__( self.token = token self.timeout = timeout self.closed = False + self.resolve_scope_requests: list[Any] = [] self.search_requests: list[Any] = [] self.remember_requests: list[Any] = [] self.prepare_requests: list[Any] = [] @@ -130,6 +144,7 @@ def reset(cls) -> None: cls.flush_error = None cls.capture_position_offset = 0 cls.flush_cursors = None + cls.default_scope_id = "server:default" async def __aenter__(self) -> RecordingClient: return self @@ -138,6 +153,10 @@ async def __aexit__(self, *exc_info: object) -> None: del exc_info self.closed = True + async def resolve_scope_binding(self, request: Any) -> ScopeDescriptor: + self.resolve_scope_requests.append(request) + return scope_descriptor(request.explicit_scope_id or type(self).default_scope_id) + async def search_memory(self, request: Any) -> Any: self.search_requests.append(request) return _result_or_raise(type(self).search_result) diff --git a/tests/pydantic_ai_adapter/test_settings_scope.py b/tests/pydantic_ai_adapter/test_settings_scope.py index cbba53fd1..e3052a09b 100644 --- a/tests/pydantic_ai_adapter/test_settings_scope.py +++ b/tests/pydantic_ai_adapter/test_settings_scope.py @@ -15,12 +15,7 @@ from __future__ import annotations import asyncio -import hashlib -import os -from pathlib import Path -from typing import Any, cast -import powercontext_pydantic_ai.scope as scope_module import powercontext_pydantic_ai.toolset as toolset_module import pytest from powercontext_pydantic_ai import PowerContext, PowerContextSettings @@ -80,54 +75,36 @@ def test_settings_require_a_bare_token_without_leaking_invalid_input() -> None: assert token not in str(exc_info.value) -@pytest.mark.parametrize( - ("remote", "expected"), - [ - ("https://github.com/OceanBase/powercontext.git", "github.com/OceanBase/powercontext"), - ("ssh://git@github.com/OceanBase/powercontext.git", "github.com/OceanBase/powercontext"), - ("git@github.com:OceanBase/powercontext.git", "github.com/OceanBase/powercontext"), - ], -) -def test_scope_reuses_codex_remote_normalization(remote: str, expected: str) -> None: - assert scope_module.normalize_git_remote(remote) == expected - - -def test_scope_uses_normalized_git_origin_then_local_path( - monkeypatch: pytest.MonkeyPatch, - tmp_path: Path, -) -> None: - def git_remote(_cwd: str, *arguments: str) -> str | None: - if arguments == ("rev-parse", "--show-toplevel"): - return str(tmp_path) - if arguments == ("config", "--get", "remote.origin.url"): - return "https://token@GitHub.com/OceanBase/powercontext.git" - return None +def test_settings_reject_scope_id_over_contract_limit_instead_of_rewriting_it() -> None: + with pytest.raises(ValidationError): + PowerContextSettings(scope_id="scope:" + "x" * 300) - monkeypatch.setattr(scope_module, "_git_value", git_remote) - assert scope_module.derive_scope_id(tmp_path) == "git:github.com/OceanBase/powercontext" - monkeypatch.setattr(scope_module, "_git_value", lambda *_args: None) - digest = hashlib.sha256(os.fsencode(tmp_path.resolve())).hexdigest() - assert scope_module.derive_scope_id(tmp_path) == f"local:{digest}" +def test_server_default_scope_is_used_for_the_run(monkeypatch: pytest.MonkeyPatch) -> None: + RecordingClient.reset() + RecordingClient.default_scope_id = "server:chosen-default" + monkeypatch.delenv("POWERCONTEXT_PYDANTIC_AI_SCOPE_ID", raising=False) + monkeypatch.setattr(toolset_module, "PowerContextClient", RecordingClient) + async def respond(_messages, _info): + return ModelResponse(parts=[TextPart("complete")]) -def test_explicit_scope_skips_git_and_is_deterministically_bounded(monkeypatch: pytest.MonkeyPatch) -> None: - monkeypatch.setattr( - scope_module, - "_git_value", - lambda *_args: pytest.fail("explicit scope must not invoke Git"), - ) - configured = "scope:" + "x" * 300 - settings = PowerContextSettings(scope_id=configured) - ctx = cast(RunContext[Any], object()) + async def scenario() -> None: + agent = Agent(FunctionModel(respond), capabilities=[PowerContext()]) + result = await agent.run("use the Server default Scope") + assert result.output == "complete" - resolved = scope_module.resolve_scope_id(ctx, None, settings.scope_id) + asyncio.run(scenario()) - assert resolved == f"sha256:{hashlib.sha256(configured.encode()).hexdigest()}" - assert len(resolved) <= 256 + client = RecordingClient.instances[0] + assert client.resolve_scope_requests + assert {request.explicit_scope_id for request in client.resolve_scope_requests} == {None} + assert {request.scope_id for request in client.prepare_requests} == {"server:chosen-default"} -def test_constructor_scope_callback_wins_and_runs_once_per_agent_run(monkeypatch: pytest.MonkeyPatch) -> None: +def test_constructor_scope_callback_selects_the_scope_for_the_run( + monkeypatch: pytest.MonkeyPatch, +) -> None: RecordingClient.reset() RecordingClient.prepare_result = prepared_response(None) monkeypatch.setattr(toolset_module, "PowerContextClient", RecordingClient) @@ -160,6 +137,7 @@ async def scenario() -> None: asyncio.run(scenario()) - assert len(calls) == 1 - assert RecordingClient.instances[0].prepare_requests - assert {request.scope_id for request in RecordingClient.instances[0].prepare_requests} == {"constructor:scope"} + assert calls + client = RecordingClient.instances[0] + assert {request.explicit_scope_id for request in client.resolve_scope_requests} == {"constructor:scope"} + assert {request.scope_id for request in client.prepare_requests} == {"constructor:scope"} diff --git a/tests/pydantic_ai_adapter/test_toolset.py b/tests/pydantic_ai_adapter/test_toolset.py index 7d8fd45cd..8ca9ce846 100644 --- a/tests/pydantic_ai_adapter/test_toolset.py +++ b/tests/pydantic_ai_adapter/test_toolset.py @@ -83,6 +83,7 @@ async def scenario() -> Any: assert "untrusted historical evidence" in (model_calls[0][-1].instructions or "") client = RecordingClient.instances[0] + assert [request.explicit_scope_id for request in client.resolve_scope_requests] == ["project:tools"] assert client.search_requests[0].model_dump(mode="json") == { "scope_id": "project:tools", "query": "public response", diff --git a/tests/test_api_contract.py b/tests/test_api_contract.py index 537e827ef..228d4ab1e 100644 --- a/tests/test_api_contract.py +++ b/tests/test_api_contract.py @@ -163,14 +163,14 @@ def test_capture_operation_declares_its_typed_accepted_exchange() -> None: assert CAPTURE_CONTENT_SOURCE.success_status == 202 -def test_stats_operation_exposes_dashboard_ready_scoped_values() -> None: - assert GET_STATS.method == "GET" +def test_stats_operation_exposes_dashboard_ready_selection_values() -> None: + assert GET_STATS.method == "POST" assert GET_STATS.path == "/v1/stats" assert GET_STATS.request_type is GetStatsRequest - assert GET_STATS.request_location == "query" + assert GET_STATS.request_location == "body" assert GET_STATS.response_type is ScopedStats assert GET_STATS.success_status == 200 - assert GetStatsRequest(scope_id="project").period is StatsPeriod.FIELD_30D + assert GetStatsRequest.model_validate({"selection": {"mode": "all"}}).period is StatsPeriod.FIELD_30D contract = yaml.safe_load(CONTRACT_PATH.read_text()) schemas = contract["components"]["schemas"] @@ -179,10 +179,19 @@ def test_stats_operation_exposes_dashboard_ready_scoped_values() -> None: usage_value = schemas["ModelUsageValue"] recall = schemas["RecallTokenStatistics"] - operation = contract["paths"]["/v1/stats"]["get"] - assert "requestBody" not in operation - assert [parameter["name"] for parameter in operation["parameters"]] == ["scope_id", "period"] - assert set(stats["properties"]) == {"scope_id", "as_of", "inventory", "usage", "recall"} + operation = contract["paths"]["/v1/stats"]["post"] + assert operation["requestBody"]["content"]["application/json"]["schema"] == { + "$ref": "#/components/schemas/GetStatsRequest" + } + assert set(stats["properties"]) == { + "selection", + "scope_ids", + "as_of", + "inventory", + "usage", + "recall", + "by_scope", + } assert usage["properties"]["by_purpose"]["maxItems"] == 16 assert usage["properties"]["daily"]["maxItems"] == 30 assert usage_value["properties"]["input_tokens"]["nullable"] is True @@ -191,6 +200,18 @@ def test_stats_operation_exposes_dashboard_ready_scoped_values() -> None: assert recall["properties"]["daily"]["maxItems"] == 30 +def test_scope_resource_operations_separate_identity_from_mutable_metadata() -> None: + contract = yaml.safe_load(CONTRACT_PATH.read_text()) + path_item = contract["paths"]["/v1/scopes/{scope_id}"] + assert path_item["get"]["parameters"][0]["in"] == "path" + assert "requestBody" not in path_item["get"] + assert path_item["put"]["parameters"][0]["in"] == "path" + assert path_item["put"]["requestBody"]["content"]["application/json"]["schema"] == { + "$ref": "#/components/schemas/UpdateScopeRequest" + } + assert "scope_id" not in contract["components"]["schemas"]["UpdateScopeRequest"]["properties"] + + def test_memory_operations_use_family_prefixed_paths_and_typed_requests() -> None: memory_operations = ( FLUSH_MEMORY, diff --git a/tests/test_cli.py b/tests/test_cli.py index aaa65eabb..c33503108 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -60,59 +60,64 @@ def _empty_inventory() -> dict[str, object]: def _stats_response() -> ScopedStats: - return ScopedStats.model_validate({ - "scope_id": "project", - "as_of": "2026-08-04T12:00:00Z", - "inventory": _empty_inventory(), - "usage": { - "period": { - "preset": "today", - "start_date": "2026-08-04", - "end_date": "2026-08-04", - "timezone": "UTC", - }, - "totals": { + inventory = _empty_inventory() + usage = { + "period": { + "preset": "today", + "start_date": "2026-08-04", + "end_date": "2026-08-04", + "timezone": "UTC", + }, + "totals": { + "generation": {"requests": 0, "input_tokens": 0, "output_tokens": 0}, + "embedding": {"requests": 0, "input_tokens": 0, "output_tokens": 0}, + }, + "by_purpose": [], + "daily": [ + { + "date": "2026-08-04", "generation": {"requests": 0, "input_tokens": 0, "output_tokens": 0}, "embedding": {"requests": 0, "input_tokens": 0, "output_tokens": 0}, - }, - "by_purpose": [], - "daily": [ - { - "date": "2026-08-04", - "generation": {"requests": 0, "input_tokens": 0, "output_tokens": 0}, - "embedding": {"requests": 0, "input_tokens": 0, "output_tokens": 0}, - "by_purpose": [], - } - ], + "by_purpose": [], + } + ], + } + recall = { + "period": { + "preset": "today", + "start_date": "2026-08-04", + "end_date": "2026-08-04", + "timezone": "UTC", + }, + "estimator": {"estimator_id": "character:weighted", "version": "1"}, + "totals": { + "preparations": 3, + "ready_preparations": 2, + "comparable_preparations": 1, + "baseline_tokens": 100, + "recalled_tokens": 40, + "token_reduction": 60, }, - "recall": { - "period": { - "preset": "today", - "start_date": "2026-08-04", - "end_date": "2026-08-04", - "timezone": "UTC", - }, - "estimator": {"estimator_id": "character:weighted", "version": "1"}, - "totals": { + "daily": [ + { + "date": "2026-08-04", "preparations": 3, "ready_preparations": 2, "comparable_preparations": 1, "baseline_tokens": 100, "recalled_tokens": 40, "token_reduction": 60, - }, - "daily": [ - { - "date": "2026-08-04", - "preparations": 3, - "ready_preparations": 2, - "comparable_preparations": 1, - "baseline_tokens": 100, - "recalled_tokens": 40, - "token_reduction": 60, - } - ], - }, + } + ], + } + return ScopedStats.model_validate({ + "selection": {"mode": "exact", "scope_ids": ["project"]}, + "scope_ids": ["project"], + "as_of": "2026-08-04T12:00:00Z", + "inventory": inventory, + "usage": usage, + "recall": recall, + "by_scope": [{"scope_id": "project", "inventory": inventory, "usage": usage, "recall": recall}], }) @@ -479,7 +484,10 @@ async def get_stats(self, request: GetStatsRequest) -> ScopedStats: ) assert result.exit_code == 0 - assert received[0].model_dump(mode="json") == {"scope_id": "project", "period": "today"} + assert received[0].model_dump(mode="json") == { + "selection": {"mode": "exact", "scope_ids": ["project"]}, + "period": "today", + } assert "Sources: 0 total, 0 memory processed, 0 memory pending" in result.output assert "Generation: 0 requests, 0 input tokens, 0 output tokens" in result.output assert "Recall token estimator: character:weighted@1" in result.output diff --git a/tests/test_cli_workbuddy.py b/tests/test_cli_workbuddy.py index 1c8208650..5058e8c09 100644 --- a/tests/test_cli_workbuddy.py +++ b/tests/test_cli_workbuddy.py @@ -45,7 +45,7 @@ def _write_plugin(root: Path) -> Path: scripts = plugin / "scripts" scripts.mkdir() (scripts / "__init__.py").write_text('"""PowerContext helper scripts."""\n', encoding="utf-8") - (scripts / "project_scope.py").write_text( + (scripts / "workspace_scope.py").write_text( "import json\n\n" "def resolve_scope_id(*_args, **_kwargs) -> str:\n" " return 'scope'\n\n" @@ -55,11 +55,11 @@ def _write_plugin(root: Path) -> Path: ) cache = scripts / "__pycache__" cache.mkdir() - (cache / "project_scope.cpython-312.pyc").write_bytes(b"\x00") + (cache / "scope_binding.cpython-312.pyc").write_bytes(b"\x00") skill = plugin / "skills" / "project-context" skill.mkdir(parents=True) (skill / "SKILL.md").write_text( - '${POWERCONTEXT_PYTHON} ${POWERCONTEXT_PROJECT_SCOPE_SCRIPT} --cwd "$PWD"\n', + '${POWERCONTEXT_PYTHON} ${POWERCONTEXT_SCOPE_BINDING_SCRIPT} --cwd "$PWD"\n', encoding="utf-8", ) return plugin @@ -109,14 +109,14 @@ def test_setup_workbuddy_installs_from_a_local_checkout(tmp_path: Path, monkeypa hooks_dir = home / "hooks" for name in _HOOK_MODULES: assert (hooks_dir / name).is_file() - assert (hooks_dir / "powercontext_project_scope.py").is_file() + assert (hooks_dir / "powercontext_scope_binding.py").is_file() skill_markdown = home / "skills" / "project-context" / "SKILL.md" assert skill_markdown.is_file() skill_content = skill_markdown.read_text(encoding="utf-8") - assert "${POWERCONTEXT_PROJECT_SCOPE_SCRIPT}" not in skill_content + assert "${POWERCONTEXT_SCOPE_BINDING_SCRIPT}" not in skill_content assert "${POWERCONTEXT_PYTHON}" not in skill_content - assert (hooks_dir / "powercontext_project_scope.py").as_posix() in skill_content + assert (hooks_dir / "powercontext_scope_binding.py").as_posix() in skill_content assert Path(sys.executable).as_posix() in skill_content assert json.loads((skill_markdown.parent / ".powercontext.json").read_text(encoding="utf-8")) == { "schema": 1, @@ -322,7 +322,7 @@ def test_setup_workbuddy_refreshes_an_owned_skill(tmp_path: Path, monkeypatch) - assert first.exit_code == 0 (plugin / "skills" / "project-context" / "SKILL.md").write_text( - 'updated\n${POWERCONTEXT_PYTHON} ${POWERCONTEXT_PROJECT_SCOPE_SCRIPT} --cwd "$PWD"\n', + 'updated\n${POWERCONTEXT_PYTHON} ${POWERCONTEXT_SCOPE_BINDING_SCRIPT} --cwd "$PWD"\n', encoding="utf-8", ) refreshed = CliRunner().invoke(create_cli([setup_app]), ["setup", "workbuddy", "--source", str(checkout)]) diff --git a/tests/test_client.py b/tests/test_client.py index 40e036b7d..2947b7296 100644 --- a/tests/test_client.py +++ b/tests/test_client.py @@ -23,7 +23,12 @@ from powercontext.client.settings import ClientSettings from powercontext.http import ( CaptureContentSourceRequest, + ExactScopeSelection, GetHandoffReportRequest, + ReportFormat, + ScopeId, + ScopeSelection, + UpdateScopeRequest, ) @@ -100,6 +105,48 @@ def respond(request: httpx.Request) -> httpx.Response: asyncio.run(scenario()) +def test_client_uses_scope_resource_paths_without_repeating_the_id_in_the_body() -> None: + async def scenario() -> None: + requests: list[httpx.Request] = [] + + def respond(request: httpx.Request) -> httpx.Response: + requests.append(request) + return httpx.Response( + 200, + json={ + "scope_id": "scope:feature", + "title": "Feature", + "summary": "Current work", + "parent_scope_id": None, + "context_references": [], + "external_references": [], + "version": 1, + }, + ) + + async with httpx.AsyncClient(transport=httpx.MockTransport(respond)) as http_client: + client = PowerContextClient("https://memory.example", http_client=http_client) + await client.get_scope("scope:feature") + await client.update_scope( + "scope:feature", + UpdateScopeRequest( + expected_version=1, + title="Feature", + summary="Current work", + ), + ) + + assert [request.method for request in requests] == ["GET", "PUT"] + assert [request.url.raw_path for request in requests] == [ + b"/v1/scopes/scope%3Afeature", + b"/v1/scopes/scope%3Afeature", + ] + assert requests[0].content == b"" + assert "scope_id" not in json.loads(requests[1].content) + + asyncio.run(scenario()) + + def test_client_keeps_a_generic_server_error_when_the_error_body_is_invalid() -> None: async def scenario() -> None: response = httpx.Response(500, text="Internal Server Error") @@ -161,7 +208,10 @@ def respond(request: httpx.Request) -> httpx.Response: async with httpx.AsyncClient(transport=httpx.MockTransport(respond)) as http_client: client = PowerContextClient("https://memory.example", http_client=http_client) - request = GetHandoffReportRequest(scope_id="scope-1") + request = GetHandoffReportRequest( + selection=ScopeSelection(root=ExactScopeSelection(mode="exact", scope_ids=[ScopeId("scope-1")])), + format=ReportFormat.MARKDOWN, + ) rendered = await client.get_handoff_report(request) content = await client.download_handoff_report(request) @@ -169,7 +219,10 @@ def respond(request: httpx.Request) -> httpx.Response: assert content == b"# Handoff Report\n" assert len(requests) == 2 assert json.loads(requests[0].content)["download"] is False - assert json.loads(requests[0].content)["scope_id"] == "scope-1" + assert json.loads(requests[0].content)["selection"] == { + "mode": "exact", + "scope_ids": ["scope-1"], + } assert json.loads(requests[1].content)["download"] is True asyncio.run(scenario()) diff --git a/tests/test_config_cli.py b/tests/test_config_cli.py index 6d68f4382..4c0b1658f 100644 --- a/tests/test_config_cli.py +++ b/tests/test_config_cli.py @@ -120,18 +120,18 @@ def test_init_validate_and_show_round_trip_managed_environment( assert "initial-secret" not in shown.output -def test_init_rejects_configuration_that_server_settings_reject( +def test_init_rejects_configuration_that_validation_rejects( monkeypatch: pytest.MonkeyPatch, tmp_path: Path, ) -> None: environment = tmp_path / ".env" - invalid = _configuration(scope_id="p" * 256) + invalid = _configuration(embedding_dimension=0) monkeypatch.setattr(config_cli, "collect_configuration", lambda **_kwargs: invalid) result = CliRunner().invoke(config_cli.app, ["init", "--output", str(environment)]) assert result.exit_code == 2 - assert "at most 255 characters" in result.output + assert "Embedding dimension and Source interval must be positive" in result.output assert not environment.exists() @@ -200,7 +200,7 @@ def test_custom_connection_is_not_reclassified_from_its_model_prefix(monkeypatch ) connections = iter(((generation, ("CUSTOM_CREDENTIAL",)), (embedding, ("VOYAGE_API_KEY",)))) monkeypatch.setattr(config_cli, "_collect_connection", lambda _role: next(connections)) - prompts = iter(("project:test", "Test", 3)) + prompts = iter((3,)) monkeypatch.setattr(config_cli.typer, "prompt", lambda *_args, **_kwargs: next(prompts)) with patch.object( @@ -381,7 +381,7 @@ def test_init_hides_and_redacts_marked_additional_credentials( result = CliRunner().invoke( config_cli.app, ["init", "--output", str(environment)], - input="\n\n\n-\n-\nMYTOKEN\ny\nextra-secret\n\n\n-\n-\n\n1536\ny\n", + input="\n-\n-\nMYTOKEN\ny\nextra-secret\n\n\n-\n-\n\n1536\ny\n", ) text = environment.read_text(encoding="utf-8") @@ -448,7 +448,7 @@ def _configuration( generation: config_cli.ModelSelection | None = None, embedding: config_cli.ModelSelection | None = None, credentials: tuple[str, ...] = ("OPENAI_API_KEY",), - scope_id: str = "project:quickstart", + embedding_dimension: int = 1536, database_kind: str = "sqlite", database_url: str | None = None, database_path: str | None = None, @@ -456,12 +456,10 @@ def _configuration( shared = (config_cli.ProviderVariable("OPENAI_API_KEY", "initial-secret"),) return config_cli.GeneratedConfiguration( config_version=1, - scope_id=scope_id, - display_name="Quick Start", generation=generation or config_cli.ModelSelection("openai:gpt-4.1-mini", shared), embedding=embedding or config_cli.ModelSelection("openai:text-embedding-3-small", shared), embedding_profile_id="openai-text-embedding-3-small-1536-unit-v1", - embedding_dimension=1536, + embedding_dimension=embedding_dimension, database_kind=database_kind, database_url=database_url, database_path=database_path, diff --git a/tests/test_dashboard.py b/tests/test_dashboard.py index 8b81ae31f..48f083ca1 100644 --- a/tests/test_dashboard.py +++ b/tests/test_dashboard.py @@ -27,7 +27,6 @@ from powercontext.server.settings import ( BearerAuthConfig, DashboardConfig, - DashboardScopeConfig, McpConfig, ServerSettings, ) @@ -40,7 +39,6 @@ def test_dashboard_is_enabled_by_default_without_authentication_or_scopes(tmp_pa "POWERCONTEXT_SERVER_AUTH_ENABLED", "POWERCONTEXT_SERVER_AUTH_TOKEN", "POWERCONTEXT_SERVER_DASHBOARD_ENABLED", - "POWERCONTEXT_SERVER_DASHBOARD_SCOPES", ): monkeypatch.delenv(name, raising=False) settings = ServerSettings( @@ -56,12 +54,13 @@ def test_dashboard_is_enabled_by_default_without_authentication_or_scopes(tmp_pa scopes = client.get("/dashboard/scopes") assert settings.dashboard.enabled is True - assert settings.dashboard.scopes == [] assert home.status_code == 200 assert skills.status_code == 200 assert review.status_code == 200 assert scopes.status_code == 200 - assert scopes.json() == [] + assert scopes.json()[0]["display_name"] == "Default" + assert scopes.json()[0]["summary"] == "Default context" + assert scopes.json()[0]["parent_scope_id"] is None def test_dashboard_can_be_disabled_explicitly(tmp_path) -> None: @@ -114,19 +113,23 @@ def test_dashboard_is_the_authenticated_server_ui_entry(tmp_path) -> None: enabled=True, token=SecretStr("dashboard-secret"), ), - dashboard=DashboardConfig( - enabled=True, - scopes=[ - DashboardScopeConfig(scope_id="person:psiace", display_name="PsiACE"), - DashboardScopeConfig(scope_id="project:powercontext", display_name="PowerContext"), - ], - ), + dashboard=DashboardConfig(enabled=True), database=SQLiteConfig(url=f"sqlite+aiosqlite:///{tmp_path / 'dashboard.db'}"), mcp=McpConfig(enabled=False), ) ) with TestClient(app) as client: + first_scope = client.post( + "/v1/scopes", + headers=_AUTH_HEADERS, + json={"title": "PsiACE", "summary": "Personal context", "idempotency_key": "psiace"}, + ).json() + second_scope = client.post( + "/v1/scopes", + headers=_AUTH_HEADERS, + json={"title": "PowerContext", "summary": "Repository context", "idempotency_key": "powercontext"}, + ).json() home = client.get("/") skills = client.get("/skills") review = client.get("/reviews") @@ -140,10 +143,54 @@ def test_dashboard_is_the_authenticated_server_ui_entry(tmp_path) -> None: assert removed_dashboard_alias.status_code == 404 assert missing_scopes.status_code == 401 assert scopes.status_code == 200 - assert scopes.json() == [ - {"scope_id": "person:psiace", "display_name": "PsiACE"}, - {"scope_id": "project:powercontext", "display_name": "PowerContext"}, - ] + assert 'data-server-session="missing"' in home.text + assert 'id="auth-shell"' in home.text + assert 'id="auth-shell" hidden' not in home.text + assert 'id="page-status" hidden' in home.text + assert 'class="server-content" id="dashboard"' in home.text + assert 'id="dashboard" hidden' not in home.text + assert 'data-server-auth-required="true"' in home.text + assert 'data-i18n-aria-label="brandHomeLabel"' in home.text + assert 'data-i18n-aria-label="primaryNavigation"' in home.text + assert 'data-i18n-aria-label="scopeOverview"' in home.text + assert 'data-i18n-aria-label="activityAria"' in home.text + assert "dashboard.js?v=product-language-v4" in home.text + assert 'data-i18n="skillsTitle"' in skills.text + assert 'aria-current="page" data-i18n="skillsTitle"' in skills.text + assert 'id="skills-scope-search"' in skills.text + assert 'role="combobox"' in skills.text + assert 'aria-controls="skills-scope-options"' in skills.text + assert 'id="skills-scope-options" role="listbox"' in skills.text + assert 'id="skills-search"' in skills.text + assert 'id="skills-authority-filter"' in skills.text + assert 'id="skills-list" role="listbox"' in skills.text + assert 'id="skills-managed-content"' in skills.text + assert 'id="skills-delivery"' in skills.text + assert 'id="skills-create-revision"' in skills.text + assert 'id="skills-publish-dialog"' in skills.text + assert "skills.js?v=agent-targets-v1" in skills.text + assert 'data-i18n="reviewTitle"' in review.text + assert 'aria-current="page" data-i18n="reviewTitle"' in review.text + assert 'id="review-scope-select"' not in review.text + assert 'id="review-scope-search"' in review.text + assert 'role="combobox"' in review.text + assert 'aria-controls="review-scope-options"' in review.text + assert 'id="review-scope-options" role="listbox"' in review.text + assert 'id="review-family-filter"' in review.text + assert 'id="review-status-filter"' in review.text + assert 'id="review-list" role="listbox"' in review.text + assert 'id="review-revision-form" hidden' in review.text + assert 'id="review-approve-dialog"' in review.text + assert 'id="review-reject-dialog"' in review.text + assert 'id="review-publication"' in review.text + assert 'id="review-create-skill-revision"' in review.text + assert 'id="review-revision-title"' in review.text + assert 'id="review-publish-dialog"' in review.text + assert "review.js?v=agent-targets-v1" in review.text + returned = {item["scope_id"]: item for item in scopes.json()} + assert returned[first_scope["scope_id"]]["display_name"] == "PsiACE" + assert returned[first_scope["scope_id"]]["summary"] == "Personal context" + assert returned[second_scope["scope_id"]]["display_name"] == "PowerContext" def test_review_publishes_an_approved_managed_skill_into_configured_agent_targets(tmp_path) -> None: @@ -151,10 +198,7 @@ def test_review_publishes_an_approved_managed_skill_into_configured_agent_target claude_skill_root = tmp_path / "repository" / ".claude" / "skills" settings = ServerSettings( auth=BearerAuthConfig(enabled=True, token=SecretStr("dashboard-secret")), - dashboard=DashboardConfig( - enabled=True, - scopes=[DashboardScopeConfig(scope_id="project:powercontext", display_name="PowerContext")], - ), + dashboard=DashboardConfig(enabled=True), database=SQLiteConfig(url=f"sqlite+aiosqlite:///{tmp_path / 'managed-skill-publish.db'}"), external_skills=ExternalSkillsConfig( host_id="dashboard-test", @@ -180,11 +224,16 @@ def test_review_publishes_an_approved_managed_skill_into_configured_agent_target app = create_server_app(settings=settings) with TestClient(app) as client: + scope_id = client.post( + "/v1/scopes", + headers=_AUTH_HEADERS, + json={"title": "PowerContext", "summary": "Repository context", "idempotency_key": "powercontext"}, + ).json()["scope_id"] source = client.post( "/v1/sources/content", headers=_AUTH_HEADERS, json={ - "scope_id": "project:powercontext", + "scope_id": scope_id, "source_id": "managed-skill-evidence", "content": "The contract workflow was reviewed and its validation passed.", }, @@ -193,7 +242,7 @@ def test_review_publishes_an_approved_managed_skill_into_configured_agent_target "/v1/skill/propose", headers=_AUTH_HEADERS, json={ - "scope_id": "project:powercontext", + "scope_id": scope_id, "proposal": { "name": "review-contract-change", "description": "Use when changing the reviewed public contract.", @@ -208,13 +257,13 @@ def test_review_publishes_an_approved_managed_skill_into_configured_agent_target "/v1/artifact-candidates/approve", headers=_AUTH_HEADERS, json={ - "scope_id": "project:powercontext", + "scope_id": scope_id, "candidate_id": candidate["candidate_id"], "expected_version": candidate["version"], }, ).json() selection = { - "scope_id": "project:powercontext", + "scope_id": scope_id, "candidate_id": approved["candidate_id"], "artifact": approved["result_artifact"], } @@ -245,13 +294,13 @@ def test_review_publishes_an_approved_managed_skill_into_configured_agent_target registered = client.post( "/v1/external-skills/list", headers=_AUTH_HEADERS, - json={"scope_id": "project:powercontext", "include_unavailable": False}, + json={"scope_id": scope_id, "include_unavailable": False}, ) revision_source = client.post( "/v1/sources/content", headers=_AUTH_HEADERS, json={ - "scope_id": "project:powercontext", + "scope_id": scope_id, "source_id": "managed-skill-revision-evidence", "content": "The packaged contract must also be verified after regeneration.", }, @@ -260,7 +309,7 @@ def test_review_publishes_an_approved_managed_skill_into_configured_agent_target "/v1/skill/propose", headers=_AUTH_HEADERS, json={ - "scope_id": "project:powercontext", + "scope_id": scope_id, "proposal": { "name": "review-contract-change", "description": "Use when changing the reviewed public contract.", @@ -277,13 +326,13 @@ def test_review_publishes_an_approved_managed_skill_into_configured_agent_target "/v1/artifact-candidates/approve", headers=_AUTH_HEADERS, json={ - "scope_id": "project:powercontext", + "scope_id": scope_id, "candidate_id": revision_candidate["candidate_id"], "expected_version": revision_candidate["version"], }, ).json() revision_selection = { - "scope_id": "project:powercontext", + "scope_id": scope_id, "candidate_id": revision_approved["candidate_id"], "artifact": revision_approved["result_artifact"], } @@ -365,10 +414,7 @@ def test_publish_reports_success_when_post_publish_scan_fails(tmp_path, caplog) codex_skill_root = tmp_path / "repository" / ".agents" / "skills" settings = ServerSettings( auth=BearerAuthConfig(enabled=True, token=SecretStr("dashboard-secret")), - dashboard=DashboardConfig( - enabled=True, - scopes=[DashboardScopeConfig(scope_id="project:powercontext", display_name="PowerContext")], - ), + dashboard=DashboardConfig(enabled=True), database=SQLiteConfig(url=f"sqlite+aiosqlite:///{tmp_path / 'publish-scan-failure.db'}"), external_skills=ExternalSkillsConfig( host_id="dashboard-test", @@ -387,11 +433,12 @@ def test_publish_reports_success_when_post_publish_scan_fails(tmp_path, caplog) app = create_server_app(settings=settings) with TestClient(app) as client, caplog.at_level(logging.WARNING): + scope_id = client.get("/v1/scopes/default", headers=_AUTH_HEADERS).json()["scope_id"] source = client.post( "/v1/sources/content", headers=_AUTH_HEADERS, json={ - "scope_id": "project:powercontext", + "scope_id": scope_id, "source_id": "managed-skill-evidence", "content": "The contract workflow was reviewed and its validation passed.", }, @@ -400,7 +447,7 @@ def test_publish_reports_success_when_post_publish_scan_fails(tmp_path, caplog) "/v1/skill/propose", headers=_AUTH_HEADERS, json={ - "scope_id": "project:powercontext", + "scope_id": scope_id, "proposal": { "name": "review-contract-change", "description": "Use when changing the reviewed public contract.", @@ -415,13 +462,13 @@ def test_publish_reports_success_when_post_publish_scan_fails(tmp_path, caplog) "/v1/artifact-candidates/approve", headers=_AUTH_HEADERS, json={ - "scope_id": "project:powercontext", + "scope_id": scope_id, "candidate_id": candidate["candidate_id"], "expected_version": candidate["version"], }, ).json() selection = { - "scope_id": "project:powercontext", + "scope_id": scope_id, "candidate_id": approved["candidate_id"], "artifact": approved["result_artifact"], } @@ -470,10 +517,7 @@ def test_publish_reports_stale_discovery_when_registry_database_is_unavailable(t codex_skill_root = tmp_path / "repository" / ".agents" / "skills" settings = ServerSettings( auth=BearerAuthConfig(enabled=True, token=SecretStr("dashboard-secret")), - dashboard=DashboardConfig( - enabled=True, - scopes=[DashboardScopeConfig(scope_id="project:powercontext", display_name="PowerContext")], - ), + dashboard=DashboardConfig(enabled=True), database=SQLiteConfig(url=f"sqlite+aiosqlite:///{tmp_path / 'publish-registry-down.db'}"), external_skills=ExternalSkillsConfig( host_id="dashboard-test", @@ -492,11 +536,12 @@ def test_publish_reports_stale_discovery_when_registry_database_is_unavailable(t app = create_server_app(settings=settings) with TestClient(app) as client, caplog.at_level(logging.WARNING): + scope_id = client.get("/v1/scopes/default", headers=_AUTH_HEADERS).json()["scope_id"] source = client.post( "/v1/sources/content", headers=_AUTH_HEADERS, json={ - "scope_id": "project:powercontext", + "scope_id": scope_id, "source_id": "managed-skill-evidence", "content": "The contract workflow was reviewed and its validation passed.", }, @@ -505,7 +550,7 @@ def test_publish_reports_stale_discovery_when_registry_database_is_unavailable(t "/v1/skill/propose", headers=_AUTH_HEADERS, json={ - "scope_id": "project:powercontext", + "scope_id": scope_id, "proposal": { "name": "review-contract-change", "description": "Use when changing the reviewed public contract.", @@ -520,13 +565,13 @@ def test_publish_reports_stale_discovery_when_registry_database_is_unavailable(t "/v1/artifact-candidates/approve", headers=_AUTH_HEADERS, json={ - "scope_id": "project:powercontext", + "scope_id": scope_id, "candidate_id": candidate["candidate_id"], "expected_version": candidate["version"], }, ).json() selection = { - "scope_id": "project:powercontext", + "scope_id": scope_id, "candidate_id": approved["candidate_id"], "artifact": approved["result_artifact"], } @@ -556,22 +601,19 @@ def test_handoff_report_page_is_available_without_the_statistics_dashboard(tmp_p disabled_page = client.get("/handoff-reports") with TestClient(enabled_app) as client: enabled_page = client.get("/handoff-reports") - disabled_skills = client.get("/skills") - disabled_review = client.get("/reviews") - disabled_dashboard = client.get("/") - disabled_dashboard_scopes = client.get("/dashboard/scopes", headers=_AUTH_HEADERS) - protected_scopes = client.post( - "/v1/handoff-reports/scopes/list-known", - json={"limit": 100}, - ) + scopes = client.get("/dashboard/scopes", headers=_AUTH_HEADERS) assert disabled_page.status_code == 404 assert enabled_page.status_code == 200 - assert disabled_skills.status_code == 404 - assert disabled_review.status_code == 404 - assert disabled_dashboard.status_code == 404 - assert disabled_dashboard_scopes.status_code == 404 - assert protected_scopes.status_code == 401 + assert scopes.status_code == 200 + assert scopes.json()[0]["display_name"] == "Default" + assert 'class="server-content" id="handoff-report"' in enabled_page.text + assert 'id="scope-select"' in enabled_page.text + assert 'id="scope-report-rows"' in enabled_page.text + assert 'id="download-report"' in enabled_page.text + assert 'data-i18n-aria-label="handoffSummary"' in enabled_page.text + assert '
' in enabled_page.text + assert "handoff-report.js?v=scope-selection-v2" in enabled_page.text def _handoff_report_settings(database_path: Path, *, enabled: bool) -> ServerSettings: diff --git a/tests/test_handoff_report.py b/tests/test_handoff_report.py new file mode 100644 index 000000000..88fd35a02 --- /dev/null +++ b/tests/test_handoff_report.py @@ -0,0 +1,152 @@ +# Copyright (c) 2026 OceanBase. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +from __future__ import annotations + +from fastapi.testclient import TestClient + +from powercontext.builtin.persistence.sqlite import SQLiteConfig +from powercontext.builtin.runtime.config import HandoffReportConfig +from powercontext.server.factory import create_server_app +from powercontext.server.settings import McpConfig, ServerSettings + + +def test_handoff_report_uses_common_scope_selection(tmp_path) -> None: + app = create_server_app( + settings=ServerSettings( + database=SQLiteConfig(url=f"sqlite+aiosqlite:///{tmp_path / 'report.db'}"), + handoff_report=HandoffReportConfig(enabled=True), + mcp=McpConfig(enabled=False), + ) + ) + + with TestClient(app) as client: + default_scope_id = client.get("/v1/scopes/default").json()["scope_id"] + root_scope_id = _create_scope(client, title="Feature", key="feature") + child_scope_id = _create_scope(client, title="Agent validation", key="validation", parent=root_scope_id) + other_scope_id = _create_scope(client, title="Incident", key="incident") + root_handoff = _commit_handoff(client, root_scope_id, disposition="continuable") + other_handoff = _commit_handoff(client, other_scope_id, disposition="blocked") + + subtree = client.post( + "/v1/handoff-reports/get", + json={"selection": {"mode": "subtree", "root_scope_id": root_scope_id}, "format": "json"}, + ) + exact = client.post( + "/v1/handoff-reports/get", + json={"selection": {"mode": "exact", "scope_ids": [child_scope_id]}, "format": "json"}, + ) + all_scopes = client.post( + "/v1/handoff-reports/get", + json={"selection": {"mode": "all"}, "format": "json"}, + ) + assert subtree.status_code == 200 + subtree_report = subtree.json()["report"] + assert subtree_report["selection"] == {"mode": "subtree", "root_scope_id": root_scope_id} + assert subtree_report["scope_ids"] == [root_scope_id, child_scope_id] + assert [entry["status"] for entry in subtree_report["scopes"]] == ["continuable", "no_handoff"] + assert subtree_report["scopes"][0]["handoff"] == { + "scope_id": root_scope_id, + "artifact": root_handoff, + } + assert subtree_report["scopes"][1]["scope"]["parent_scope_id"] == root_scope_id + assert subtree_report["summary"] == { + "continuable_count": 1, + "blocked_count": 0, + "complete_count": 0, + "no_handoff_count": 1, + } + + assert exact.status_code == 200 + assert exact.json()["report"]["scope_ids"] == [child_scope_id] + assert exact.json()["report"]["scopes"][0]["status"] == "no_handoff" + + assert all_scopes.status_code == 200 + all_report = all_scopes.json()["report"] + assert set(all_report["scope_ids"]) == {default_scope_id, root_scope_id, child_scope_id, other_scope_id} + assert all_report["summary"] == { + "continuable_count": 1, + "blocked_count": 1, + "complete_count": 0, + "no_handoff_count": 2, + } + other_entry = next(entry for entry in all_report["scopes"] if entry["scope"]["scope_id"] == other_scope_id) + assert other_entry["handoff"]["artifact"] == other_handoff + + +def test_handoff_report_markdown_preserves_scope_organization_and_exact_addresses(tmp_path) -> None: + app = create_server_app( + settings=ServerSettings( + database=SQLiteConfig(url=f"sqlite+aiosqlite:///{tmp_path / 'markdown.db'}"), + handoff_report=HandoffReportConfig(enabled=True), + mcp=McpConfig(enabled=False), + ) + ) + + with TestClient(app) as client: + scope_id = _create_scope(client, title="Release review", key="release") + handoff = _commit_handoff(client, scope_id, disposition="complete") + response = client.post( + "/v1/handoff-reports/get", + json={"selection": {"mode": "exact", "scope_ids": [scope_id]}, "format": "markdown"}, + ) + + assert response.status_code == 200 + assert response.headers["content-type"].startswith("text/markdown") + assert "# Handoff Report" in response.text + assert "## Release review" in response.text + assert f"{scope_id}/handoff/{handoff['artifact_id']}@{handoff['revision']}" in response.text + + +def _create_scope(client: TestClient, *, title: str, key: str, parent: str | None = None) -> str: + response = client.post( + "/v1/scopes", + json={ + "title": title, + "summary": f"{title} context", + "parent_scope_id": parent, + "idempotency_key": key, + }, + ) + assert response.status_code == 201 + return response.json()["scope_id"] + + +def _commit_handoff(client: TestClient, scope_id: str, *, disposition: str) -> dict[str, object]: + source = client.post( + "/v1/sources/content", + json={"scope_id": scope_id, "source_id": "handoff-state", "content": f"State is {disposition}."}, + ) + assert source.status_code == 202 + citation = {"kind": "source", "source_ref": source.json()["source"]} + prepared = client.post( + "/v1/handoff/finalize", + json={ + "scope_id": scope_id, + "draft": { + "objective": f"Finish {scope_id}.", + "state": [{"text": f"Current state is {disposition}.", "citations": [citation]}], + "disposition": disposition, + "next_action": {"text": "Verify the exact result.", "citations": [citation]}, + "omissions": [], + }, + }, + ) + assert prepared.status_code == 200 + committed = client.post( + "/v1/handoff/commit", + json={"scope_id": scope_id, "handoff": prepared.json()}, + ) + assert committed.status_code == 200 + return committed.json()["reference"] diff --git a/tests/test_handoff_report_canonical.py b/tests/test_handoff_report_canonical.py deleted file mode 100644 index 0aa903563..000000000 --- a/tests/test_handoff_report_canonical.py +++ /dev/null @@ -1,86 +0,0 @@ -# Copyright (c) 2026 OceanBase. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -import asyncio -from datetime import UTC, datetime - -import pytest - -from powercontext.builtin.handoff_report.canonical import ( - canonical_json_bytes, - finalize_digests, - report_digest, - selection_digest, -) -from powercontext.builtin.handoff_report.models import ProjectDescriptor, WorkstreamDescriptor -from powercontext.builtin.handoff_report.service import HandoffReportService -from tests.test_handoff_report_service import _Adapter, _handoff - - -def _project() -> ProjectDescriptor: - return ProjectDescriptor( - project_id="prj-canonical", - project_key="canonical", - title="Canonical", - timezone="UTC", - version=1, - ) - - -def _workstream() -> WorkstreamDescriptor: - return WorkstreamDescriptor( - scope_id="scope-canonical", - project_id="prj-canonical", - title="Canonical", - kind="feature", - version=1, - ) - - -def _report(): - async def scenario(): - return await HandoffReportService(_Adapter({"scope-canonical": _handoff()})).generate( - _project(), - (_workstream(),), - include_evidence_checks=False, - generated_at=datetime(2026, 8, 6, tzinfo=UTC), - ) - - return asyncio.run(scenario()) - - -def test_canonical_json_normalizes_nfc_and_rejects_floats() -> None: - assert canonical_json_bytes({"text": "Cafe\u0301"}) == canonical_json_bytes({"text": "Café"}) - - with pytest.raises(ValueError, match="floating-point"): - canonical_json_bytes({"value": 1.5}) - - -def test_selection_digest_is_locale_independent_but_report_digest_is_not() -> None: - report = _report() - english = report.model_copy(update={"locale": "en"}) - - assert report.selection_digest == selection_digest(report) - assert report.selection_digest == selection_digest(english) - assert report.report_digest == report_digest(report) - assert report.report_digest != report_digest(english) - assert finalize_digests(english).selection_digest == report.selection_digest - - -def test_digest_fields_are_stable_when_a_report_is_revalidated() -> None: - report = _report() - restored = type(report).model_validate(report.model_dump(by_alias=True)) - - assert restored.selection_digest == report.selection_digest - assert restored.report_digest == report.report_digest diff --git a/tests/test_handoff_report_catalog.py b/tests/test_handoff_report_catalog.py deleted file mode 100644 index 2bd8f4eac..000000000 --- a/tests/test_handoff_report_catalog.py +++ /dev/null @@ -1,248 +0,0 @@ -# Copyright (c) 2026 OceanBase. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -from __future__ import annotations - -import asyncio -from datetime import UTC, datetime - -import pytest - -from powercontext.builtin.handoff_report import ( - HandoffReportCatalog, - ProjectConflictError, - ProjectDescriptor, - ProjectNotFoundError, - ScopeAlreadyGroupedError, - WorkstreamConflictError, - WorkstreamNotFoundError, -) -from powercontext.builtin.handoff_report.sqlite import HANDOFF_REPORT_TABLES -from powercontext.builtin.persistence.sqlite import SQLiteConfig, SQLiteProfile - - -def _time(day: int, hour: int = 0) -> datetime: - return datetime(2026, 8, day, hour, tzinfo=UTC) - - -def _updated_project(project: ProjectDescriptor, **changes) -> ProjectDescriptor: - values = project.model_dump(by_alias=True) - values.update(changes) - return ProjectDescriptor.model_validate(values) - - -def test_catalog_creates_projects_workstreams_and_resolves_scope_membership() -> None: - async def scenario() -> None: - catalog = HandoffReportCatalog(project_id_factory=lambda: "prj-1") - async with ( - SQLiteProfile.open(SQLiteConfig(), tables=HANDOFF_REPORT_TABLES) as profile, - profile.database.transaction() as connection, - ): - project = await catalog.create_project( - connection, - project_key="powercontext", - title="PowerContext", - timezone="Asia/Shanghai", - effective_at=_time(1), - ) - workstream = await catalog.register_workstream( - connection, - project_id=project.project_id, - scope_id="scope-report", - key="handoff-report", - title="Handoff Report", - kind="feature", - effective_at=_time(1, 1), - ) - - assert await catalog.get_project(connection, "prj-1") == project - assert await catalog.get_workstream(connection, "scope-report") == workstream - assert await catalog.project_for_scope(connection, "scope-report") == project - assert (await catalog.list_workstreams(connection, "prj-1")).items == (workstream,) - - asyncio.run(scenario()) - - -def test_project_and_workstream_updates_use_cas_and_preserve_revision_history() -> None: - async def scenario() -> None: - catalog = HandoffReportCatalog(project_id_factory=lambda: "prj-1") - async with ( - SQLiteProfile.open(SQLiteConfig(), tables=HANDOFF_REPORT_TABLES) as profile, - profile.database.transaction() as connection, - ): - project = await catalog.create_project( - connection, - project_key="powercontext", - title="PowerContext", - timezone="UTC", - effective_at=_time(1), - ) - workstream = await catalog.register_workstream( - connection, - project_id=project.project_id, - scope_id="scope-report", - title="Initial title", - kind="feature", - effective_at=_time(1, 1), - ) - - updated_project = _updated_project( - project, - title="Renamed Project", - version=2, - ) - assert ( - await catalog.update_project( - connection, - updated_project, - expected_version=1, - effective_at=_time(2), - ) - == updated_project - ) - - updated_workstream = workstream.model_copy(update={"title": "Renamed Workstream", "version": 2}) - assert ( - await catalog.update_workstream( - connection, - updated_workstream, - expected_version=1, - effective_at=_time(2, 1), - ) - == updated_workstream - ) - - assert await catalog.get_project(connection, "prj-1") == updated_project - assert await catalog.get_workstream(connection, "scope-report") == updated_workstream - assert await catalog.project_revision(connection, "prj-1", 1) == project - assert await catalog.workstream_revision(connection, "scope-report", 1) == workstream - assert (await catalog.project_at(connection, "prj-1", _time(1, 12))) == project - assert (await catalog.project_at(connection, "prj-1", _time(2, 12))) == updated_project - assert (await catalog.workstream_at(connection, "scope-report", _time(1, 12))) == workstream - assert (await catalog.workstream_at(connection, "scope-report", _time(2, 12))) == updated_workstream - - with pytest.raises(ProjectConflictError) as project_conflict: - await catalog.update_project( - connection, - _updated_project(project, title="Stale", version=2), - expected_version=1, - ) - assert project_conflict.value.current_version == 2 - - with pytest.raises(WorkstreamConflictError) as workstream_conflict: - await catalog.update_workstream( - connection, - workstream.model_copy(update={"title": "Stale", "version": 2}), - expected_version=1, - ) - assert workstream_conflict.value.current_version == 2 - - asyncio.run(scenario()) - - -def test_catalog_enforces_project_key_workstream_key_and_scope_identity_uniqueness() -> None: - async def scenario() -> None: - project_ids = iter(("prj-1", "prj-2", "prj-3")) - catalog = HandoffReportCatalog(project_id_factory=project_ids.__next__) - async with ( - SQLiteProfile.open(SQLiteConfig(), tables=HANDOFF_REPORT_TABLES) as profile, - profile.database.transaction() as connection, - ): - first = await catalog.create_project( - connection, - project_key="same-key", - title="First", - timezone="UTC", - ) - with pytest.raises(ProjectConflictError, match="already in use"): - await catalog.create_project( - connection, - project_key="same-key", - title="Duplicate", - timezone="UTC", - ) - - await catalog.register_workstream( - connection, - project_id=first.project_id, - scope_id="scope-1", - key="same-workstream-key", - title="First Workstream", - kind="feature", - ) - with pytest.raises(WorkstreamConflictError, match="already in use"): - await catalog.register_workstream( - connection, - project_id=first.project_id, - scope_id="scope-2", - key="same-workstream-key", - title="Duplicate Key", - kind="feature", - ) - - second = await catalog.create_project( - connection, - project_key="second-key", - title="Second", - timezone="UTC", - ) - with pytest.raises(ScopeAlreadyGroupedError, match="scope-1"): - await catalog.register_workstream( - connection, - project_id=second.project_id, - scope_id="scope-1", - title="Moved Scope", - kind="feature", - ) - - with pytest.raises(ProjectNotFoundError): - await catalog.get_project(connection, "missing") - with pytest.raises(WorkstreamNotFoundError): - await catalog.get_workstream(connection, "missing") - - asyncio.run(scenario()) - - -def test_catalog_lists_with_cursor_and_excludes_archived_by_default() -> None: - async def scenario() -> None: - ids = iter(("prj-a", "prj-b", "prj-c")) - catalog = HandoffReportCatalog(project_id_factory=ids.__next__) - async with ( - SQLiteProfile.open(SQLiteConfig(), tables=HANDOFF_REPORT_TABLES) as profile, - profile.database.transaction() as connection, - ): - projects = tuple([ - await catalog.create_project( - connection, - project_key=f"project-{suffix}", - title=f"Project {suffix}", - timezone="UTC", - ) - for suffix in ("a", "b", "c") - ]) - archived = _updated_project(projects[1], catalog_state="archived", version=2) - await catalog.update_project(connection, archived, expected_version=1) - - first_page = await catalog.list_projects(connection, limit=1) - assert tuple(item.project_id for item in first_page.items) == ("prj-a",) - assert first_page.next_cursor == "prj-a" - - second_page = await catalog.list_projects(connection, cursor=first_page.next_cursor, limit=1) - assert tuple(item.project_id for item in second_page.items) == ("prj-c",) - assert second_page.next_cursor is None - - all_projects = await catalog.list_projects(connection, include_archived=True) - assert tuple(item.project_id for item in all_projects.items) == ("prj-a", "prj-b", "prj-c") - - asyncio.run(scenario()) diff --git a/tests/test_handoff_report_http.py b/tests/test_handoff_report_http.py deleted file mode 100644 index 40554d928..000000000 --- a/tests/test_handoff_report_http.py +++ /dev/null @@ -1,289 +0,0 @@ -# Copyright (c) 2026 OceanBase. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -import sqlite3 - -from fastapi.testclient import TestClient - -from powercontext.builtin.persistence.sqlite import SQLiteConfig -from powercontext.builtin.runtime import HandoffReportConfig -from powercontext.server.app import create_app -from powercontext.server.factory import create_server_app -from powercontext.server.settings import McpConfig, ServerSettings - - -def test_handoff_report_catalog_and_json_projection_are_available_over_http(tmp_path) -> None: - database_path = tmp_path / "report.db" - app = create_server_app( - settings=ServerSettings( - database=SQLiteConfig(url=f"sqlite+aiosqlite:///{database_path}"), - handoff_report=HandoffReportConfig(enabled=True), - mcp=McpConfig(enabled=False), - ) - ) - - with TestClient(app) as client: - created = client.post( - "/v1/handoff-reports/projects/create", - json={"project_key": "powercontext", "title": "PowerContext"}, - ) - assert created.status_code == 201 - project = created.json() - fetched_project = client.post( - "/v1/handoff-reports/projects/get", - json={"project_id": project["project_id"]}, - ) - updated_project_payload = {**project, "title": "PowerContext Reports", "version": 2} - updated_project = client.post( - "/v1/handoff-reports/projects/update", - json={"project": updated_project_payload, "expected_version": 1}, - ) - - registered = client.post( - "/v1/handoff-reports/workstreams/register", - json={ - "project_id": project["project_id"], - "scope_id": "scope-report", - "title": "Handoff Report", - "kind": "feature", - }, - ) - assert registered.status_code == 201 - workstream = registered.json() - updated_workstream = client.post( - "/v1/handoff-reports/workstreams/update", - json={ - "workstream": {**workstream, "title": "Handoff Report API", "version": 2}, - "expected_version": 1, - }, - ) - - recorded = client.post( - "/v1/handoff-reports/activities/record", - json={ - "project_id": project["project_id"], - "scope_id": "scope-report", - "source": "git_commit", - "source_event_id": "git:abc123", - "occurred_at": "2026-08-07T01:00:00Z", - "time_basis": "source_reported", - "title": "Implement report APIs", - }, - ) - repeated = client.post( - "/v1/handoff-reports/activities/record", - json={ - "project_id": project["project_id"], - "scope_id": "scope-report", - "source": "git_commit", - "source_event_id": "git:abc123", - "occurred_at": "2026-08-07T01:00:00Z", - "time_basis": "source_reported", - "title": "Implement report APIs", - }, - ) - previous_activity = client.post( - "/v1/handoff-reports/activities/record", - json={ - "project_id": project["project_id"], - "scope_id": "scope-report", - "source": "git_commit", - "source_event_id": "git:previous", - "occurred_at": "2026-08-05T01:00:00Z", - "time_basis": "source_reported", - "title": "Prepare report APIs", - }, - ) - activities = client.post( - "/v1/handoff-reports/activities/list", - json={"project_id": project["project_id"]}, - ) - attached = client.post( - "/v1/handoff-reports/workspace-bindings/attach", - json={ - "workspace_instance_id": "workspace-1", - "project_id": project["project_id"], - "repository_ref": { - "provider": "github", - "repository_id": "oceanbase/powercontext", - "normalized_remote": "https://github.com/oceanbase/powercontext.git", - "subpath": ".", - }, - "expected_version": None, - }, - ) - binding = client.post( - "/v1/handoff-reports/workspace-bindings/get", - json={"workspace_instance_id": "workspace-1"}, - ) - - prepared_for_report = client.post( - "/v1/work/handoffs/prepare-current", - json={ - "scope_id": "scope-report", - "source_id": "handoff-report-boundary", - "handoff": { - "schema": "powercontext.current-work-handoff.v1", - "trust": "untrusted_input", - "objective": "Continue the Handoff Report work.", - "state": [{"text": "Scope reports are available.", "basis": "declared", "evidence": []}], - "disposition": "continuable", - "next_action": None, - "omissions": [], - }, - }, - ) - assert prepared_for_report.status_code == 200 - committed = client.post( - "/v1/handoff/commit", - json={"scope_id": "scope-report", "handoff": prepared_for_report.json()["handoff"]}, - ) - - listed = client.post("/v1/handoff-reports/projects/list", json={}) - listed_scopes = client.post("/v1/handoff-reports/scopes/list-known", json={}) - report_response = client.post( - "/v1/handoff-reports/get", - json={ - "scope_id": "scope-report", - "include_evidence_checks": False, - "format": "json", - }, - ) - periodic_response = client.post( - "/v1/handoff-reports/get", - json={ - "scope_id": "scope-report", - "include_evidence_checks": False, - "format": "json", - "period": { - "start": "2026-08-06T00:00:00Z", - "end": "2026-08-08T00:00:00Z", - "timezone": "Asia/Shanghai", - "compare_to_previous_period": True, - }, - }, - ) - markdown_response = client.post( - "/v1/handoff-reports/get", - json={ - "scope_id": "scope-report", - "include_evidence_checks": False, - "format": "markdown", - "locale": "en", - }, - ) - default_response = client.post( - "/v1/handoff-reports/get", - json={"scope_id": "scope-report", "include_evidence_checks": False}, - ) - downloaded = client.post( - "/v1/handoff-reports/get", - json={ - "scope_id": "scope-report", - "include_evidence_checks": False, - "format": "markdown", - "download": True, - }, - ) - detached = client.post( - "/v1/handoff-reports/workspace-bindings/detach", - json={"workspace_instance_id": "workspace-1", "expected_version": 1}, - ) - - assert listed.status_code == 200 - assert committed.status_code == 200 - assert listed_scopes.status_code == 200 - assert listed_scopes.json() == {"items": [{"scope_id": "scope-report"}], "next_cursor": None} - assert fetched_project.json() == project - assert updated_project.status_code == 200 - assert updated_project.json()["version"] == 2 - assert updated_workstream.status_code == 200 - assert updated_workstream.json()["version"] == 2 - assert listed.json()["items"][0]["project_id"] == project["project_id"] - assert report_response.status_code == 200 - body = report_response.json() - assert body["format"] == "json" - assert body["report"]["project"]["project_id"] == "unused" - assert body["report"]["workstreams"][0]["workstream"]["scope_id"] == "scope-report" - assert body["report"]["summary"]["continuable_count"] == 1 - assert body["report"]["coverage"]["activity_coverage"] == "not_configured" - assert body["selection_digest"].startswith("sha256:") - assert body["report_digest"].startswith("sha256:") - assert markdown_response.status_code == 200 - assert markdown_response.headers["content-type"].startswith("text/markdown") - assert "# PowerContext Project Handoff Report" in markdown_response.text - assert 'scope_id: "scope-report"' in markdown_response.text - assert "project_id:" not in markdown_response.text - assert default_response.status_code == 200 - assert default_response.headers["content-type"].startswith("text/markdown") - assert "# PowerContext 项目交接报告" in default_response.text - assert downloaded.status_code == 200 - assert downloaded.headers["content-type"].startswith("text/markdown") - assert downloaded.headers["content-disposition"] == 'attachment; filename="handoff-report.md"' - assert downloaded.headers["x-powercontext-selection-digest"].startswith("sha256:") - assert "# PowerContext 项目交接报告" in downloaded.text - assert recorded.status_code == 201 - assert previous_activity.status_code == 201 - assert repeated.status_code == 201 - assert repeated.json() == recorded.json() - assert recorded.json()["cursor"] == 1 - assert activities.status_code == 200 - assert activities.json()["high_watermark"] == 2 - assert [item["source_event_id"] for item in activities.json()["items"]] == ["git:abc123", "git:previous"] - assert periodic_response.status_code == 200 - periodic = periodic_response.json()["report"] - assert periodic["report_kind"] == "periodic" - assert periodic["normalized_period"]["timezone"] == "Asia/Shanghai" - assert periodic["period_comparison"] is None - assert attached.status_code == 200 - assert binding.status_code == 200 - assert binding.json() == attached.json() - assert detached.status_code == 200 - assert detached.json()["state"] == "detached" - assert detached.json()["version"] == 2 - with sqlite3.connect(database_path) as connection: - report_tables = connection.execute( - "SELECT name FROM sqlite_master WHERE type = 'table' AND name LIKE 'pc_handoff_report_%'" - ).fetchall() - assert report_tables - - -def test_handoff_report_routes_are_not_registered_when_feature_is_disabled() -> None: - response = TestClient(create_app()).post( - "/v1/handoff-reports/projects/list", - json={}, - ) - - assert response.status_code == 404 - assert "/v1/handoff-reports/projects/list" not in create_app().openapi()["paths"] - - -def test_disabled_handoff_report_does_not_create_report_tables(tmp_path) -> None: - database_path = tmp_path / "without-report.db" - app = create_server_app( - settings=ServerSettings( - database=SQLiteConfig(url=f"sqlite+aiosqlite:///{database_path}"), - mcp=McpConfig(enabled=False), - handoff_report=HandoffReportConfig(enabled=False), - ) - ) - - with TestClient(app): - pass - - with sqlite3.connect(database_path) as connection: - report_tables = connection.execute( - "SELECT name FROM sqlite_master WHERE type = 'table' AND name LIKE 'pc_handoff_report_%'" - ).fetchall() - assert report_tables == [] diff --git a/tests/test_handoff_report_models.py b/tests/test_handoff_report_models.py deleted file mode 100644 index 781409b93..000000000 --- a/tests/test_handoff_report_models.py +++ /dev/null @@ -1,199 +0,0 @@ -# Copyright (c) 2026 OceanBase. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -from datetime import UTC, datetime, timedelta, timezone - -import pytest -from pydantic import ValidationError - -from powercontext.artifacts import ArtifactRef -from powercontext.builtin.handoff_report import ( - ActivityAgent, - ActivityVcsContext, - ExternalReference, - ProjectDescriptor, - ReportActivityEvent, - ReportSelectionEntry, - WorkstreamDescriptor, - activity_sort_key, - normalized_sort_text, - selection_sort_key, - workstream_sort_key, -) - -NOW = datetime(2026, 8, 5, 4, 0, tzinfo=UTC) - - -def _project(**changes) -> ProjectDescriptor: - values = { - "project_id": "prj_01K", - "project_key": "powercontext", - "title": "PowerContext", - "timezone": "Asia/Shanghai", - "version": 1, - } - values.update(changes) - return ProjectDescriptor.model_validate(values) - - -def _workstream(**changes) -> WorkstreamDescriptor: - values = { - "scope_id": "scope-report", - "project_id": "prj_01K", - "title": "Handoff Report", - "kind": "feature", - "version": 1, - } - values.update(changes) - return WorkstreamDescriptor.model_validate(values) - - -def _activity(**changes) -> ReportActivityEvent: - values = { - "event_id": "evt-1", - "project_id": "prj_01K", - "source": "git_commit", - "source_event_id": "commit-abc", - "occurred_at": NOW - timedelta(hours=1), - "observed_at": NOW, - "time_basis": "source_reported", - } - values.update(changes) - return ReportActivityEvent.model_validate(values) - - -def test_project_descriptor_is_versioned_frozen_and_serializes_schema_alias() -> None: - project = _project(description="A durable project handoff", default_locale="en") - - assert project.model_dump(by_alias=True)["schema"] == "powercontext.project.v1" - assert project.default_locale == "en" - with pytest.raises(ValidationError): - project.title = "Changed" - - -@pytest.mark.parametrize("timezone_name", ["", " Asia/Shanghai", "Not/A_Timezone"]) -def test_project_descriptor_rejects_invalid_timezone(timezone_name: str) -> None: - with pytest.raises(ValidationError): - _project(timezone=timezone_name) - - -def test_workstream_descriptor_reuses_scope_identity_and_bounds_metadata() -> None: - issue = ExternalReference(kind="issue", provider="github", external_id="42") - workstream = _workstream(key="handoff-report", external_refs=(issue,), labels=("report", "v1")) - - assert workstream.scope_id == "scope-report" - assert workstream.external_refs == (issue,) - - with pytest.raises(ValidationError, match="labels must be unique"): - _workstream(labels=("report", "report")) - with pytest.raises(ValidationError, match="external references must be unique"): - _workstream(external_refs=(issue, issue)) - - -def test_activity_event_keeps_observation_untrusted_and_explicitly_timed() -> None: - event = _activity( - scope_id="scope-report", - agent=ActivityAgent(provider="codex", label="agent-1"), - session_id="session-1", - vcs_context=ActivityVcsContext(branch="handoff_report", head_revision="abc123"), - ) - - assert event.trust == "untrusted_observation" - assert event.effective_period_time() == NOW - timedelta(hours=1) - assert event.model_dump(by_alias=True)["schema"] == "powercontext.handoff-report-activity.v1" - - -def test_activity_event_does_not_invent_period_time() -> None: - current = _activity( - source="git_worktree", - source_event_id="worktree-current", - occurred_at=None, - time_basis="current_only", - ) - unknown = _activity( - source="coding_session", - source_event_id="unknown-session", - occurred_at=None, - time_basis="unknown", - ) - - assert current.effective_period_time() is None - assert unknown.effective_period_time() is None - - -def test_activity_event_validates_timestamp_basis_and_utc_observation() -> None: - with pytest.raises(ValidationError, match="must contain occurred_at"): - _activity(occurred_at=None) - with pytest.raises(ValidationError, match="only valid for source-reported"): - _activity(time_basis="first_seen") - with pytest.raises(ValidationError, match="observed_at must be UTC"): - _activity(observed_at=NOW.astimezone(timezone(timedelta(hours=8)))) - with pytest.raises(ValidationError, match="occurred_at must include a UTC offset"): - _activity(occurred_at=datetime(2026, 8, 5, 3, 0)) # noqa: DTZ001 - intentional invalid input - - -def test_report_selection_entry_requires_exact_handoff_or_explicit_absence() -> None: - handoff_ref = ArtifactRef(family="handoff", artifact_id="handoff-1", revision=2) - selected = ReportSelectionEntry( - scope_id="scope-report", - workstream_revision=3, - status="selected", - handoff_ref=handoff_ref, - ) - absent = ReportSelectionEntry(scope_id="scope-empty", workstream_revision=1, status="no_handoff") - - assert selected.handoff_ref == handoff_ref - assert absent.handoff_ref is None - with pytest.raises(ValidationError, match="must contain an exact Handoff"): - ReportSelectionEntry(scope_id="scope-report", workstream_revision=3, status="selected") - with pytest.raises(ValidationError, match="cannot contain"): - ReportSelectionEntry( - scope_id="scope-report", - workstream_revision=3, - status="no_handoff", - handoff_ref=handoff_ref, - ) - with pytest.raises(ValidationError, match="Handoff family"): - ReportSelectionEntry( - scope_id="scope-report", - workstream_revision=3, - status="selected", - handoff_ref=ArtifactRef(family="memory", artifact_id="memory-1", revision=1), - ) - - -def test_stable_sort_helpers_use_normalized_title_scope_and_effective_time() -> None: - composed = _workstream(scope_id="scope-2", title="Café") - decomposed = _workstream(scope_id="scope-1", title="Cafe\u0301") - late = _activity(event_id="evt-late", source_event_id="late", occurred_at=NOW) - early = _activity(event_id="evt-early", source_event_id="early", occurred_at=NOW - timedelta(days=1)) - current = _activity( - event_id="evt-current", - source="git_worktree", - source_event_id="current", - occurred_at=None, - time_basis="current_only", - ) - selected = ReportSelectionEntry( - scope_id="scope-2", - workstream_revision=1, - status="selected", - handoff_ref=ArtifactRef(family="handoff", artifact_id="handoff-1", revision=1), - ) - absent = ReportSelectionEntry(scope_id="scope-1", workstream_revision=1, status="no_handoff") - - assert normalized_sort_text(composed.title) == normalized_sort_text(decomposed.title) - assert sorted((composed, decomposed), key=workstream_sort_key) == [decomposed, composed] - assert sorted((current, late, early), key=activity_sort_key) == [early, late, current] - assert sorted((selected, absent), key=selection_sort_key) == [absent, selected] diff --git a/tests/test_handoff_report_repository.py b/tests/test_handoff_report_repository.py deleted file mode 100644 index 73c8bfd27..000000000 --- a/tests/test_handoff_report_repository.py +++ /dev/null @@ -1,280 +0,0 @@ -# Copyright (c) 2026 OceanBase. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -from __future__ import annotations - -import asyncio -from datetime import UTC, datetime, timedelta -from typing import Any - -import pytest - -from powercontext.builtin.handoff_report.models import ReportActivityEvent, ReportActivitySource, ReportTimeBasis -from powercontext.builtin.handoff_report.repository import ( - ActivityEventConflictError, - InvalidActivityEventError, - InvalidActivityRepositoryArgumentError, -) -from powercontext.builtin.handoff_report.sqlite import HANDOFF_REPORT_TABLES, SQLiteActivityEventRepository -from powercontext.builtin.persistence.sqlite import SQLiteConfig, SQLiteProfile - - -def _event( - event_id: str, - *, - project_id: str = "project-1", - source: ReportActivitySource = "git_commit", - source_event_id: str | None = None, - observed_at: datetime, - occurred_at: datetime | None = None, - time_basis: ReportTimeBasis = "source_reported", - title: str | None = None, -) -> ReportActivityEvent: - return ReportActivityEvent( - event_id=event_id, - project_id=project_id, - source=source, - source_event_id=source_event_id or event_id, - observed_at=observed_at, - occurred_at=occurred_at, - time_basis=time_basis, - title=title, - ) - - -def test_activity_store_is_idempotent_and_rejects_payload_conflicts() -> None: - async def scenario() -> None: - now = datetime(2026, 8, 5, 10, tzinfo=UTC) - repository = SQLiteActivityEventRepository() - event = _event("event-1", observed_at=now, occurred_at=now - timedelta(hours=1)) - async with SQLiteProfile.open(SQLiteConfig(), tables=HANDOFF_REPORT_TABLES) as profile: - async with profile.database.transaction() as connection: - first = await repository.record(connection, event) - repeated = await repository.record(connection, event) - assert repeated == first - assert first.cursor == 1 - assert first.payload["event_id"] == "event-1" - - conflicting = event.model_copy(update={"title": "different"}) - with pytest.raises(ActivityEventConflictError): - async with profile.database.transaction() as connection: - await repository.record(connection, conflicting) - - asyncio.run(scenario()) - - -def test_idempotent_retry_ignores_only_server_owned_identity_and_observation_time() -> None: - async def scenario() -> None: - now = datetime(2026, 8, 5, 10, tzinfo=UTC) - repository = SQLiteActivityEventRepository() - first_event = _event( - "server-event-1", - source_event_id="git:stable", - observed_at=now, - occurred_at=now - timedelta(hours=1), - title="Implemented report storage", - ) - retry = first_event.model_copy( - update={ - "event_id": "server-event-2", - "observed_at": now + timedelta(minutes=5), - } - ) - async with SQLiteProfile.open(SQLiteConfig(), tables=HANDOFF_REPORT_TABLES) as profile: - async with profile.database.transaction() as connection: - first = await repository.record(connection, first_event) - async with profile.database.transaction() as connection: - repeated = await repository.record(connection, retry) - assert await repository.high_watermark(connection, "project-1") == 1 - - assert repeated == first - assert repeated.event_id == "server-event-1" - assert repeated.observed_at == now - assert repeated.payload["event_id"] == "server-event-1" - - semantic_changes = ( - retry.model_copy(update={"title": "Different activity"}), - retry.model_copy(update={"occurred_at": now - timedelta(hours=2)}), - ) - for changed in semantic_changes: - with pytest.raises(ActivityEventConflictError): - async with profile.database.transaction() as connection: - await repository.record(connection, changed) - - asyncio.run(scenario()) - - -def test_record_revalidates_constructed_payload_before_indexing() -> None: - async def scenario() -> None: - now = datetime(2026, 8, 5, 10, tzinfo=UTC) - invalid = ReportActivityEvent.model_construct( - event_id="event-invalid", - project_id="project-1", - source="git_commit", - source_event_id="git:invalid", - occurred_at=now, - observed_at=now, - time_basis="host_observed", - trust="untrusted_observation", - ) - repository = SQLiteActivityEventRepository() - async with SQLiteProfile.open(SQLiteConfig(), tables=HANDOFF_REPORT_TABLES) as profile: - with pytest.raises(InvalidActivityEventError): - async with profile.database.transaction() as connection: - await repository.record(connection, invalid) - async with profile.database.transaction() as connection: - assert await repository.high_watermark(connection, "project-1") == 0 - - asyncio.run(scenario()) - - -def test_single_repository_serializes_concurrent_sqlite_records(tmp_path) -> None: - async def scenario() -> None: - now = datetime(2026, 8, 5, 10, tzinfo=UTC) - repository = SQLiteActivityEventRepository() - ready = asyncio.Event() - config = SQLiteConfig(url=f"sqlite+aiosqlite:///{tmp_path / 'activity.db'}") - - async with SQLiteProfile.open(config, tables=HANDOFF_REPORT_TABLES) as profile: - - async def record_one(index: int): - await ready.wait() - async with profile.database.transaction() as connection: - return await repository.record( - connection, - _event( - f"event-{index}", - observed_at=now, - occurred_at=now + timedelta(seconds=index), - ), - ) - - tasks = tuple(asyncio.create_task(record_one(index)) for index in range(12)) - ready.set() - stored = await asyncio.gather(*tasks) - - assert sorted(item.cursor for item in stored) == list(range(1, 13)) - async with profile.database.transaction() as connection: - assert await repository.high_watermark(connection, "project-1") == 12 - assert len(await repository.list(connection, "project-1")) == 12 - - asyncio.run(scenario()) - - -def test_activity_store_lists_by_project_period_source_and_frozen_cursor() -> None: - async def scenario() -> None: - now = datetime(2026, 8, 5, 10, tzinfo=UTC) - repository = SQLiteActivityEventRepository() - events = ( - _event("old", observed_at=now, occurred_at=now - timedelta(days=8)), - _event("period-git", observed_at=now, occurred_at=now - timedelta(days=2)), - _event( - "period-session", - observed_at=now - timedelta(days=1), - source="coding_session", - time_basis="host_observed", - ), - _event( - "current", - observed_at=now, - source="git_worktree", - time_basis="current_only", - ), - _event( - "other-project", - project_id="project-2", - observed_at=now, - occurred_at=now - timedelta(days=1), - ), - ) - async with SQLiteProfile.open(SQLiteConfig(), tables=HANDOFF_REPORT_TABLES) as profile: - async with profile.database.transaction() as connection: - for event in events: - await repository.record(connection, event) - frozen_cursor = await repository.high_watermark(connection, "project-1") - assert frozen_cursor == 4 - page = await repository.list( - connection, - "project-1", - period_start=now - timedelta(days=7), - period_end=now + timedelta(seconds=1), - sources=("git_commit", "coding_session"), - through_cursor=frozen_cursor, - ) - cursor_page = await repository.list( - connection, - "project-1", - after_cursor=2, - through_cursor=frozen_cursor, - limit=1, - ) - assert [item.event_id for item in page] == ["period-git", "period-session"] - assert [item.cursor for item in page] == [2, 3] - assert [item.event_id for item in cursor_page] == ["period-session"] - - asyncio.run(scenario()) - - -def test_list_requires_strict_integer_cursor_and_limit_values() -> None: - async def scenario() -> None: - repository = SQLiteActivityEventRepository() - async with ( - SQLiteProfile.open(SQLiteConfig(), tables=HANDOFF_REPORT_TABLES) as profile, - profile.database.transaction() as connection, - ): - for invalid in (True, 1.0, "1"): - invalid_value: Any = invalid - with pytest.raises(InvalidActivityRepositoryArgumentError, match="after_cursor"): - await repository.list(connection, "project-1", after_cursor=invalid_value) - with pytest.raises(InvalidActivityRepositoryArgumentError, match="through_cursor"): - await repository.list(connection, "project-1", through_cursor=invalid_value) - with pytest.raises(InvalidActivityRepositoryArgumentError, match="limit"): - await repository.list(connection, "project-1", limit=invalid_value) - - asyncio.run(scenario()) - - -def test_retention_purge_is_project_scoped_and_does_not_regress_cursor() -> None: - async def scenario() -> None: - now = datetime(2026, 8, 5, 10, tzinfo=UTC) - repository = SQLiteActivityEventRepository() - async with SQLiteProfile.open(SQLiteConfig(), tables=HANDOFF_REPORT_TABLES) as profile: - async with profile.database.transaction() as connection: - await repository.record( - connection, - _event("expired", observed_at=now - timedelta(days=91), occurred_at=now - timedelta(days=91)), - ) - await repository.record(connection, _event("kept", observed_at=now, occurred_at=now)) - await repository.record( - connection, - _event( - "other-expired", - project_id="project-2", - observed_at=now - timedelta(days=91), - occurred_at=now - timedelta(days=91), - ), - ) - assert await repository.purge(connection, "project-1", now - timedelta(days=90)) == 1 - assert await repository.high_watermark(connection, "project-1") == 2 - remaining = await repository.list(connection, "project-1") - other = await repository.list(connection, "project-2") - assert [item.event_id for item in remaining] == ["kept"] - assert [item.event_id for item in other] == ["other-expired"] - - asyncio.run(scenario()) - - -def test_all_report_table_names_use_the_isolated_prefix() -> None: - assert HANDOFF_REPORT_TABLES - assert all(table.name.startswith("pc_handoff_report_") for table in HANDOFF_REPORT_TABLES) diff --git a/tests/test_handoff_report_selection.py b/tests/test_handoff_report_selection.py deleted file mode 100644 index 7e54b6dca..000000000 --- a/tests/test_handoff_report_selection.py +++ /dev/null @@ -1,208 +0,0 @@ -# Copyright (c) 2026 OceanBase. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -from __future__ import annotations - -import asyncio -from collections import deque - -import pytest - -from powercontext.artifacts import ArtifactRef -from powercontext.builtin.artifacts.handoff import ( - Handoff, - HandoffContent, - HandoffEvidenceCheck, - HandoffSourceCitation, - HandoffStatement, -) -from powercontext.builtin.handoff_report.adapters import RuntimeHandoffReadAdapter -from powercontext.builtin.handoff_report.errors import ( - HandoffReportBusyError, - HandoffReportEvidenceCheckUnavailableError, -) -from powercontext.builtin.handoff_report.models import WorkstreamDescriptor -from powercontext.builtin.handoff_report.selection import select_optimistic_stable_handoffs -from powercontext.sources import SourceRef - - -def _workstream(scope_id: str, *, version: int = 1) -> WorkstreamDescriptor: - return WorkstreamDescriptor( - scope_id=scope_id, - project_id="prj-1", - title=f"Workstream {scope_id}", - kind="feature", - version=version, - ) - - -def _handoff(revision: int, *, artifact_id: str = "handoff") -> Handoff: - citation = HandoffSourceCitation( - source_ref=SourceRef(source_type="content", source_id="source-1"), - ) - return Handoff( - artifact_id=artifact_id, - revision=revision, - content=HandoffContent( - objective="Implement Handoff Report.", - state=( - HandoffStatement( - text=f"Handoff revision {revision} is committed.", - citations=(citation,), - ), - ), - disposition="continuable", - ), - ) - - -class _FakeReadAdapter: - def __init__(self, values: dict[str, tuple[Handoff | None, ...]]) -> None: - self._values = {scope_id: deque(items) for scope_id, items in values.items()} - self.calls: list[str] = [] - - async def latest(self, scope_id: str, /) -> Handoff | None: - self.calls.append(scope_id) - values = self._values[scope_id] - return values.popleft() if len(values) > 1 else values[0] - - async def get(self, scope_id: str, reference: ArtifactRef, /) -> Handoff: - del scope_id, reference - raise NotImplementedError - - async def revisions(self, scope_id: str, /) -> tuple[Handoff, ...]: - del scope_id - raise NotImplementedError - - async def check_evidence( - self, - scope_id: str, - reference: ArtifactRef, - /, - ) -> tuple[HandoffEvidenceCheck, ...]: - del scope_id, reference - raise NotImplementedError - - -def test_optimistic_selection_freezes_stable_heads_in_scope_order() -> None: - async def scenario() -> None: - adapter = _FakeReadAdapter({"scope-a": (_handoff(2),), "scope-b": (_handoff(4),)}) - - selected = await select_optimistic_stable_handoffs( - adapter, - (_workstream("scope-b", version=3), _workstream("scope-a", version=2)), - ) - - assert adapter.calls == ["scope-a", "scope-b", "scope-a", "scope-b"] - assert tuple(entry.scope_id for entry in selected) == ("scope-a", "scope-b") - assert tuple(entry.workstream_revision for entry in selected) == (2, 3) - assert tuple(entry.handoff_ref.revision for entry in selected if entry.handoff_ref is not None) == (2, 4) - - asyncio.run(scenario()) - - -def test_optimistic_selection_preserves_explicit_no_handoff() -> None: - async def scenario() -> None: - selected = await select_optimistic_stable_handoffs( - _FakeReadAdapter({"scope-empty": (None,)}), - (_workstream("scope-empty"),), - ) - - assert selected[0].status == "no_handoff" - assert selected[0].handoff_ref is None - - asyncio.run(scenario()) - - -def test_optimistic_selection_retries_a_change_then_freezes_stable_heads() -> None: - async def scenario() -> None: - adapter = _FakeReadAdapter({"scope-a": (_handoff(1), _handoff(2), _handoff(2), _handoff(2))}) - - selected = await select_optimistic_stable_handoffs(adapter, (_workstream("scope-a"),)) - - assert adapter.calls == ["scope-a"] * 4 - assert selected[0].handoff_ref == ArtifactRef(family="handoff", artifact_id="handoff", revision=2) - - asyncio.run(scenario()) - - -def test_optimistic_selection_reports_busy_after_bounded_instability() -> None: - async def scenario() -> None: - adapter = _FakeReadAdapter({"scope-a": tuple(_handoff(revision) for revision in range(1, 7))}) - - with pytest.raises(HandoffReportBusyError) as captured: - await select_optimistic_stable_handoffs(adapter, (_workstream("scope-a"),)) - - assert captured.value.attempts == 3 - assert adapter.calls == ["scope-a"] * 6 - - asyncio.run(scenario()) - - -@pytest.mark.parametrize("attempts", [True, 1.5, "2", 0, 6]) -def test_optimistic_selection_requires_a_strict_bounded_attempt_count(attempts: object) -> None: - async def scenario() -> None: - with pytest.raises(ValueError, match="attempts must be between"): - await select_optimistic_stable_handoffs( - _FakeReadAdapter({"scope-a": (_handoff(1),)}), - (_workstream("scope-a"),), - attempts=attempts, # ty: ignore[invalid-argument-type] - ) - - asyncio.run(scenario()) - - -class _FakeScopedApplication: - def __init__(self, handoff: Handoff) -> None: - self.handoff = handoff - self.references: list[ArtifactRef] = [] - - async def latest(self) -> Handoff | None: - return self.handoff - - async def revision(self, reference: ArtifactRef, /) -> Handoff: - self.references.append(reference) - return self.handoff - - async def revisions(self) -> tuple[Handoff, ...]: - return (self.handoff,) - - -class _FakeApplication: - def __init__(self, scoped: _FakeScopedApplication) -> None: - self.scoped = scoped - self.scopes: list[str] = [] - - def for_scope(self, scope_id: str, /) -> _FakeScopedApplication: - self.scopes.append(scope_id) - return self.scoped - - -def test_runtime_adapter_maps_only_existing_read_behaviors() -> None: - async def scenario() -> None: - handoff = _handoff(2) - scoped = _FakeScopedApplication(handoff) - application = _FakeApplication(scoped) - adapter = RuntimeHandoffReadAdapter(application) - reference = handoff.as_ref() - - assert await adapter.latest("scope-a") == handoff - assert await adapter.get("scope-a", reference) == handoff - assert await adapter.revisions("scope-a") == (handoff,) - with pytest.raises(HandoffReportEvidenceCheckUnavailableError): - await adapter.check_evidence("scope-a", reference) - assert application.scopes == ["scope-a"] * 3 - assert scoped.references == [reference] - - asyncio.run(scenario()) diff --git a/tests/test_handoff_report_service.py b/tests/test_handoff_report_service.py deleted file mode 100644 index 3e5c77ddd..000000000 --- a/tests/test_handoff_report_service.py +++ /dev/null @@ -1,488 +0,0 @@ -# Copyright (c) 2026 OceanBase. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -from __future__ import annotations - -import asyncio -from datetime import UTC, datetime - -import pytest -import yaml -from pydantic import ValidationError - -from powercontext.artifacts import ArtifactRef -from powercontext.builtin.artifacts.handoff import ( - Handoff, - HandoffContent, - HandoffEvidenceCheck, - HandoffSourceCitation, - HandoffStatement, -) -from powercontext.builtin.handoff_report.errors import ( - HandoffReportEvidenceCheckUnavailableError, - HandoffReportInconsistentError, -) -from powercontext.builtin.handoff_report.models import ( - ActivityAgent, - ActivityVcsContext, - ExternalReference, - ProjectDescriptor, - ReportActivityEvent, - WorkstreamDescriptor, -) -from powercontext.builtin.handoff_report.rendering import render_markdown -from powercontext.builtin.handoff_report.report import HandoffReport -from powercontext.builtin.handoff_report.service import HandoffReportService -from powercontext.sources import SourceRef - - -def _project() -> ProjectDescriptor: - return ProjectDescriptor( - project_id="prj-1", - project_key="powercontext", - title="PowerContext "} - ) - workstream = _workstream("scope`tick", "Feature # heading\n[click](javascript:evil)") - handoff = _handoff( - objective="Objective **bold**\n![objective](https://evil)", - state="State \nsecond line", - next_action="Next [link](https://evil)", - ) - reference = ExternalReference( - kind="issue", - provider="host`provider", - external_id="issue](javascript:evil)", - url="https://evil/`](x)", - ) - activity = _activity( - "evt`assigned", - "scope`tick", - title="Activity ![image](x)\n", - summary="Summary [link](javascript:evil)\nnext line", - source_ref=reference, - evidence_refs=(reference,), - agent=ActivityAgent(provider="codex`host", label="agent [admin]"), - session_id="session`id", - vcs_context=ActivityVcsContext(branch="feature/[link]", head_revision="abc`123"), - ) - return await HandoffReportService(_Adapter({"scope`tick": handoff})).generate( - project, - (workstream,), - activities=(activity,), - activity_cursor=1, - activity_coverage="captured", - generated_at=datetime(2026, 8, 5, tzinfo=UTC), - ) - - markdown = render_markdown(asyncio.run(scenario())) - - assert "<script>" not in markdown - assert "<img" not in markdown - assert "![image](x)" not in markdown - assert "[link](https://evil)" not in markdown - assert "<script>" in markdown - assert r"\!\[image\]\(x\)" in markdown - assert r"Project \[link\]\(https://evil\) \!\[image\]\(x\)<script>" in markdown - assert r"State <img src=x onerror=alert\(1\)> second line" in markdown - assert r"Summary \[link\]\(javascript:evil\) next line" in markdown - assert "`` scope`tick ``" in markdown - assert "`` evt`assigned ``" in markdown - assert "`` session`id ``" in markdown - - -def test_canonical_report_rejects_wrong_project_revision_and_handoff_projection() -> None: - report = _report_with_activities() - item = report.workstreams[0] - selection = report.end_selection[0] - - wrong_project = item.model_copy( - update={"workstream": item.workstream.model_copy(update={"project_id": "prj-other"})} - ) - with pytest.raises(ValidationError, match="belong to the Report Project"): - _revalidate(report.model_copy(update={"workstreams": (wrong_project,)})) - - wrong_revision = selection.model_copy(update={"workstream_revision": item.workstream.version + 1}) - with pytest.raises(ValidationError, match="Workstream revision"): - _revalidate(report.model_copy(update={"end_selection": (wrong_revision,)})) - - wrong_ref = ArtifactRef(family="handoff", artifact_id="different", revision=1) - wrong_history = (item.handoff_history[-1].model_copy(update={"reference": wrong_ref}),) - wrong_handoff = item.model_copy(update={"handoff_ref": wrong_ref, "handoff_history": wrong_history}) - with pytest.raises(ValidationError, match="Handoff reference"): - _revalidate(report.model_copy(update={"workstreams": (wrong_handoff,)})) - - -def test_canonical_report_rejects_duplicate_scopes_and_activity_ids() -> None: - report = _report_with_activities() - duplicate_scope = report.model_copy( - update={ - "end_selection": (report.end_selection[0], report.end_selection[0]), - "workstreams": (report.workstreams[0], report.workstreams[0]), - "coverage": report.coverage.model_copy(update={"selected_workstreams": 2}), - "activity_selection": ("evt-assigned", "evt-assigned", "evt-unassigned"), - } - ) - with pytest.raises(ValidationError, match="selection scopes must be unique"): - _revalidate(duplicate_scope) - - assigned = report.workstreams[0].activities[0] - duplicate_event = report.unassigned_activity[0].model_copy(update={"event_id": assigned.event_id}) - duplicate_activity = report.model_copy( - update={ - "unassigned_activity": (duplicate_event,), - "activity_selection": (assigned.event_id, assigned.event_id), - } - ) - with pytest.raises(ValidationError, match="Activity Event ids must be unique"): - _revalidate(duplicate_activity) - - -@pytest.mark.parametrize( - ("updates", "message"), - [ - ({"project_id": "prj-other"}, "belong to the Report Project"), - ({"scope_id": "scope-other"}, "scope must match"), - ], -) -def test_canonical_report_rejects_invalid_assigned_activity_ownership(updates, message: str) -> None: - report = _report_with_activities() - item = report.workstreams[0] - event = item.activities[0].model_copy(update=updates) - invalid_item = item.model_copy(update={"activities": (event,)}) - - with pytest.raises(ValidationError, match=message): - _revalidate(report.model_copy(update={"workstreams": (invalid_item,)})) - - -def test_canonical_report_rejects_invalid_unassigned_activity_and_selection() -> None: - report = _report_with_activities() - unassigned = report.unassigned_activity[0] - - wrong_project = unassigned.model_copy(update={"project_id": "prj-other"}) - with pytest.raises(ValidationError, match="belong to the Report Project"): - _revalidate(report.model_copy(update={"unassigned_activity": (wrong_project,)})) - - selected_scope = unassigned.model_copy(update={"scope_id": "scope-a"}) - with pytest.raises(ValidationError, match="cannot be unassigned"): - _revalidate(report.model_copy(update={"unassigned_activity": (selected_scope,)})) - - with pytest.raises(ValidationError, match="activity_selection"): - _revalidate(report.model_copy(update={"activity_selection": ("evt-assigned",)})) - - wrong_count = report.coverage.model_copy(update={"unassigned_activity_count": 0}) - with pytest.raises(ValidationError, match="unassigned_activity_count"): - _revalidate(report.model_copy(update={"coverage": wrong_count})) diff --git a/tests/test_handoff_report_workspace.py b/tests/test_handoff_report_workspace.py deleted file mode 100644 index 9b8fd2d69..000000000 --- a/tests/test_handoff_report_workspace.py +++ /dev/null @@ -1,173 +0,0 @@ -# Copyright (c) 2026 OceanBase. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -from __future__ import annotations - -import asyncio -from datetime import UTC, datetime, timedelta, timezone - -import pytest -from pydantic import ValidationError - -from powercontext.builtin.handoff_report import ( - HandoffReportCatalog, - ProjectNotFoundError, - RepositoryRef, - WorkspaceBindingConflictError, - WorkspaceBindingNotFoundError, - WorkspaceBindingService, - normalize_repository_ref, -) -from powercontext.builtin.handoff_report.sqlite import HANDOFF_REPORT_TABLES -from powercontext.builtin.persistence.sqlite import SQLiteConfig, SQLiteProfile - - -def test_repository_ref_normalizes_safe_remote_and_relative_subpath() -> None: - reference = RepositoryRef( - provider="github", - normalized_remote="HTTPS://GitHub.com/oceanbase/powercontext.git/", - subpath="./services/api", - ) - - normalized = normalize_repository_ref(reference) - - assert normalized.normalized_remote == "https://github.com/oceanbase/powercontext.git" - assert normalized.subpath == "services/api" - - with pytest.raises(ValidationError, match="credentials"): - RepositoryRef(provider="github", normalized_remote="https://user@example.com/repo.git") - with pytest.raises(ValueError, match="parent traversal"): - normalize_repository_ref( - RepositoryRef(provider="github", normalized_remote="https://github.com/org/repo.git", subpath="../api") - ) - with pytest.raises(ValidationError, match="must contain"): - RepositoryRef(provider="local") - - -def test_workspace_binding_requires_explicit_project_and_uses_cas_for_rebind() -> None: - async def scenario() -> None: - ids = iter(("prj-1", "prj-2")) - catalog = HandoffReportCatalog(project_id_factory=ids.__next__) - bindings = WorkspaceBindingService(catalog=catalog) - reference = RepositoryRef( - provider="github", - repository_id="repo-1", - normalized_remote="https://github.com/org/repo.git", - subpath=".", - ) - observed = datetime(2026, 8, 6, 2, tzinfo=timezone(timedelta(hours=8))) - - async with ( - SQLiteProfile.open(SQLiteConfig(), tables=HANDOFF_REPORT_TABLES) as profile, - profile.database.transaction() as connection, - ): - first_project = await catalog.create_project( - connection, - project_key="first", - title="First", - timezone="UTC", - ) - second_project = await catalog.create_project( - connection, - project_key="second", - title="Second", - timezone="UTC", - ) - - binding = await bindings.attach( - connection, - workspace_instance_id="ws-1", - project_id=first_project.project_id, - repository_ref=reference, - expected_version=None, - confirmed_at=observed, - ) - assert binding.version == 1 - assert binding.state == "confirmed" - assert binding.confirmed_at == observed.astimezone(UTC) - assert binding.repository_ref.normalized_remote == "https://github.com/org/repo.git" - assert await bindings.get(connection, "ws-1") == binding - - with pytest.raises(WorkspaceBindingConflictError, match="already has"): - await bindings.attach( - connection, - workspace_instance_id="ws-1", - project_id=first_project.project_id, - repository_ref=reference, - expected_version=None, - ) - - refreshed = await bindings.attach( - connection, - workspace_instance_id="ws-1", - project_id=first_project.project_id, - repository_ref=reference, - expected_version=1, - ) - assert refreshed.version == 2 - - with pytest.raises(WorkspaceBindingConflictError) as stale: - await bindings.attach( - connection, - workspace_instance_id="ws-1", - project_id=first_project.project_id, - repository_ref=reference, - expected_version=1, - ) - assert stale.value.current_version == 2 - - detached = await bindings.detach(connection, "ws-1", expected_version=2) - assert detached.state == "detached" - assert detached.version == 3 - with pytest.raises(WorkspaceBindingNotFoundError): - await bindings.get(connection, "ws-1") - assert await bindings.get_record(connection, "ws-1") == detached - - rebound = await bindings.attach( - connection, - workspace_instance_id="ws-1", - project_id=second_project.project_id, - repository_ref=reference, - expected_version=3, - ) - assert rebound.project_id == second_project.project_id - assert rebound.version == 4 - - asyncio.run(scenario()) - - -def test_workspace_attach_rejects_unknown_project_and_missing_exact_version() -> None: - async def scenario() -> None: - catalog = HandoffReportCatalog(project_id_factory=lambda: "prj-1") - bindings = WorkspaceBindingService(catalog=catalog) - reference = RepositoryRef(provider="local", subpath=".") - - async with ( - SQLiteProfile.open(SQLiteConfig(), tables=HANDOFF_REPORT_TABLES) as profile, - profile.database.transaction() as connection, - ): - with pytest.raises(ProjectNotFoundError): - await bindings.attach( - connection, - workspace_instance_id="ws-unknown", - project_id="missing", - repository_ref=reference, - expected_version=None, - ) - with pytest.raises(WorkspaceBindingConflictError, match="missing"): - await bindings.detach(connection, "ws-unknown", expected_version=1) - with pytest.raises(WorkspaceBindingNotFoundError): - await bindings.get(connection, "ws-unknown") - - asyncio.run(scenario()) diff --git a/tests/test_js_operations.py b/tests/test_js_operations.py index 3ff76d830..f75b66117 100644 --- a/tests/test_js_operations.py +++ b/tests/test_js_operations.py @@ -51,16 +51,18 @@ def test_js_operations_record_method_path_location_and_scope() -> None: generator = _load_generator() doc = yaml.safe_load(generator.CONTRACT_PATH.read_text(encoding="utf-8")) by_id = {row["operationId"]: row for row in generator.parse_operations(doc)} - assert by_id["get_liveness"] == { + assert {key: by_id["get_liveness"][key] for key in ("operationId", "method", "path", "location", "scopeMode")} == { "operationId": "get_liveness", "method": "GET", "path": "/health/live", "location": None, - "scope": False, + "scopeMode": "none", } - assert by_id["get_stats"]["location"] == "query" + assert by_id["get_stats"]["location"] == "body" + assert by_id["get_stats"]["scopeMode"] == "selection" assert by_id["remember_memory"]["location"] == "body" - assert by_id["remember_memory"]["scope"] is True + assert by_id["remember_memory"]["scopeMode"] == "current" + assert by_id["set_scope_binding"]["scopeMode"] == "none" def test_committed_js_operations_match_openapi() -> None: diff --git a/tests/test_mcp.py b/tests/test_mcp.py index af9d95fcd..cbcf23479 100644 --- a/tests/test_mcp.py +++ b/tests/test_mcp.py @@ -21,13 +21,8 @@ import httpx from fastapi import Request from fastmcp import Client -from fastmcp.client.elicitation import ElicitResult from fastmcp.client.transports import StreamableHttpTransport -from mcp.types import ElicitRequestFormParams -from powercontext.builtin.handoff_report import CatalogPage -from powercontext.builtin.handoff_report import ProjectDescriptor as ReportProjectDescriptor -from powercontext.builtin.handoff_report import WorkstreamDescriptor as ReportWorkstreamDescriptor from powercontext.builtin.runtime import MemoryEntriesPage from powercontext.server.access import HttpAccessLogMiddleware from powercontext.server.app import create_app @@ -37,79 +32,11 @@ ResultT = TypeVar("ResultT") -class HandoffReportCatalogStub: - def __init__( - self, - projects: tuple[ReportProjectDescriptor, ...], - workstreams: dict[str, tuple[ReportWorkstreamDescriptor, ...]], - ) -> None: - self.projects = projects - self.workstreams = workstreams - - async def list_projects( - self, - *, - cursor: str | None = None, - limit: int = 50, - include_archived: bool = False, - ) -> CatalogPage[ReportProjectDescriptor]: - del cursor, include_archived - return CatalogPage(self.projects[:limit], None) - - async def list_workstreams( - self, - project_id: str, - *, - cursor: str | None = None, - limit: int = 50, - include_archived: bool = False, - ) -> CatalogPage[ReportWorkstreamDescriptor]: - del cursor, include_archived - return CatalogPage(self.workstreams.get(project_id, ())[:limit], None) - - -def handoff_report_app( - projects: tuple[ReportProjectDescriptor, ...], - workstreams: dict[str, tuple[ReportWorkstreamDescriptor, ...]], -): - application = SimpleNamespace(handoff_report=HandoffReportCatalogStub(projects, workstreams)) - return create_app(application=application, handoff_report_enabled=True) - - -def report_project(project_id: str, project_key: str, title: str) -> ReportProjectDescriptor: - return ReportProjectDescriptor( - project_id=project_id, - project_key=project_key, - title=title, - timezone="UTC", - version=1, - ) - - -def report_workstream( - project_id: str, - scope_id: str, - key: str, - title: str, - *, - labels: tuple[str, ...] = (), -) -> ReportWorkstreamDescriptor: - return ReportWorkstreamDescriptor( - project_id=project_id, - scope_id=scope_id, - key=key, - title=title, - kind="feature", - labels=labels, - version=1, - ) - - def run_async(operation: Callable[[], Coroutine[Any, Any, ResultT]]) -> ResultT: return asyncio.run(operation()) -def test_mcp_exposes_only_the_agent_facing_server_operations() -> None: +def test_mcp_exposes_only_data_plane_and_integration_control_operations() -> None: async def inspect_components() -> tuple[list[str], int, int]: async with Client(create_mcp_server(create_app())) as client: tools = await client.list_tools() @@ -124,22 +51,29 @@ async def inspect_components() -> tuple[list[str], int, int]: "acknowledge_handoff", "approve_artifact_candidate", "capture_content_source", + "clear_scope_binding", "commit_handoff", "continue_handoff", + "create_scope", "create_work_contract", "finalize_handoff", "get_artifact_candidate", "get_memory_entry", + "get_scope", "handoff_current_work", "list_artifact_candidates", "list_memory_entries", + "list_scopes", + "publish_artifact", "reject_artifact_candidate", "record_task_outcome", + "resolve_scope_binding", "remember_memory", "retire_memory_entry", "revise_artifact_candidate", "revise_memory_entry", "search_memory", + "set_scope_binding", } assert resource_count == 0 assert prompt_count == 0 @@ -153,164 +87,12 @@ async def inspect_components() -> dict[str, Any]: tools = run_async(inspect_components) assert "get_handoff_report" in tools - assert "get_handoff_report_workspace" in tools - assert "list_handoff_report_known_scopes" in tools - assert "record_handoff_report_activity" not in tools - assert "attach_handoff_report_workspace" not in tools - picker = tools["select_handoff_workstream"] - assert picker is not None - assert picker.readOnlyHint is True - assert picker.destructiveHint is False - assert picker.idempotentHint is True - assert picker.openWorldHint is False - - -def test_mcp_handoff_picker_returns_structured_choices_without_elicitation() -> None: - project = report_project("prj-powercontext", "powercontext", "PowerContext") - workstreams = ( - report_workstream(project.project_id, "scope-claude", "claude-compat", "Claude compatibility"), - report_workstream(project.project_id, "scope-ui", "handoff-ui", "Handoff workbench"), - ) - app = handoff_report_app((project,), {project.project_id: workstreams}) - - async def select() -> tuple[dict[str, Any], dict[str, Any]]: - async with Client(create_mcp_server(app)) as client: - choices = await client.call_tool("select_handoff_workstream", {}) - selected = await client.call_tool( - "select_handoff_workstream", - {"project_id": project.project_id, "work_id": "handoff-ui"}, - ) - return choices.structured_content or {}, selected.structured_content or {} - - choices, selected = run_async(select) - - assert choices["status"] == "needs_selection" - assert choices["stage"] == "workstream" - assert [item["work_id"] for item in choices["workstream_choices"]] == ["claude-compat", "handoff-ui"] - assert selected["status"] == "selected" - assert selected["selected"] == { - "work_id": "handoff-ui", - "scope_id": "scope-ui", - "project_id": project.project_id, - "project_key": "powercontext", - "title": "Handoff workbench", - "kind": "feature", - "catalog_version": 1, - } - - -def test_mcp_handoff_picker_does_not_silently_resolve_an_ambiguous_work_id() -> None: - project = report_project("prj-powercontext", "powercontext", "PowerContext") - workstreams = ( - report_workstream(project.project_id, "scope-claude", "shared-id", "Claude compatibility"), - report_workstream(project.project_id, "shared-id", "handoff-ui", "Handoff workbench"), - ) - app = handoff_report_app((project,), {project.project_id: workstreams}) - - async def select() -> dict[str, Any]: - async with Client(create_mcp_server(app)) as client: - result = await client.call_tool( - "select_handoff_workstream", - {"project_id": project.project_id, "work_id": "shared-id"}, - ) - return result.structured_content or {} - - result = run_async(select) - - assert result["status"] == "needs_selection" - assert result["stage"] == "workstream" - assert [item["work_id"] for item in result["workstream_choices"]] == ["shared-id", "handoff-ui"] - - -def test_mcp_handoff_picker_uses_native_form_elicitation() -> None: - project = report_project("prj-powercontext", "powercontext", "PowerContext") - workstreams = ( - report_workstream(project.project_id, "scope-claude", "claude-compat", "Claude compatibility"), - report_workstream(project.project_id, "scope-ui", "handoff-ui", "Handoff workbench"), - ) - app = handoff_report_app((project,), {project.project_id: workstreams}) - requests: list[ElicitRequestFormParams] = [] - - async def choose_second(_message, _response_type, params, _context) -> str: - assert isinstance(params, ElicitRequestFormParams) - requests.append(params) - return "option-2" - - async def select() -> dict[str, Any]: - async with Client(create_mcp_server(app), elicitation_handler=choose_second) as client: - result = await client.call_tool("select_handoff_workstream", {"locale": "en"}) - return result.structured_content or {} - - selected = run_async(select) - - assert selected["status"] == "selected" - assert selected["selected"]["work_id"] == "handoff-ui" - assert len(requests) == 1 - assert requests[0].message == "Choose the work to hand off or continue." - options = requests[0].requestedSchema["properties"]["value"]["oneOf"] - assert options == [ - {"const": "option-1", "title": "Claude compatibility · claude-compat · feature"}, - {"const": "option-2", "title": "Handoff workbench · handoff-ui · feature"}, - ] - - -def test_mcp_handoff_picker_preserves_cancelled_selection() -> None: - project = report_project("prj-powercontext", "powercontext", "PowerContext") - workstreams = ( - report_workstream(project.project_id, "scope-claude", "claude-compat", "Claude compatibility"), - report_workstream(project.project_id, "scope-ui", "handoff-ui", "Handoff workbench"), - ) - app = handoff_report_app((project,), {project.project_id: workstreams}) - - async def cancel(_message, _response_type, _params, _context) -> ElicitResult: - return ElicitResult(action="cancel") - - async def select() -> dict[str, Any]: - async with Client(create_mcp_server(app), elicitation_handler=cancel) as client: - result = await client.call_tool("select_handoff_workstream", {}) - return result.structured_content or {} - - result = run_async(select) - - assert result["status"] == "cancelled" - assert result["stage"] == "workstream" - assert result["selected"] is None - - -def test_mcp_handoff_picker_selects_project_then_workstream() -> None: - memory = report_project("prj-memory", "memory", "Memory") - handoff = report_project("prj-handoff", "handoff", "Handoff") - app = handoff_report_app( - (memory, handoff), - { - memory.project_id: (report_workstream(memory.project_id, "scope-memory", "memory-core", "Memory Core"),), - handoff.project_id: ( - report_workstream(handoff.project_id, "scope-cli", "handoff-cli", "Handoff CLI"), - report_workstream(handoff.project_id, "scope-web", "handoff-web", "Handoff Web"), - ), - }, - ) - replies = iter(("option-2", "option-1")) - messages: list[str] = [] - - async def choose(_message, _response_type, _params, _context) -> str: - messages.append(_message) - return next(replies) - - async def select() -> dict[str, Any]: - async with Client(create_mcp_server(app), elicitation_handler=choose) as client: - result = await client.call_tool("select_handoff_workstream", {"locale": "en"}) - return result.structured_content or {} - - result = run_async(select) - - assert messages == [ - "Choose the Project that owns this Handoff.", - "Choose the work to hand off or continue.", - ] - assert result["status"] == "selected" - assert result["selected"]["project_id"] == handoff.project_id - assert result["selected"]["work_id"] == "handoff-cli" + report = tools["get_handoff_report"] + assert report is not None + assert report.readOnlyHint is True + assert report.destructiveHint is False + assert report.idempotentHint is True + assert report.openWorldHint is False def test_mcp_describes_handoff_tool_side_effects_for_host_approval() -> None: diff --git a/tests/test_openclaw_cli.py b/tests/test_openclaw_cli.py index 2a09ed5ab..3e12b7c2c 100644 --- a/tests/test_openclaw_cli.py +++ b/tests/test_openclaw_cli.py @@ -68,7 +68,6 @@ def test_configure_openclaw_preserves_existing_tools_and_adds_missing_tools(monk openclaw_cli.configure_openclaw( executable="openclaw", server_url="http://127.0.0.1:8765", - scope_mode="agent", ) allowlist_call = run_openclaw.call_args_list[1] @@ -102,11 +101,14 @@ def read_config(command: list[str], *, timeout: int, check: bool = True) -> Comp openclaw_cli.configure_openclaw( executable="openclaw", server_url="http://127.0.0.1:8765", - scope_mode="agent", ) settings = json.loads(run_openclaw.call_args_list[0].args[4]) assert settings[0] == {"path": "gateway.mode", "value": "local"} + assert { + "path": "plugins.entries.memory-powercontext.hooks.allowConversationAccess", + "value": True, + } in settings def test_install_openclaw_plugin_builds_installs_and_configures( @@ -129,14 +131,12 @@ def test_install_openclaw_plugin_builds_installs_and_configures( source="oceanbase/powercontext", ref="tested-ref", server_url="http://127.0.0.1:8765/", - scope_mode="project", ) assert result == OpenClawSetupResult( plugin="memory-powercontext", plugin_path=str(plugin), server_url="http://127.0.0.1:8765", - scope_mode="project", data_dir=str(tmp_path / "data"), ) build.assert_called_once_with(plugin) @@ -144,7 +144,6 @@ def test_install_openclaw_plugin_builds_installs_and_configures( configure.assert_called_once_with( executable="/usr/bin/openclaw", server_url="http://127.0.0.1:8765", - scope_mode="project", ) @@ -156,7 +155,6 @@ def test_setup_openclaw_exposes_source_ref_and_runtime_options(monkeypatch: pyte plugin="memory-powercontext", plugin_path="plugin-path", server_url="http://127.0.0.1:8765", - scope_mode="agent", data_dir="data-dir", ) ) @@ -173,8 +171,6 @@ def test_setup_openclaw_exposes_source_ref_and_runtime_options(monkeypatch: pyte "tested-ref", "--server-url", "http://127.0.0.1:8765", - "--scope-mode", - "agent", "--json", ], ) @@ -185,7 +181,6 @@ def test_setup_openclaw_exposes_source_ref_and_runtime_options(monkeypatch: pyte source="oceanbase/powercontext", ref="tested-ref", server_url="http://127.0.0.1:8765", - scope_mode="agent", ) @@ -197,7 +192,6 @@ def install(**kwargs: str) -> OpenClawSetupResult: plugin="memory-powercontext", plugin_path="plugin-path", server_url=kwargs["server_url"], - scope_mode=kwargs["scope_mode"], data_dir="data-dir", ) diff --git a/tests/test_openclaw_configure_script.py b/tests/test_openclaw_configure_script.py index cdc9cb398..e1ab0a69d 100644 --- a/tests/test_openclaw_configure_script.py +++ b/tests/test_openclaw_configure_script.py @@ -76,6 +76,10 @@ def fake_run(command: list[str], *, timeout: int, check: bool = True) -> Complet if command[1:4] == ["config", "set", "--batch-json"]: settings = json.loads(command[4]) assert settings[0] == {"path": "gateway.mode", "value": "local"} + assert { + "path": "plugins.entries.memory-powercontext.hooks.allowConversationAccess", + "value": True, + } in settings return CompletedProcess(command, 0, "", "") if command[1:3] == ["gateway", "restart"]: return CompletedProcess(command, 0, "", "") @@ -84,7 +88,7 @@ def fake_run(command: list[str], *, timeout: int, check: bool = True) -> Complet monkeypatch.setattr(configure_openclaw, "run_command", fake_run) monkeypatch.setenv("OPENCLAW_RESTART", "1") - configure_openclaw.enable("openclaw", "http://127.0.0.1:8765", "agent") + configure_openclaw.enable("openclaw", "http://127.0.0.1:8765") assert commands[0][1:4] == ["config", "get", "gateway.mode"] diff --git a/tests/test_scope_api.py b/tests/test_scope_api.py new file mode 100644 index 000000000..59fb91a4e --- /dev/null +++ b/tests/test_scope_api.py @@ -0,0 +1,200 @@ +# Copyright (c) 2026 OceanBase. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +from __future__ import annotations + +from fastapi.testclient import TestClient + +from powercontext.builtin.persistence.sqlite import SQLiteConfig +from powercontext.server.factory import create_server_app +from powercontext.server.settings import McpConfig, ServerSettings + + +def test_scope_http_flow_resolves_default_durable_and_observation_ranges(tmp_path) -> None: + app = create_server_app( + settings=ServerSettings( + database=SQLiteConfig(url=f"sqlite+aiosqlite:///{tmp_path / 'runtime.db'}"), + mcp=McpConfig(enabled=False), + ) + ) + + with TestClient(app) as client: + default = client.get("/v1/scopes/default") + assert default.status_code == 200 + default_scope_id = default.json()["scope_id"] + + root = client.post( + "/v1/scopes", + json={"title": "Feature", "summary": "Feature result", "idempotency_key": "feature"}, + ) + assert root.status_code == 201 + root_scope_id = root.json()["scope_id"] + child = client.post( + "/v1/scopes", + json={ + "title": "Validation", + "summary": "Independent validation", + "parent_scope_id": root_scope_id, + "idempotency_key": "validation", + }, + ) + assert child.status_code == 201 + child_scope_id = child.json()["scope_id"] + + binding_key = {"integration": "codex", "kind": "session", "external_id": "session-1"} + workspace_key = {"integration": "codex", "kind": "workspace", "external_id": "workspace-1"} + assert ( + client.put( + "/v1/scope-bindings", + json={"key": binding_key, "scope_id": child_scope_id}, + ).status_code + == 200 + ) + assert ( + client.put( + "/v1/scope-bindings", + json={"key": workspace_key, "scope_id": root_scope_id}, + ).status_code + == 200 + ) + resolved = client.post( + "/v1/scope-bindings/resolve", + json={"binding_keys": [binding_key, workspace_key]}, + ) + assert resolved.status_code == 200 + assert resolved.json()["scope_id"] == child_scope_id + workspace = client.post( + "/v1/scope-bindings/resolve", + json={"binding_keys": [workspace_key]}, + ) + assert workspace.json()["scope_id"] == root_scope_id + + subtree = client.post( + "/v1/scopes/selection/resolve", + json={"selection": {"mode": "subtree", "root_scope_id": root_scope_id}}, + ) + assert [scope["scope_id"] for scope in subtree.json()["items"]] == [root_scope_id, child_scope_id] + all_scopes = client.post( + "/v1/scopes/selection/resolve", + json={"selection": {"mode": "all"}}, + ) + assert {scope["scope_id"] for scope in all_scopes.json()["items"]} == { + default_scope_id, + root_scope_id, + child_scope_id, + } + + +def test_scope_http_flow_rejects_stale_metadata_and_invalid_selection(tmp_path) -> None: + app = create_server_app( + settings=ServerSettings( + database=SQLiteConfig(url=f"sqlite+aiosqlite:///{tmp_path / 'runtime.db'}"), + mcp=McpConfig(enabled=False), + ) + ) + + with TestClient(app) as client: + created = client.post( + "/v1/scopes", + json={"title": "Work", "summary": "Initial", "idempotency_key": "work"}, + ).json() + request = { + "expected_version": created["version"], + "title": "Work", + "summary": "Updated", + } + scope_path = f"/v1/scopes/{created['scope_id']}" + fetched = client.get(scope_path) + assert fetched.status_code == 200 + assert fetched.json() == created + + assert client.put(scope_path, json=request).status_code == 200 + stale = client.put(scope_path, json=request) + assert stale.status_code == 409 + assert stale.json()["error"]["code"] == "scope_version_conflict" + + invalid = client.post( + "/v1/scopes/selection/resolve", + json={"selection": {"mode": "exact", "scope_ids": []}}, + ) + assert invalid.status_code == 422 + + +def test_scope_http_flow_publishes_one_exact_artifact(tmp_path) -> None: + app = create_server_app( + settings=ServerSettings( + database=SQLiteConfig(url=f"sqlite+aiosqlite:///{tmp_path / 'runtime.db'}"), + mcp=McpConfig(enabled=False), + ) + ) + + with TestClient(app) as client: + source_scope_id = client.post( + "/v1/scopes", + json={"title": "Source", "summary": "Working state", "idempotency_key": "source"}, + ).json()["scope_id"] + target_scope_id = client.post( + "/v1/scopes", + json={"title": "Target", "summary": "Accepted state", "idempotency_key": "target"}, + ).json()["scope_id"] + memory = client.post( + "/v1/memory/remember", + json={"scope_id": source_scope_id, "kind": "decision", "text": "Publish the accepted decision."}, + ).json()["memory"] + request = { + "source": {"scope_id": source_scope_id, "artifact": memory}, + "target_scope_id": target_scope_id, + "idempotency_key": "accepted-decision", + } + + created = client.post("/v1/artifact-publications", json=request) + repeated = client.post("/v1/artifact-publications", json=request) + + assert created.status_code == 201 + assert repeated.status_code == 201 + assert created.json() == repeated.json() + assert created.json()["source"] == request["source"] + assert created.json()["target"]["scope_id"] == target_scope_id + assert created.json()["target"]["artifact"]["revision"] == 1 + + conflicting = client.post( + "/v1/artifact-publications", + json={ + **request, + "source": { + "scope_id": source_scope_id, + "artifact": {**memory, "revision": memory["revision"] + 1}, + }, + }, + ) + assert conflicting.status_code == 409 + assert conflicting.json()["error"]["code"] == "artifact_publication_conflict" + + +def test_data_plane_rejects_an_unknown_scope(tmp_path) -> None: + app = create_server_app( + settings=ServerSettings( + database=SQLiteConfig(url=f"sqlite+aiosqlite:///{tmp_path / 'runtime.db'}"), + mcp=McpConfig(enabled=False), + ) + ) + + with TestClient(app) as client: + response = client.post( + "/v1/memory/search", + json={"scope_id": "scp_unknown", "query": "prior decision"}, + ) + + assert response.status_code == 404 + assert response.json()["error"]["code"] == "scope_not_found" diff --git a/tests/test_server.py b/tests/test_server.py index 26f6dc3d9..693d0d3cc 100644 --- a/tests/test_server.py +++ b/tests/test_server.py @@ -89,7 +89,6 @@ async def embed(self, texts: tuple[str, ...], /) -> EmbeddingResult: def test_settings_load_server_environment(monkeypatch) -> None: monkeypatch.delenv("POWERCONTEXT_SERVER_DASHBOARD_ENABLED", raising=False) - monkeypatch.delenv("POWERCONTEXT_SERVER_DASHBOARD_SCOPES", raising=False) monkeypatch.setenv("POWERCONTEXT_SERVER_HTTP_HOST", "127.0.0.2") monkeypatch.setenv("POWERCONTEXT_SERVER_HTTP_PORT", "9000") monkeypatch.setenv( @@ -143,7 +142,6 @@ def test_settings_load_server_environment(monkeypatch) -> None: assert settings.mcp.enabled is False assert settings.mcp.path == "/context" assert settings.dashboard.enabled is True - assert settings.dashboard.scopes == [] assert settings.external_skills.host_id == "workstation-1" assert settings.external_skills.targets[0].target_id == "codex-project" assert settings.external_skills.targets[0].path.as_posix() == "/srv/project/.agents/skills" @@ -169,7 +167,7 @@ def test_env_example_loads_server_settings(monkeypatch) -> None: settings = ServerSettings() assert isinstance(settings.database, SQLiteConfig) - assert settings.dashboard.scopes[0].scope_id == "project:quickstart" + assert settings.dashboard.enabled is True assert settings.runtime.schedule_seconds == 60 assert settings.inference.generation_model == "openai:gpt-4.1-mini" assert settings.inference.embedding_dimension == 1536 @@ -770,6 +768,7 @@ def test_stats_returns_inclusive_utc_periods_for_empty_scope(tmp_path) -> None: ) with TestClient(app) as client: + default_scope_id = client.get("/v1/scopes/default").json()["scope_id"] responses = [] for requested_period, expected_preset, expected_days in ( (None, "30d", 30), @@ -777,13 +776,18 @@ def test_stats_returns_inclusive_utc_periods_for_empty_scope(tmp_path) -> None: ("7d", "7d", 7), ("30d", "30d", 30), ): - params = {"scope_id": "project:test"} + payload: dict[str, object] = { + "selection": {"mode": "exact", "scope_ids": [default_scope_id]}, + } if requested_period is not None: - params["period"] = requested_period - responses.append((client.get("/v1/stats", params=params), expected_preset, expected_days)) - invalid = client.get( + payload["period"] = requested_period + responses.append((client.post("/v1/stats", json=payload), expected_preset, expected_days)) + invalid = client.post( "/v1/stats", - params={"scope_id": "project:test", "period": "all"}, + json={ + "selection": {"mode": "exact", "scope_ids": [default_scope_id]}, + "period": "all", + }, ) assert invalid.status_code == 422 @@ -804,7 +808,15 @@ def test_stats_returns_inclusive_utc_periods_for_empty_scope(tmp_path) -> None: } expected_dates = [(start_date + timedelta(days=offset)).isoformat() for offset in range(expected_days)] - assert body["scope_id"] == "project:test" + assert body["selection"] == { + "mode": "exact", + "scope_ids": [default_scope_id], + } + assert body["scope_ids"] == [default_scope_id] + assert [item["scope_id"] for item in body["by_scope"]] == [default_scope_id] + assert body["by_scope"][0]["inventory"] == body["inventory"] + assert body["by_scope"][0]["usage"] == body["usage"] + assert body["by_scope"][0]["recall"] == body["recall"] assert body["usage"]["period"] == expected_period assert body["recall"]["period"] == expected_period assert [day["date"] for day in body["usage"]["daily"]] == expected_dates diff --git a/tests/test_server_metrics.py b/tests/test_server_metrics.py index 7cecdcb9b..90a9fd0f4 100644 --- a/tests/test_server_metrics.py +++ b/tests/test_server_metrics.py @@ -57,9 +57,10 @@ def test_http_metrics_use_declared_operations_and_exclude_infrastructure(tmp_pat app = create_server_app(settings=_settings(tmp_path / "runtime.db")) with TestClient(app) as client: + scope_id = client.get("/v1/scopes/default").json()["scope_id"] assert client.get("/v1/capabilities").status_code == 200 - assert client.post("/v1/memory/flush", json={"scope_id": "project:metrics"}).status_code == 200 - assert client.post("/v1/artifact-candidates/list", json={"scope_id": "project:metrics"}).status_code == 200 + assert client.post("/v1/memory/flush", json={"scope_id": scope_id}).status_code == 200 + assert client.post("/v1/artifact-candidates/list", json={"scope_id": scope_id}).status_code == 200 assert client.get("/health/live").status_code == 200 response = client.get("/metrics") @@ -113,9 +114,17 @@ def test_one_off_scope_ids_keep_runtime_scope_cache_bounded(tmp_path) -> None: with TestClient(app) as client: for index in range(12): + scope_id = client.post( + "/v1/scopes", + json={ + "title": f"One-off {index}", + "summary": "Runtime cache behavior", + "idempotency_key": f"one-off-{index}", + }, + ).json()["scope_id"] response = client.post( "/v1/context/prepare", - json={"scope_id": f"one-off-{index}", "query": "short query"}, + json={"scope_id": scope_id, "query": "short query"}, ) assert response.status_code == 200 metrics = client.get("/metrics").text @@ -153,7 +162,17 @@ async def scenario() -> str: Client(transport) as client, create_http_client() as http_client, ): - await client.call_tool("list_memory_entries", {"scope_id": "project:metrics"}) + created = await http_client.post( + "/v1/scopes", + json={ + "title": "Metrics", + "summary": "MCP metrics behavior", + "idempotency_key": "metrics", + }, + ) + created.raise_for_status() + scope_id = created.json()["scope_id"] + await client.call_tool("list_memory_entries", {"scope_id": scope_id}) return (await http_client.get("/metrics")).text metrics = asyncio.run(scenario()) diff --git a/tests/test_server_tracing.py b/tests/test_server_tracing.py index 04f477519..7d15e24a8 100644 --- a/tests/test_server_tracing.py +++ b/tests/test_server_tracing.py @@ -50,10 +50,11 @@ def _tracing(*, instrumented: bool = False) -> tuple[ServerTracing, InMemorySpan return ServerTracing(provider, instrumented=instrumented), exporter -def test_http_and_application_spans_preserve_incoming_context() -> None: +def test_http_and_application_spans_preserve_incoming_context(tmp_path) -> None: tracing, exporter = _tracing() app = create_server_app( settings=ServerSettings( + database=SQLiteConfig(url=f"sqlite+aiosqlite:///{tmp_path / 'tracing.db'}"), mcp=McpConfig(enabled=False), metrics=MetricsConfig(enabled=False), logging=ServerLoggingConfig(access=False), diff --git a/tests/test_setup_select.py b/tests/test_setup_select.py index b40ebdb0b..c58ead8dc 100644 --- a/tests/test_setup_select.py +++ b/tests/test_setup_select.py @@ -309,12 +309,11 @@ def test_setup_select_passes_source_ref_and_host_specific_defaults(monkeypatch) source="oceanbase/powercontext", ref="tested-ref", server_url="http://127.0.0.1:8000", - scope_mode="agent", ) installers["opencode"].assert_called_once_with(source="oceanbase/powercontext", ref="tested-ref") -def test_setup_select_passes_server_and_scope_overrides_to_openclaw(monkeypatch) -> None: +def test_setup_select_passes_server_override_to_openclaw(monkeypatch) -> None: installers = _patch_installers(monkeypatch) result = _invoke([ @@ -324,8 +323,6 @@ def test_setup_select_passes_server_and_scope_overrides_to_openclaw(monkeypatch) "openclaw", "--server-url", "https://memory.example", - "--scope-mode", - "project", ]) assert result.exit_code == 0 @@ -333,7 +330,6 @@ def test_setup_select_passes_server_and_scope_overrides_to_openclaw(monkeypatch) source="oceanbase/powercontext", ref="master", server_url="https://memory.example", - scope_mode="project", ) From 5d5b55028585fd550f6a49006ed59613ef60e0b3 Mon Sep 17 00:00:00 2001 From: Chojan Shang <psiace@apache.org> Date: Wed, 2 Sep 2026 16:13:27 +0800 Subject: [PATCH 07/17] docs(scope): explain server-owned organization --- docs/en/development/server-web-ui.md | 36 +-- docs/en/docs/explanation/core-concepts.md | 14 +- docs/en/docs/how-to/configure-claude-code.md | 23 +- docs/en/docs/how-to/configure-codex.md | 25 +-- docs/en/docs/how-to/configure-dsh.md | 4 +- docs/en/docs/how-to/configure-hermes.md | 12 +- docs/en/docs/how-to/configure-langchain.md | 10 +- docs/en/docs/how-to/configure-langgraph.md | 20 +- docs/en/docs/how-to/configure-openclaw.md | 19 +- docs/en/docs/how-to/configure-opencode.md | 5 +- docs/en/docs/how-to/configure-pi.md | 5 +- docs/en/docs/how-to/configure-pydantic-ai.md | 11 +- docs/en/docs/how-to/configure-workbuddy.md | 29 ++- .../en/docs/how-to/full-capability-runtime.md | 205 ++++++------------ docs/en/docs/how-to/handoff-with-codex.md | 10 +- docs/en/docs/how-to/install-and-run.md | 4 +- docs/en/docs/how-to/use-handoff-report.md | 76 +++---- docs/en/docs/reference/configuration.md | 20 +- docs/en/docs/reference/http-api.md | 2 +- docs/en/docs/reference/interfaces.md | 29 +-- docs/en/docs/tutorials/agent-quickstart.md | 28 +-- docs/en/docs/tutorials/codex-quickstart.md | 6 +- docs/zh/development/server-web-ui.md | 33 ++- docs/zh/docs/explanation/core-concepts.md | 7 +- docs/zh/docs/how-to/configure-claude-code.md | 22 +- docs/zh/docs/how-to/configure-codex.md | 21 +- docs/zh/docs/how-to/configure-dsh.md | 4 +- docs/zh/docs/how-to/configure-hermes.md | 12 +- docs/zh/docs/how-to/configure-langchain.md | 9 +- docs/zh/docs/how-to/configure-langgraph.md | 18 +- docs/zh/docs/how-to/configure-openclaw.md | 18 +- docs/zh/docs/how-to/configure-opencode.md | 5 +- docs/zh/docs/how-to/configure-pi.md | 4 +- docs/zh/docs/how-to/configure-pydantic-ai.md | 10 +- docs/zh/docs/how-to/configure-workbuddy.md | 23 +- .../zh/docs/how-to/full-capability-runtime.md | 195 ++++++----------- docs/zh/docs/how-to/handoff-with-codex.md | 9 +- docs/zh/docs/how-to/install-and-run.md | 4 +- docs/zh/docs/how-to/use-handoff-report.md | 68 ++---- docs/zh/docs/reference/configuration.md | 18 +- docs/zh/docs/reference/http-api.md | 2 +- docs/zh/docs/reference/interfaces.md | 19 +- docs/zh/docs/tutorials/agent-quickstart.md | 23 +- docs/zh/docs/tutorials/codex-quickstart.md | 4 +- 44 files changed, 462 insertions(+), 659 deletions(-) diff --git a/docs/en/development/server-web-ui.md b/docs/en/development/server-web-ui.md index d30083dbe..2dcdfb60c 100644 --- a/docs/en/development/server-web-ui.md +++ b/docs/en/development/server-web-ui.md @@ -72,20 +72,22 @@ versioned prefixes. ## Understand Dashboard data -The browser authenticates against `/dashboard/scopes`, then requests `/v1/stats` with the selected `scope_id` and a -`30d` period. The Server reads one scoped snapshot and returns inventory, model usage, and recall statistics. +The browser authenticates against `/dashboard/scopes`, builds the shared Scope selector, then posts the selected +`ScopeSelection` and period to `/v1/stats`. The selector exposes three observation views: `all`, one root's `subtree`, +or one `exact` Scope. A Parent relation organizes the selector; it does not make parent data visible to a child. | Dashboard value | Source | | --- | --- | -| Sources | Current scoped Source journal position | -| Memory entries | Entries in the current Memory Artifact | -| Artifacts | Current Artifact heads grouped by family | -| Pending review | Current Candidate heads grouped by family and status | +| Sources | Selected Scopes' Source journal positions | +| Memory entries | Entries in the selected Scopes' Memory Artifacts | +| Artifacts | Selected Scopes' Artifact heads grouped by family | +| Pending review | Selected Scopes' Candidate heads grouped by family and status | | Model usage | Persisted daily generation and embedding usage | | Recall hits, token reduction, and savings trend | Persisted daily recall measurements for the configured estimator | -The Runtime performs these reads in one database transaction and calculates totals, pending Sources, family counts, -daily buckets, and token reduction on the Server. The browser presents `ready_preparations` as recall hits and plots the +The Runtime resolves the selection to exact Scope IDs, aggregates totals, pending Sources, family counts, daily buckets, +and token reduction on the Server, and returns both the selection and resolved IDs. The browser presents +`ready_preparations` as recall hits and plots the signed daily `token_reduction` as the savings trend. Each heatmap cell combines those two fields for its date. Its fixed bands are no hit, hit without a positive reduction, 1–255, 256–1023, and 1024 or more estimated tokens reduced. The fixed thresholds keep sparse activity and outliers from changing the meaning of every other cell. @@ -101,17 +103,17 @@ or rendering contract only after a second page needs the same behavior. ## Add the Handoff Report page -When Handoff Report is enabled, the Server hosts the scope Handoff page at `/handoff-reports` without requiring the scoped-statistics Dashboard or its configured scope list. The optional Dashboard remains at `/` when separately enabled. The pages share only `base.html`, the header and footer, `auth.js`, theme state, and locale state; their statistics and report calculations remain independent. +When Handoff Report is enabled, the Server hosts a read-only report page at `/handoff-reports`; the Dashboard remains +optional. Both pages load Scopes from `/dashboard/scopes` and use `scope-selection.js` to expose the same `all`, +`subtree`, and `exact` views. -The Handoff Report page obtains exact `scope_id` values with committed Handoffs from `POST /v1/handoff-reports/scopes/list-known` and uses them in a searchable scope combobox. Selecting a scope sends its required `scope_id` to `POST /v1/handoff-reports/get`; neither the Project catalog nor `project_id` participates in report selection. The page presents the exact current Handoff snapshot at full width. +The page posts the selected `ScopeSelection` to `/v1/handoff-reports/get`. The Server resolves it to exact Scope IDs +and projects each Scope's descriptor and latest exact Handoff. A Scope without a committed Handoff remains visible as +`no_handoff`. Parent does not infer Context sharing, and the report does not edit Handoff state. -The current snapshot displays objective, current state, disposition, next action, and known omissions as one Handoff document. One Edit action opens all five fields, and one Save Revision action prepares and commits the complete document as a new immutable Handoff Revision. Scope switching and background refresh pause while the editor is open. Receiver-side decisions are not part of this page; existing continuity records remain available in the read-only Continuity timeline. Apart from the explicit revision write, the browser formats returned `summary`, `coverage`, Workstream state, and digests without recalculating report semantics. - -When known-scope discovery succeeds but no scope has a committed Handoff, the page replaces report controls with a clearly labeled, data-free template preview. Retry enumerates Handoff heads again; the first committed scope replaces the preview. The preview neither creates a Handoff nor requests fabricated report data. - -The page requests the current day in UTC by default and provides current-day, ISO-week, calendar-month, and custom date-range inputs. The custom end date is inclusive in the UI and is converted to the exclusive start of the next day for the API. The current scope application normalizes this input but supplies no Activity events, reports `activity_coverage=not_configured`, and returns no period comparison. Handoff status comes from the current exact selection and must not be presented as a historical period-end state. - -The overview request may disable evidence checks for lower latency. A Markdown download makes a separate request with `format=markdown`, `download=true`, and evidence checks enabled by default. The browser never reconstructs Markdown from rendered DOM or canonical JSON. Both background refresh and browser download currently require a stored bearer token even when Server authentication is disabled; initial and manual report loads still work without one. Disabling Handoff Report removes the `/handoff-reports` page and its API while leaving the original Dashboard route, scope selection, and statistics request unchanged. +JSON is the browser projection. Markdown download repeats the same selection with `format=markdown` and +`download=true`; the browser does not reconstruct Markdown from the rendered DOM. Disabling Handoff Report removes +the page and report API without changing Dashboard selection or statistics behavior. ## Preserve the security boundary diff --git a/docs/en/docs/explanation/core-concepts.md b/docs/en/docs/explanation/core-concepts.md index 4ed93065d..657d3b6ad 100644 --- a/docs/en/docs/explanation/core-concepts.md +++ b/docs/en/docs/explanation/core-concepts.md @@ -11,11 +11,12 @@ Agent turn. Every value belongs to a scope. ## Scope is the isolation boundary -Every content operation uses a `scope_id`. The scope selects an isolated Source journal, Memory lifecycle, Candidate -inbox, Handoff history, and related runtime state. Integrations can derive a scope from a repository or path, while -public interfaces also allow callers to supply one explicitly. +Every content operation uses a `scope_id`. The Scope selects an isolated Source journal, Memory lifecycle, Candidate +inbox, Handoff history, and related runtime state. Scope IDs are opaque Server identifiers. Integrations resolve an +explicit Scope, a durable binding, or the Server default; repository, path, session, and Agent identities are binding +inputs rather than Scope IDs. -A scope ID selects data. It does not prove user identity, grant tool access, or authorize execution. +A Scope ID selects data. It does not prove user identity, grant tool access, or authorize execution. ## Sources preserve evidence @@ -89,9 +90,8 @@ inspected boundary and returns a temporary Prepared Handoff. Committing a Handof the user wants a milestone. The receiver resolves the Handoff and records an Acknowledgement; a Task Outcome preserves the final status and checks as Source evidence. -The [Handoff Report](../how-to/use-handoff-report.md) projects current Handoff Revisions for inspection and export. The -current scope report does not yet include Activity events or period comparison, and it does not rewrite Memory or the -underlying Handoff history. +The [Handoff Report](../how-to/use-handoff-report.md) projects the latest Handoff Revision in each selected Scope for +inspection and export. It is read-only and does not rewrite Memory or the underlying Handoff history. ## Interfaces expose different parts of the same Server diff --git a/docs/en/docs/how-to/configure-claude-code.md b/docs/en/docs/how-to/configure-claude-code.md index cded5130e..af89d38e5 100644 --- a/docs/en/docs/how-to/configure-claude-code.md +++ b/docs/en/docs/how-to/configure-claude-code.md @@ -58,7 +58,7 @@ PowerContext Server data. For each user prompt, the Hook: -1. derives the same project scope as the Codex integration; +1. resolves the current Scope from explicit, session, workspace, and default bindings; 2. calls `POST /v1/context/prepare` at most once; 3. strictly validates `powercontext.prepared-context.v1` and injects it unchanged through `additionalContext`; 4. independently captures the prompt as ordinary Content Source evidence. @@ -73,20 +73,19 @@ Skill. Scope resolution uses this order: 1. `POWERCONTEXT_CLAUDE_SCOPE_ID`, when explicitly set; -2. the Git-private Workstream binding shared with Codex; -3. the normalized `remote.origin.url` of the Git top-level directory; -4. a `local:sha256:<digest>` identifier derived from the resolved project directory. +2. a durable session binding stored by PowerContext; +3. a durable workspace binding stored by PowerContext; +4. the Server's default Scope. -Claude Code and Codex therefore resolve the exact same scope in a checkout that has a Workstream binding. Without a -binding they still share the normalized remote scope. Bind a known Workstream with the bundled resolver: +Bind a known Scope to the checkout with the bundled resolver: ```bash -python3 "${CLAUDE_PLUGIN_ROOT}/scripts/project_scope.py" \ - --cwd "$PWD" --bind-workstream "WORKSTREAM_SCOPE_ID" +python3 "${CLAUDE_PLUGIN_ROOT}/scripts/workspace_scope.py" \ + --cwd "$PWD" --bind-scope "SCOPE_ID" ``` -The local fallback is stable for one resolved directory, but it is not intended to join unrelated checkouts. Set an -explicit scope only when that separation or sharing is deliberate. +The resolver hashes the workspace path only as an external binding key. It never generates a Scope ID from a Git +remote or directory. Set an explicit Scope only when that separation or sharing is deliberate. ## Use explicit Memory and Handoff operations @@ -122,8 +121,8 @@ export POWERCONTEXT_CLAUDE_CAPTURE_PROMPTS=false claude ``` -Use `POWERCONTEXT_CLAUDE_SCOPE_ID` only when the Memory scope must intentionally differ from both the Git remote and -local project path. +Use `POWERCONTEXT_CLAUDE_SCOPE_ID` only when the current work must intentionally override durable bindings and the +Server default. `POWERCONTEXT_CLAUDE_FLUSH_ON_CAPTURE=true` makes the Hook wait for Source processing and is intended for tests, not normal interactive use. diff --git a/docs/en/docs/how-to/configure-codex.md b/docs/en/docs/how-to/configure-codex.md index 57d6b74b1..306226104 100644 --- a/docs/en/docs/how-to/configure-codex.md +++ b/docs/en/docs/how-to/configure-codex.md @@ -36,27 +36,20 @@ handoff this work ``` The `project-context` Skill treats that imperative as explicit authorization to create one durable Handoff milestone. -If the catalog contains multiple Workstreams, Codex first opens a native picker; one Workstream is selected -automatically when it is the only candidate. Codex binds the selected Workstream to the checkout, inspects the current -conversation and repository, assembles the objective, branch and worktree state, changed files, observed checks, -blockers, omissions, and next action, then calls `handoff_current_work` followed by `commit_handoff`. After a successful -commit, Codex reports the selected Workstream and exact Handoff Revision; the user does not need to fill in the Handoff -content or confirm the commit again. +Codex inspects the current conversation and repository, assembles the objective, branch and worktree state, changed +files, observed checks, blockers, omissions, and next action, then calls `handoff_current_work` followed by +`commit_handoff` in the current Session Scope. After a successful commit, Codex reports the exact Handoff Revision; the +user does not need to fill in the Handoff content or confirm the commit again. `交接`, `交接当前工作`, and `commit a handoff` use the same behavior. To inspect the proposed content without writing, ask to `preview the handoff without committing`; the Skill renders the proposed fields in chat and calls no write tool. Discussing Handoff design or asking how it works does not authorize a write. -Codex resolves scope in this order: an explicit `POWERCONTEXT_CODEX_SCOPE_ID`, a Workstream scope persistently bound -to the current Git workspace, the normalized Git remote, and finally the project path. Later Codex sessions in the -same workspace reuse that scope. - -The picker returns the Workstream's human-facing `work_id` and authoritative `scope_id`. The `project-context` Skill -passes that exact scope to the resolver's `--bind-workstream` operation and verifies the result. The binding lives in -`powercontext/codex-workspace.json` below the Git-private directory, outside the worktree and commits. A one-line -Handoff then continues the selected Workstream's Artifact lifecycle and creates the next Revision. If the MCP client -does not support native elicitation, the tool returns structured choices instead; the integration must still obtain an -explicit selection and must not choose silently. +At Session start, Codex resolves Scope in this order: an explicit `POWERCONTEXT_CODEX_SCOPE_ID`, an existing Session +binding, a host-managed workspace binding, and the Server's default Scope. The selected Scope is fixed to the Session. +Repository and directory identities are lookup inputs only; they never generate a Scope ID. The prompt hook uses the +binding for recall and capture, while `PreToolUse` injects it into data-plane tools so Agent input cannot redirect a +read or write. The host must create or bind a different Scope when the Session changes work boundaries. The Hook calls `POST /v1/context/prepare` once before Codex analyzes the prompt. It requests an 8000-byte total budget, strictly validates `powercontext.prepared-context.v1`, and injects the returned content unchanged. The Runtime labels diff --git a/docs/en/docs/how-to/configure-dsh.md b/docs/en/docs/how-to/configure-dsh.md index 2de6affb7..da5486c95 100644 --- a/docs/en/docs/how-to/configure-dsh.md +++ b/docs/en/docs/how-to/configure-dsh.md @@ -30,7 +30,9 @@ The plugin has two paths to the same Server: - before each model step it asks the Runtime to prepare one final, bounded context value, then independently captures the user's prompt as Source evidence; - named `pc_*` tools call the public HTTP API to remember, search, revise, retire, and audit Memory. -Memory scope comes from the normalized Git remote when one is available, or from the session workspace path otherwise. Set `POWERCONTEXT_DSH_SCOPE_ID` when the session has no workspace cwd, or when the scope must be independent of both. The plugin does not fall back to the Harness process directory. +The plugin resolves one Server-owned Scope in this order: `POWERCONTEXT_DSH_SCOPE_ID`, a durable binding for the +session workspace, then the Server default. The workspace path is hashed only as an external binding key. A missing +workspace therefore uses the Server default instead of the Harness process directory. The plugin calls `POST /v1/context/prepare` once before the model analyzes the prompt. Explicit `remember_memory` calls do not require a model. diff --git a/docs/en/docs/how-to/configure-hermes.md b/docs/en/docs/how-to/configure-hermes.md index aaaa7afbf..443e11086 100644 --- a/docs/en/docs/how-to/configure-hermes.md +++ b/docs/en/docs/how-to/configure-hermes.md @@ -52,14 +52,13 @@ hermes powercontext search "Python package manager" ``` Inside an interactive Hermes session, `/pc status` should reach the same active provider. Use `/pc ` followed by -Tab/Down to inspect the available Memory, Handoff, Experience, Skill, review, statistics, trace, and Workstream +Tab/Down to inspect the available Memory, Handoff, Experience, Skill, review, statistics, trace, and Scope commands. Hermes 0.20.4 does not provide enough invocation context to route gateway slash commands safely, so the companion rejects gateway invocations; use the provider's Hermes tools in gateway sessions. -The provider uses `http://127.0.0.1:8000` by default. In a Git workspace, Workstream persistence first reads the -shared `.git/powercontext/codex-workspace.json` scope binding. An explicit scope configuration takes precedence. -Without either value, the provider derives a scope from the active Hermes profile and gateway user identifier; for a -local CLI session without a user identifier, it derives a stable value from `HERMES_HOME`. +The provider uses `http://127.0.0.1:8000` by default. The Server resolves an explicit Scope first, then durable session +and workspace bindings, and finally its default Scope. Hermes hashes the workspace path only as an external binding +key; it does not generate Scope IDs from profiles, users, repositories, or directories. ## Configure the connection @@ -72,7 +71,7 @@ the file: | `POWERCONTEXT_HERMES_BASE_URL` | PowerContext Server URL | | `POWERCONTEXT_HERMES_AUTHORIZATION` | Complete authorization header, such as `Bearer <token>` | | `POWERCONTEXT_HERMES_TOKEN` | Bare-token shorthand used when `AUTHORIZATION` is absent | -| `POWERCONTEXT_HERMES_SCOPE_ID` | Explicit scope or scope template | +| `POWERCONTEXT_HERMES_SCOPE_ID` | Explicit server-owned Scope ID | | `POWERCONTEXT_HERMES_MAX_BYTES` | Maximum prepared-context size, from 512 to 32768 bytes | | `POWERCONTEXT_HERMES_TIMEOUT` | HTTP request timeout in seconds | | `POWERCONTEXT_HERMES_CAPTURE_TURNS` | Capture completed turns as Sources | @@ -80,7 +79,6 @@ the file: | `POWERCONTEXT_HERMES_CAPTURE_PRE_COMPRESS` | Capture filtered new turns before compression; disabled by default | | `POWERCONTEXT_HERMES_EVALUATION_TRACE` | Record recalled context in sensitive local JSONL traces; disabled by default | | `POWERCONTEXT_HERMES_EVALUATION_TRACE_PATH` | Override the evaluation trace directory | -| `POWERCONTEXT_HERMES_WORKSTREAM` | Read the shared Git-private Workstream binding; enabled by default | Let the Hermes wizard store authorization in its protected `.env` secret store; do not put the token in `config.json`. Use plain HTTP only for a loopback Server. See [Deploy the Server](deploy-server.md) before connecting diff --git a/docs/en/docs/how-to/configure-langchain.md b/docs/en/docs/how-to/configure-langchain.md index 6d13778ae..bcfacbff9 100644 --- a/docs/en/docs/how-to/configure-langchain.md +++ b/docs/en/docs/how-to/configure-langchain.md @@ -50,7 +50,7 @@ agent = create_agent( result = await agent.ainvoke( {"messages": [{"role": "user", "content": "How should we deploy this service?"}]}, - context=PowerContextScope(scope_id="git:github.com/acme/api"), + context=PowerContextScope(), ) ``` @@ -99,13 +99,13 @@ LangGraph adapter's scope or environment prefix: | --- | --- | --- | | `POWERCONTEXT_LANGCHAIN_BASE_URL` | `http://127.0.0.1:8000` | PowerContext Server URL | | `POWERCONTEXT_LANGCHAIN_TOKEN` | unset | Bare bearer token passed to the Client | -| `POWERCONTEXT_LANGCHAIN_SCOPE_ID` | derived | Durable scope shared across runs | +| `POWERCONTEXT_LANGCHAIN_SCOPE_ID` | unset | Existing Server Scope to use instead of the Server default | | `POWERCONTEXT_LANGCHAIN_TIMEOUT` | `10` | Client timeout in seconds | | `POWERCONTEXT_LANGCHAIN_MAX_BYTES` | `8000` | Prepared-context size limit | -An explicit `PowerContextScope` value wins over environment configuration. If no explicit scope exists, PowerContext -derives one from the current Git remote; if neither is available, recall and capture fail open without interrupting the -agent. The token remains in Client configuration and never enters agent state or message content. +An explicit `PowerContextScope` value wins over environment configuration and must identify an existing Server Scope. +If neither is set, the Server default Scope is used. The adapter never derives a Scope ID from Git, a path, the Agent, +or the prompt. The token remains in Client configuration and never enters agent state or message content. ## Failure behavior diff --git a/docs/en/docs/how-to/configure-langgraph.md b/docs/en/docs/how-to/configure-langgraph.md index 849937e8e..03df40a66 100644 --- a/docs/en/docs/how-to/configure-langgraph.md +++ b/docs/en/docs/how-to/configure-langgraph.md @@ -49,7 +49,7 @@ agent = create_react_agent( context_schema=PowerContextScope, checkpointer=my_checkpointer, ) -await agent.ainvoke(state, context=PowerContextScope(scope_id="git:github.com/acme/api")) +await agent.ainvoke(state, context=PowerContextScope()) ``` The recall hook and the Memory tools are async, so drive the graph with `ainvoke`/`astream`; a synchronous @@ -80,7 +80,7 @@ builder.add_edge(START, "recall") builder.add_edge("recall", "model") graph = builder.compile(checkpointer=my_checkpointer) -await graph.ainvoke(state, context=PowerContextScope(scope_id="git:github.com/acme/api")) +await graph.ainvoke(state, context=PowerContextScope()) ``` The recall hook and the tools read the active `PowerContextScope` from the LangGraph runtime, so a single value on @@ -95,7 +95,7 @@ Configuration is read through pydantic-settings with the prefix `POWERCONTEXT_LA | --- | --- | --- | | `POWERCONTEXT_LANGGRAPH_BASE_URL` | `http://127.0.0.1:8000` | PowerContext Server URL | | `POWERCONTEXT_LANGGRAPH_TOKEN` | unset | Bare token forwarded to `PowerContextClient` | -| `POWERCONTEXT_LANGGRAPH_SCOPE_ID` | derived | Durable scope shared across runs | +| `POWERCONTEXT_LANGGRAPH_SCOPE_ID` | unset | Existing Server Scope to use instead of the Server default | | `POWERCONTEXT_LANGGRAPH_TIMEOUT` | `10` | Client timeout in seconds | | `POWERCONTEXT_LANGGRAPH_MAX_BYTES` | `8000` | Prepared-context size limit | @@ -109,16 +109,14 @@ used only to authenticate the Client; it never appears in graph state or agent-v ## Resolve the scope -The scope for a run is resolved in this order: +The adapter asks the Server to resolve the Scope for every operation: -1. an explicit `scope_id` on `PowerContextScope`, or `POWERCONTEXT_LANGGRAPH_SCOPE_ID`; -2. a scope derived from the current Git remote; -3. otherwise the adapter raises `MissingScopeError`. +1. an explicit, existing `scope_id` on `PowerContextScope`, or `POWERCONTEXT_LANGGRAPH_SCOPE_ID`; +2. otherwise the Server default Scope. -This priority is **inverted** relative to the Codex plugin, which prefers the Git- or path-derived local scope. A -LangGraph deployment is typically a long-running service whose working directory has no relationship to the project, -so explicit configuration is the primary path and Git derivation is the fallback. When neither is available the -adapter raises rather than defaulting to a shared local scope, which would place unrelated tenants together. +Scope IDs are Server-owned opaque identifiers. The adapter never derives one from the process working directory, a +Git remote, or a filesystem path. An explicit ID is validated by the Server before the operation continues; obtain it +from the Scope API rather than inventing it locally. ## Treat recalled context as untrusted history diff --git a/docs/en/docs/how-to/configure-openclaw.md b/docs/en/docs/how-to/configure-openclaw.md index 2db4fe700..9bd26d1db 100644 --- a/docs/en/docs/how-to/configure-openclaw.md +++ b/docs/en/docs/how-to/configure-openclaw.md @@ -52,16 +52,25 @@ Explicit search and get calls use `/v1/memory/search` and `/v1/memory/entries/ge `/v1/context/prepare`. Search limits the query to 8192 characters and clamps the requested result limit to 1–50 (default 10), while each get returns at most 120 lines and 12,000 characters. -## Choose the memory scope +## Choose the memory Scope -Scope mode defaults to `agent`, which derives the memory scope from the OpenClaw agent identity. Use project scope -when the memory must be shared across agents working in the same project: +The plugin asks the Server to resolve one existing Scope before each operation. The Server checks, in order: + +1. the plugin's explicit `scopeId`; +2. durable bindings for the OpenClaw session, each ordered active project, and the agent identity; +3. the Server's default Scope. + +Agent, project, path, and session identities are binding lookup inputs only. The plugin never derives a Scope ID from +them and never creates a Scope. To select one existing Scope explicitly for all OpenClaw operations: ```bash -powercontext setup openclaw --scope-mode project +openclaw config set plugins.entries.memory-powercontext.config.scopeId scp_0123456789abcdefghjkmnpqrs +openclaw gateway restart ``` -Project scope is used only when OpenClaw supplies exactly one trusted project identity for a turn. +Without `scopeId`, provision a durable Server binding only when an OpenClaw host identity must retain a selection; +otherwise the Server default is used. The plugin does not persist bindings because OpenClaw currently has no Scope +selection contract. ## Connect to an authenticated Server diff --git a/docs/en/docs/how-to/configure-opencode.md b/docs/en/docs/how-to/configure-opencode.md index da146f78a..d34d029bf 100644 --- a/docs/en/docs/how-to/configure-opencode.md +++ b/docs/en/docs/how-to/configure-opencode.md @@ -45,11 +45,14 @@ Set variables before starting OpenCode: ```bash export POWERCONTEXT_OPENCODE_BASE_URL=http://127.0.0.1:8000 -export POWERCONTEXT_OPENCODE_SCOPE_ID=project:example export POWERCONTEXT_OPENCODE_CAPTURE_PROMPTS=true opencode ``` +Each OpenCode session resolves an explicit `POWERCONTEXT_OPENCODE_SCOPE_ID`, its durable Session binding, its +workspace binding, then the Server default. The resolved Scope is fixed to the Session so resume keeps the same +boundary. Set the explicit variable only to an existing Server-owned Scope. + For a Server using optional bearer authentication, set the complete header in `POWERCONTEXT_OPENCODE_AUTHORIZATION`. Never put credentials in the URL. Plain HTTP is accepted only for loopback hosts. Set `POWERCONTEXT_OPENCODE_CAPTURE_PROMPTS=false` when prompts must not be persisted as Source evidence. diff --git a/docs/en/docs/how-to/configure-pi.md b/docs/en/docs/how-to/configure-pi.md index 21724dd23..6998a1cf1 100644 --- a/docs/en/docs/how-to/configure-pi.md +++ b/docs/en/docs/how-to/configure-pi.md @@ -37,8 +37,9 @@ Eligible user prompts are captured separately as Content Sources. The package ne transcript. Recall, capture, and boundary flushing fail open: an unavailable Server, timeout, redirect, or invalid response leaves Pi's prompt unchanged and never blocks ordinary work. -The package derives scope from the normalized Git remote, falling back to the project path. Set an explicit scope only -when it must be independent of both. +The package resolves one Server-owned Scope in this order: `POWERCONTEXT_PI_SCOPE_ID`, a durable binding for the +workspace, then the Server default. The workspace path is hashed only as an external binding key; it never becomes a +Scope ID. Keep the explicit variable unset unless the host must force one existing Scope. ## Control prompt capture diff --git a/docs/en/docs/how-to/configure-pydantic-ai.md b/docs/en/docs/how-to/configure-pydantic-ai.md index 4cd53f2f9..09b8bb7c9 100644 --- a/docs/en/docs/how-to/configure-pydantic-ai.md +++ b/docs/en/docs/how-to/configure-pydantic-ai.md @@ -31,7 +31,7 @@ from powercontext_pydantic_ai import PowerContext agent = Agent( "openai:gpt-5.2", - capabilities=[PowerContext(scope_id="project:example")], + capabilities=[PowerContext()], ) ``` @@ -60,7 +60,7 @@ export POWERCONTEXT_PYDANTIC_AI_SCOPE_ID=project:example | --- | --- | --- | | `POWERCONTEXT_PYDANTIC_AI_BASE_URL` | `http://127.0.0.1:8000` | HTTP(S), without credentials, query, or fragment | | `POWERCONTEXT_PYDANTIC_AI_TOKEN` | unset | Bare printable token stored as `SecretStr` | -| `POWERCONTEXT_PYDANTIC_AI_SCOPE_ID` | derived | Non-empty scope, deterministically bounded to 256 characters | +| `POWERCONTEXT_PYDANTIC_AI_SCOPE_ID` | unset | Existing explicit Server Scope, up to 256 characters; unset selects the Server default | | `POWERCONTEXT_PYDANTIC_AI_TIMEOUT` | `10` | Positive seconds | | `POWERCONTEXT_PYDANTIC_AI_MAX_BYTES` | `8000` | `512`–`32768` prepared-context bytes | | `POWERCONTEXT_PYDANTIC_AI_CAPTURE_EVENTS` | `false` | Opt in to visible event capture | @@ -87,8 +87,11 @@ def tenant_scope(ctx: RunContext[dict[str, str]]) -> str: capability = PowerContext(settings=settings, scope_id=tenant_scope) ``` -The callback runs once per Agent run. Scope precedence is constructor string or callback, environment `SCOPE_ID`, -normalized Git origin, then `local:<sha256-of-project-path>`. Explicit configuration avoids Git subprocesses. +The callback runs once per Agent run. Scope precedence is constructor string or callback, then environment `SCOPE_ID`. +The adapter sends that explicit ID, or `None`, to `resolve_scope_binding` once per run and reuses the returned Scope ID +for every recall, capture, flush, and tool call in that run. Explicit IDs must identify existing Server Scopes; when +no ID is configured, the Server default is selected. The adapter does not inspect cwd, Git metadata, or paths to +create Scope IDs. ## Decide whether to capture events diff --git a/docs/en/docs/how-to/configure-workbuddy.md b/docs/en/docs/how-to/configure-workbuddy.md index 1f531bbd5..73f2a4487 100644 --- a/docs/en/docs/how-to/configure-workbuddy.md +++ b/docs/en/docs/how-to/configure-workbuddy.md @@ -69,8 +69,8 @@ cp "$PLUGIN"/hooks/workbuddy_powercontext_hook.py \ "$PLUGIN"/hooks/workbuddy_settings.py \ "$PLUGIN"/hooks/prepared_context.py \ "$WORKBUDDY_HOOKS_DIR"/ -cp "$PLUGIN/scripts/project_scope.py" \ - "$WORKBUDDY_HOOKS_DIR/powercontext_project_scope.py" +cp "$PLUGIN/scripts/workspace_scope.py" \ + "$WORKBUDDY_HOOKS_DIR/powercontext_scope_binding.py" ``` ### 2. Register the hook @@ -131,9 +131,9 @@ EOF Then replace `${POWERCONTEXT_PYTHON}` in `~/.workbuddy/skills/project-context/SKILL.md` with a shell-safe Python -executable argument. Replace `${POWERCONTEXT_PROJECT_SCOPE_SCRIPT}` with a +executable argument. Replace `${POWERCONTEXT_SCOPE_BINDING_SCRIPT}` with a shell-safe complete path to -`<WORKBUDDY_HOOKS_DIR>/powercontext_project_scope.py`. +`<WORKBUDDY_HOOKS_DIR>/powercontext_scope_binding.py`. ### 5. Start the Server, restart WorkBuddy, and verify @@ -214,7 +214,7 @@ changing them. | --- | --- | | `POWERCONTEXT_WORKBUDDY_SERVER_URL` | PowerContext server URL (default `http://127.0.0.1:8000`) | | `POWERCONTEXT_WORKBUDDY_AUTHORIZATION` | Complete authorization header, e.g. `Bearer <token>` | -| `POWERCONTEXT_WORKBUDDY_SCOPE_ID` | Explicit scope or scope template override | +| `POWERCONTEXT_WORKBUDDY_SCOPE_ID` | Explicit server-owned Scope ID | | `POWERCONTEXT_WORKBUDDY_CAPTURE_PROMPTS` | Capture user prompts as Sources (default `true`) | | `POWERCONTEXT_WORKBUDDY_FLUSH_ON_CAPTURE` | Flush until the captured Source is processed (testing only, default `false`) | | `POWERCONTEXT_WORKBUDDY_REQUEST_TIMEOUT_SECONDS` | Per-request HTTP timeout (default `1.0`) | @@ -227,19 +227,16 @@ query strings, or fragments; plain HTTP is accepted only for loopback hosts. ## Resolve the project scope -WorkBuddy resolves scope in this order: +The Server resolves Scope for WorkBuddy in this order: 1. an explicit `POWERCONTEXT_WORKBUDDY_SCOPE_ID`; -2. a Workstream scope persistently bound to the current Git workspace (stored - in `powercontext/codex-workspace.json` below the Git-private directory, - shared with the Codex and Claude Code plugins); -3. the normalized Git remote; -4. a hash of the resolved local project directory. - -Later WorkBuddy sessions in the same workspace reuse that scope. The -`project-context` Skill's `--bind-workstream` operation persists a Workstream -binding for a selected Handoff; the binding never enters the worktree or -commits. +2. a durable session binding; +3. a durable workspace binding; +4. the Server's default Scope. + +Later WorkBuddy sessions in the same workspace reuse that Scope. The `project-context` Skill's `--bind-scope` +operation persists the workspace binding in PowerContext. The workspace path is hashed only as an external binding +key; the plugin never derives a Scope ID from it. ## Connect to an authenticated local Server diff --git a/docs/en/docs/how-to/full-capability-runtime.md b/docs/en/docs/how-to/full-capability-runtime.md index bfb51e0be..b4adb2ee9 100644 --- a/docs/en/docs/how-to/full-capability-runtime.md +++ b/docs/en/docs/how-to/full-capability-runtime.md @@ -1,90 +1,52 @@ --- title: Full-capability Quick Start -description: Start all PowerContext capabilities in five minutes. +description: Configure models, start the Server, and verify the complete Memory loop. --- # Full-capability Quick Start -## Minimal versus full capability +`powercontext server run` works without model configuration, but model-backed extraction and vector search stay off. +The guided configuration enables generation, embeddings, scheduled Source processing, metrics, and tracing settings. -`powercontext server run` starts a minimal Server without any configuration. It stays up and accepts Sources, but the -capabilities that need models stay off. The guided `config init` flow writes one `.env` that turns everything on: - -| Capability | Default minimal server | Full-capability runtime | +| Capability | Minimal Server | Full-capability runtime | | --- | --- | --- | | Source capture | Enabled | Enabled | -| Memory extraction | Disabled; Sources stay pending | Enabled; Scheduler processes Sources every 60 s | -| Search modes | `auto, fts` only | `auto, fts, vector, hybrid` | -| Dashboard Scopes | None configured | `project:quickstart` visible | -| MCP endpoint | `/mcp` enabled | `/mcp` enabled | - -Both modes use SQLite by default. Vector search additionally uses the bundled `sqlite-vec` extension; when the -Embedding model or its profile is not configured, the Server falls back to SQLite FTS and reports -`Search modes: auto, fts`. Recall still works through FTS, but semantic and hybrid search need the Embedding model. - -## Choose the Scope ID first - -The Scope ID is PowerContext's data namespace. Think of it as the project ID. Sources, Memories, and Handoffs belong to -a Scope; the Dashboard and Coding Agent must use the same Scope ID for Agent-written data to appear in the web UI. - -A Server can store multiple Scopes. The Server configuration determines which Scopes the Dashboard can display, while -the Coding Agent configuration determines which Scope the current session reads and writes: - -```text -Coding Agent ── read/write ──> project:quickstart <── display ── Dashboard -``` - -Use any short, stable, non-empty string. Do not include keys or other secrets. For example: +| Memory extraction | Disabled | Enabled | +| Search modes | `auto, fts` | `auto, fts, vector, hybrid` | +| Dashboard | Default Scope | Default Scope and every created Scope | +| MCP endpoint | `/mcp` | `/mcp` | -```text -project:quickstart -git:github.com/oceanbase/powercontext -team:payment-service -``` - -This Quick Start uses: - -```text -project:quickstart -``` +The Server creates one opaque default Scope on first startup. The Dashboard discovers Scope descriptors from the +Server; it does not use a configured list. Integrations may bind a Session or workspace to that default or to another +existing Scope. -## Quick Start - -### Part 1: Start the Server - -#### 1. Install +## 1. Install and configure ```bash uv tool install --force "powercontext[cli,server] @ git+https://github.com/oceanbase/powercontext.git@master" +powercontext config init --output .env ``` -#### 2. Generate the configuration +Enter the provider connection and credential when prompted. For a local provider that ignores authentication, use a +non-secret placeholder accepted by that provider. + +Inspect and validate the generated file without printing credentials: ```bash -powercontext config init --output .env +powercontext config show --env-file .env +powercontext config validate --env-file .env ``` -Enter a provider credential when prompted. Pydantic AI providers require a credential during construction; for a -local service that ignores authentication, use a non-secret placeholder accepted by that service. - -When finished, the command prints setup and launch commands for Codex, Claude Code, DeepSeek Harness, OpenCode, and Pi. -The generated `.env` groups every setting you would otherwise assemble by hand: Server HTTP, Dashboard, Scope, -Generation model, Embedding model with profile ID and dimension, database kind and location, scheduler interval, and -per-host integration URLs. Inspect it any time with `powercontext config show --env-file .env`; credentials print as -`<redacted>`, and `powercontext config validate --env-file .env` checks the syntax and model settings. +The generated file contains Server, model, database, scheduler, and integration transport settings. Scope identity is +owned by the running Server and is not invented by the Config Generator. -#### 3. Start the Server +## 2. Start and verify the Server ```bash powercontext server run --env-file .env ``` -With `--env-file`, assignments in the file override same-named shell values, and stale `POWERCONTEXT_SERVER_*` -variables missing from the file are ignored. This makes `config validate` and `server run` use the same Server config. - -#### 4. Verify the Server - -Run this in a second terminal: +In another terminal: ```bash set -a @@ -95,126 +57,89 @@ powercontext ready powercontext capabilities ``` -Confirm these results: +The full runtime is ready when readiness is `ready`, Memory extraction is enabled, and search modes include `vector` +and `hybrid`. If only `auto, fts` appear, check the Embedding model, profile ID, dimension, credential, and Base URL. -```text -package: ok - powercontext <version> -server liveness: ok - http://127.0.0.1:8000 status=ok -server readiness: ok - http://127.0.0.1:8000 status=ready -Status: ready -Memory extraction: enabled -Search modes: auto, fts, vector, hybrid -``` - -The full-capability runtime is ready when `doctor` reports all checks as `ok`, `Status: ready`, -`Memory extraction: enabled`, all four search modes are listed, and the Dashboard at -<http://127.0.0.1:8000/> contains `Quick Start`. +Open <http://127.0.0.1:8000/> and confirm that the default Scope is available. Retrieve its opaque ID for the following +API checks: -If `powercontext capabilities` lists only `auto, fts`, the Server is running in FTS-only fallback mode. Vector and -hybrid search are unavailable, so the runtime does not meet the full-capability check above. +```bash +SCOPE_ID="$(curl -fsS http://127.0.0.1:8000/v1/scopes/default \ + | python -c 'import json, sys; print(json.load(sys.stdin)["scope_id"])')" +export SCOPE_ID +``` -### Part 2: Verify the Memory loop +## 3. Verify the Memory loop -Extraction runs when Sources are flushed, so verify one full round trip before starting a Coding Agent. Use a unique -Source ID so this check remains valid when the guide is run again. With the same environment loaded: +Capture a Source with a unique ID: ```bash SOURCE_ID="quickstart-$(date +%s)-$$" curl -fsS -X POST http://127.0.0.1:8000/v1/sources/content \ -H 'content-type: application/json' \ - -d "{\"scope_id\":\"project:quickstart\",\"source_id\":\"${SOURCE_ID}\",\"content\":\"PowerContext quick start check: prefer small, verifiable steps.\"}" + -d "{\"scope_id\":\"${SCOPE_ID}\",\"source_id\":\"${SOURCE_ID}\",\"content\":\"PowerContext quick start check: prefer small, verifiable steps.\"}" ``` -The Server replies `202` with `"status":"accepted"` and a numeric `position`; keep both the Source ID and position. -Then flush the Scope, which runs Memory extraction: +Keep the returned `position`, then flush the same Scope: ```bash -curl -X POST http://127.0.0.1:8000/v1/memory/flush \ +curl -fsS -X POST http://127.0.0.1:8000/v1/memory/flush \ -H 'content-type: application/json' \ - -d '{"scope_id":"project:quickstart"}' + -d "{\"scope_id\":\"${SCOPE_ID}\"}" ``` -The flush response contains `current_cursor`. It must be greater than or equal to the capture response's `position`. -The Scheduler may process the Source before this request, so `status:"idle"` is valid when the cursor has already -reached that position. If it has not, flush again. +The returned `current_cursor` must be at least the capture `position`. `status: "idle"` is valid when the Scheduler +already processed the Source. -Now list the current Memory entries: +List Memory entries: ```bash curl -fsS -X POST http://127.0.0.1:8000/v1/memory/entries/list \ -H 'content-type: application/json' \ - -d '{"scope_id":"project:quickstart"}' + -d "{\"scope_id\":\"${SCOPE_ID}\"}" ``` -Find an entry whose `source_refs` contains the capture response's `source_id`, and record that entry's -`citation.entry_id`. This proves the captured Source produced Memory. If no entry cites this Source, extraction ran but -produced no candidate; use a new Source ID with a clearer durable fact or preference and repeat the check. - -Confirm the inventory and verify Embedding by searching with vector mode: +Find an entry whose `source_refs` contains the captured Source and record its `citation.entry_id`. Then verify vector +retrieval: ```bash -curl -X POST http://127.0.0.1:8000/v1/memory/search \ +curl -fsS -X POST http://127.0.0.1:8000/v1/memory/search \ -H 'content-type: application/json' \ - -d '{"scope_id":"project:quickstart","query":"verifiable steps","mode":"vector","limit":50}' + -d "{\"scope_id\":\"${SCOPE_ID}\",\"query\":\"verifiable steps\",\"mode\":\"vector\",\"limit\":50}" ``` -Embedding is verified only when the response contains `"mode":"vector"` and a hit whose `citation.entry_id` equals -the source-linked entry recorded above and whose `matched_by` contains `"vector"`. A hit for another entry, an empty -`hits` list, or `"mode":null` does not verify this round trip. Check -`powercontext capabilities`: if `vector` is absent from `Search modes`, the Server is in FTS-only fallback mode; if it -is present, the source-linked entry has not been confirmed through vector search yet. An explicit vector request against -existing Memory returns HTTP 422 when vector capability is unavailable. - -Finally, check the stats for model usage: +The round trip is verified when the response has `mode: "vector"`, the recorded `entry_id`, and `vector` in +`matched_by`. Confirm model usage with: ```bash -powercontext stats --scope-id project:quickstart -``` - -```text -Embedding: 1 requests, ... +powercontext stats --scope-id "$SCOPE_ID" ``` -The Embedding request count is cumulative. A non-zero value corroborates model use, but only the source-linked vector -hit above proves this round trip. - -### Part 3: Start a Coding Agent - -The Config Generator prints setup and launch commands for every supported Coding Agent. Open a new terminal, choose an -Agent, and copy the two commands under it. The first installs the PowerContext integration; the second loads the -generated `.env` and starts the Agent, so you do not need to enter the Scope ID again. - -After the Coding Agent starts, send an ordinary prompt in the project. The integration first recalls relevant Memory -from `project:quickstart`, then saves the prompt as a Source. The Scheduler extracts Memory from new Sources within -about 60 seconds, so the flush from Part 2 is only needed once to prove the loop. - -## Where data lives +## 4. Start Codex -The generated configuration leaves the database unset, so the Server stores data in the user data directory instead of -a project-local file. With `POWERCONTEXT_HOME` unset, SQLite keeps `powercontext.db` and the scheduler state in -`scheduler.db` under: +Install the plugin using the command printed by Config Generator, load `.env`, and start Codex. Do not set +`POWERCONTEXT_CODEX_SCOPE_ID` for the normal Session flow: the plugin resolves the Session binding, then the workspace +binding, then the Server default Scope. Set it only when the host must select a known existing Scope explicitly. -- macOS: `~/Library/Application Support/powercontext/` -- Linux: `~/.local/share/powercontext/` +After Codex starts, send an ordinary prompt. The plugin recalls from the bound Scope and captures the prompt as Source +evidence. Scheduled processing handles new Sources within the configured interval. -Set `POWERCONTEXT_HOME` before starting the Server to relocate all of this. Changing the database URL later points the -Server at a different (possibly empty) database; keep the previous value if you need the old data. +## Data and restart behavior -## Stop and restart +With no database override, SQLite stores `powercontext.db` and `scheduler.db` under the user data directory: -Press `Ctrl+C` in the Server terminal to stop it. Data persists in SQLite across restarts. To resume, load the same -`.env` and run `powercontext server run --env-file .env` again; pending Sources are processed on the next Scheduler run -or flush. +- Linux: `$XDG_DATA_HOME/powercontext`, or `~/.local/share/powercontext`; +- macOS: `~/Library/Application Support/powercontext`. -## Quick troubleshooting +Press `Ctrl+C` to stop the Server. Restart it with the same `.env` and data directory. The default Scope and its opaque +ID remain stable because they are persisted in the database. | Symptom | Action | | --- | --- | -| Dashboard is empty | Compare the complete Dashboard and Agent Scope strings | -| `ready` is `degraded` | Check the Generation and Embedding models, keys, and Base URLs | -| No `vector` or `hybrid` search | Configure the Embedding model, profile ID, and dimension together; without them recall stays on FTS (`auto, fts`) | +| A Scope is missing from Dashboard | Confirm it was created through the Scope API and refresh the page | +| Readiness is `degraded` | Check model identifiers, credentials, and Base URLs | +| No `vector` or `hybrid` mode | Configure Embedding model, profile ID, and dimension together | | Sources remain pending | Enable the Scheduler or call `/v1/memory/flush` | | Existing data is missing | Restore the previous database URL or `POWERCONTEXT_HOME` | -See [Troubleshooting](troubleshoot.md) for error states and [Configuration](../reference/configuration.md) for all -variables. +See [Troubleshooting](troubleshoot.md) and [Configuration](../reference/configuration.md) for details. diff --git a/docs/en/docs/how-to/handoff-with-codex.md b/docs/en/docs/how-to/handoff-with-codex.md index d03257622..b80644fc2 100644 --- a/docs/en/docs/how-to/handoff-with-codex.md +++ b/docs/en/docs/how-to/handoff-with-codex.md @@ -17,8 +17,8 @@ state, the receiver records whether it can continue, and a Task Outcome preserve ## Before you start Complete [Install and run](install-and-run.md), keep the Server running, and start a Codex session with the -PowerContext plugin configured in the current project. Work records belong to the selected scope. If the Report catalog -contains more than one Workstream, let Codex show the picker and choose the intended one. +PowerContext plugin configured in the current project. The integration binds the Session to a Scope before reading or +writing work records. Start independent work in a new Scope only when it needs its own isolation and continuation. Do not put secrets, access tokens, or other sensitive information in Work Contracts, Handoffs, acknowledgements, or outcomes. @@ -42,9 +42,9 @@ For a durable milestone, use a direct imperative: > Hand off this work with PowerContext. Inspect the current objective, branch, worktree, changed files, checks, > blockers, omissions, and next action. Commit the completed Handoff and give me its exact Revision. -The Codex Skill selects the Workstream, inspects live state, calls `handoff_current_work`, and commits the returned -Prepared Handoff in the same turn. Success includes the scope and exact Handoff Revision. If preparation succeeds but -commit fails, the boundary Source exists but no durable milestone was created. +The Codex Skill uses the current Session Scope, inspects live state, calls `handoff_current_work`, and commits the +returned Prepared Handoff in the same turn. Success includes the Scope and exact Handoff Revision. If preparation +succeeds but commit fails, the boundary Source exists but no durable milestone was created. For a read-only preview, say `Preview a PowerContext Handoff and make no writes.` For temporary transfer without a milestone, ask Codex to prepare a Handoff without committing it. That operation records the boundary Source and returns diff --git a/docs/en/docs/how-to/install-and-run.md b/docs/en/docs/how-to/install-and-run.md index 9ec07c483..d6698645f 100644 --- a/docs/en/docs/how-to/install-and-run.md +++ b/docs/en/docs/how-to/install-and-run.md @@ -38,7 +38,7 @@ powercontext setup select --host codex --host dsh --source oceanbase/powercontex ``` Without `--server-url`, Claude Code and OpenClaw keep their `http://127.0.0.1:8000` defaults. An explicit -`--server-url` overrides both selected hosts. OpenClaw's `--scope-mode` defaults to `agent`. Selected Codex, DSH, +`--server-url` overrides both selected hosts. Selected Codex, DSH, OpenCode, Pi, and Hermes integrations pass their existing post-install diagnostics before they are reported as installed. After installing Hermes, run `hermes memory setup` and select PowerContext before starting Hermes. @@ -55,7 +55,7 @@ With no environment variables, the Server: - binds to `127.0.0.1:8000`; - enables Streamable HTTP MCP at `/mcp`; -- enables the Dashboard at `/`; when no scopes are configured, the page shows an explicit empty state; +- creates a default Scope and enables the Dashboard at `/`; - creates a persistent SQLite database in the operating system's user data directory; - supports explicit Memory operations without an inference provider. diff --git a/docs/en/docs/how-to/use-handoff-report.md b/docs/en/docs/how-to/use-handoff-report.md index 6a2724d0b..68cb5f991 100644 --- a/docs/en/docs/how-to/use-handoff-report.md +++ b/docs/en/docs/how-to/use-handoff-report.md @@ -1,12 +1,12 @@ --- title: Use Handoff Report -description: Open the Server report, select a scope, inspect Handoff history, and save a Revision. +description: Select a Scope view, inspect current Handoffs, and download a Markdown report. --- # Use Handoff Report -Handoff Report presents committed Handoff Revisions in a Server-owned web page. Use it to inspect current work by -scope, save a complete Handoff snapshot, or request a Markdown projection. +Handoff Report is a read-only view of the latest committed Handoff in each selected Scope. It does not create or edit +Scopes or Handoffs. ## Before you start @@ -17,62 +17,40 @@ powercontext server run ``` Handoff Report is enabled by default at `http://127.0.0.1:8000/handoff-reports`. It uses the Server listener and -authentication settings, but does not require the statistics Dashboard or its scope list. If bearer authentication is +authentication settings, but does not require the statistics Dashboard to be enabled. If bearer authentication is enabled, enter the configured token in the page sign-in form. -In the default unauthenticated mode, initial and manual report loads work without a token. The current browser code -requires a stored bearer token for background refresh and Markdown download, so those two controls do not issue report -requests until authentication is enabled and the page has a token. +The Server creates a default Scope during startup. Additional Scopes appear after they are created through an +integration or the Scope API. A Scope does not need a committed Handoff to appear in the report. -The page discovers scopes that contain at least one committed Handoff. Without one, it shows a data-free template -preview and disables search, period filters, editing, and download. +## 1. Commit a Handoff -## 1. Commit a Handoff in the target scope +Create a durable Handoff milestone in the Scope you want to report. In Codex, follow +[Hand off work in Codex](handoff-with-codex.md). The Codex integration writes to the Scope bound to the current Session. -Create a durable Handoff milestone in the scope you want to report. In Codex, follow -[Hand off work in Codex](handoff-with-codex.md) and keep the exact scope and Handoff Revision from the result. +The report reads committed Handoff Revisions only. A temporary Prepared Handoff is not included. -Reload Handoff Report after the commit succeeds. The page calls `list_handoff_report_known_scopes` and should include -the scope. Committing a Handoff makes the scope discoverable; no Report Project or Workstream registration is required. +## 2. Select a Scope view -## 2. Select a scope +Open Handoff Report and choose one of the shared Scope selections: -Search by `scope_id`, then select the scope. The page requests its report with `scope_id` and shows the current -objective, state, disposition, next action, and known omissions. +- **All** includes every Scope visible to this Server. +- **Scope and descendants** includes one root Scope and all of its descendants. +- **Focus** includes exactly one Scope. -The report also shows the latest Handoff history, newest first. The JSON projection contains at most the latest 20 -Revision summaries and marks when earlier history was truncated. The HTTP request schema retains an optional -`project_id` field for wire compatibility; it is deprecated and ignored when the Server generates a scope report. +Parent only expresses organization. It does not make a child's Context or Handoff visible to the parent, so each row +shows only that Scope's own latest Handoff. A selected Scope without a committed Handoff is shown as **No Handoff**. -The page starts a five-second refresh timer, but background requests currently run only when a bearer token is stored. -With authentication disabled, use **Refresh** to load changes manually. Background refresh also pauses while edits are -unsaved or a Handoff action is running. +Use **Refresh** after a Handoff or Scope changes. -## 3. Save a new Handoff Revision +## 3. Read or download the report -Select **Edit**, update the five current-snapshot fields as one document, then select **Save Revision**. The Server -prepares and commits the complete document as a new immutable Handoff Revision. +The page shows the selected Scopes, their parent relationship, Handoff status, objective, next action, and exact +Revision address. Summary counts use the same frozen selection as the rows. -Saving is a write operation. Scope switching stays paused while the editor is open. The page does not record receiver -acceptance; acknowledgements and Task Outcomes remain read-only entries in the **Continuity timeline**. - -## 4. Understand the current period controls - -The current scope report accepts and normalizes day, week, month, or custom period input, but Activity integration is -not configured. It returns no Activity events, reports `activity_coverage: not_configured`, and does not produce a -previous-period comparison. - -Do not use the period controls to infer historical work or compare Activity yet. The Handoff snapshot is the current -exact selection, not a reconstructed state at the end of the chosen period. - -## 5. Download Markdown - -With bearer authentication enabled and a token stored in the page, select **Download Markdown** to export the same -scope, locale, and normalized period. The browser requests Markdown from the Server rather than rebuilding it from the -rendered page. Downloads enable evidence checks by default and use the filename `handoff-report.md`. - -In the default unauthenticated mode, the current browser guard does not send this download request. The underlying HTTP -operation and Python Client remain available without a token while Server authentication is disabled. +Select **Download Markdown** to request the Markdown projection from the Server. The browser does not rebuild the +report from the rendered page. The JSON and Markdown projections carry selection and report digests so a consumer can +identify the exact generated result. ## Disable Handoff Report @@ -83,8 +61,8 @@ export POWERCONTEXT_SERVER_HANDOFF_REPORT_ENABLED=false powercontext server run ``` -Disabling the feature removes `/handoff-reports` and the Report API routes. The Dashboard, HTTP API, MCP, Memory, and +Disabling the feature removes `/handoff-reports` and the Report API route. The Dashboard, HTTP API, MCP, Memory, and Handoff operations remain independently configured. -For scope discovery and Report operations, see [Interfaces](../reference/interfaces.md). For exact Server settings, -see [Configuration](../reference/configuration.md). +For the Scope and Report operations, see [Interfaces](../reference/interfaces.md). For exact Server settings, see +[Configuration](../reference/configuration.md). diff --git a/docs/en/docs/reference/configuration.md b/docs/en/docs/reference/configuration.md index c0ee374e0..2d272db23 100644 --- a/docs/en/docs/reference/configuration.md +++ b/docs/en/docs/reference/configuration.md @@ -57,7 +57,6 @@ Server settings use the `POWERCONTEXT_SERVER_` prefix. | `POWERCONTEXT_SERVER_AUTH_TOKEN` | unset | Static bearer token; required when authentication is enabled | | `POWERCONTEXT_SERVER_ALLOW_UNAUTHENTICATED_NON_LOOPBACK` | `false` | Opt in to a non-loopback bind while authentication is disabled | | `POWERCONTEXT_SERVER_DASHBOARD_ENABLED` | `true` | Enable the Dashboard at the Server root path `/` | -| `POWERCONTEXT_SERVER_DASHBOARD_SCOPES` | `[]` | JSON array of selectable Dashboard scopes | | `POWERCONTEXT_SERVER_HANDOFF_REPORT_ENABLED` | `true` | Enable Handoff Report and its API routes | | `POWERCONTEXT_SERVER_LOGGING_LEVEL` | `INFO` | Operational log level | | `POWERCONTEXT_SERVER_LOGGING_FORMAT` | `console` | `console` or structured `json` output | @@ -101,9 +100,9 @@ practice, such as an in-process ASGI app, Unix-domain socket, or TLS-terminating `http_client` and pass `trust_transport_security=True` explicitly. See [Deploy the Server](../how-to/deploy-server.md) for a safe Docker and remote-access setup. -The Dashboard is enabled by default and shares the Server listener and port with the HTTP API and MCP. With no scopes -configured, the page shows an empty state. Dashboard initialization failures are logged with their direct cause and do -not prevent the Server HTTP API, MCP, or health checks from starting. +The Dashboard is enabled by default and shares the Server listener and port with the HTTP API and MCP. It discovers +the default Scope and every created Scope from the Server. Dashboard initialization failures are logged with their +direct cause and do not prevent the Server HTTP API, MCP, or health checks from starting. When bearer authentication is enabled, the HTML shells at `/`, `/skills`, `/reviews`, and `/handoff-reports`, plus their static assets, remain public so the browser can render the sign-in form. Data requests stay protected. Enter the @@ -295,7 +294,7 @@ only through the environment so it does not appear in command-line arguments. | Variable | Default | Meaning | | --- | --- | --- | -| `POWERCONTEXT_CODEX_SCOPE_ID` | derived from Git remote or project path | Override project scope | +| `POWERCONTEXT_CODEX_SCOPE_ID` | unset | Explicitly select an existing Scope instead of resolving bindings and the Server default | | `POWERCONTEXT_CODEX_AUTHORIZATION` | unset | Complete `Bearer <token>` header for Hook and MCP requests | | `POWERCONTEXT_CODEX_CAPTURE_PROMPTS` | `true` | Capture user prompts as Source evidence | | `POWERCONTEXT_CODEX_FLUSH_ON_CAPTURE` | `false` | Wait for Source processing after capture | @@ -304,15 +303,16 @@ only through the environment so it does not appear in command-line arguments. | `POWERCONTEXT_CODEX_FLUSH_MAX_CALLS` | `4` | Maximum flush calls per prompt | The outer Codex hook timeout is ten seconds. Recall, capture, and flush fail independently and never block Codex when -the Server is unavailable or rejects authentication. The variable must be present in the environment that starts -Codex; restart Codex after changing it. +the Server is unavailable or rejects authentication. Without an explicit Scope, the plugin resolves the Session +binding, workspace binding, then Server default. Configuration variables must be present in the environment that +starts Codex; restart Codex after changing them. ## Claude Code plugin | Variable | Default | Meaning | | --- | --- | --- | | `POWERCONTEXT_CLAUDE_SERVER_URL` | `http://127.0.0.1:8000` | Server base URL used by the Hook | -| `POWERCONTEXT_CLAUDE_SCOPE_ID` | derived from Git remote or project path | Override project scope | +| `POWERCONTEXT_CLAUDE_SCOPE_ID` | unset | Override durable bindings and the Server default Scope | | `POWERCONTEXT_CLAUDE_AUTHORIZATION` | unset | Complete `Bearer <token>` header for Hook and MCP requests | | `POWERCONTEXT_CLAUDE_CAPTURE_PROMPTS` | `true` | Capture user prompts as ordinary Source evidence | | `POWERCONTEXT_CLAUDE_FLUSH_ON_CAPTURE` | `false` | Wait for Source processing after capture | @@ -333,7 +333,7 @@ after changing its environment. | Variable | Default | Meaning | | --- | --- | --- | | `POWERCONTEXT_DSH_BASE_URL` | `http://127.0.0.1:8000` | Server base URL used by the plugin | -| `POWERCONTEXT_DSH_SCOPE_ID` | derived from Git remote or project path | Override project scope | +| `POWERCONTEXT_DSH_SCOPE_ID` | unset | Explicit existing Scope before workspace binding and Server default | | `POWERCONTEXT_DSH_AUTHORIZATION` | unset | Complete `Bearer <token>` header for plugin HTTP requests | | `POWERCONTEXT_DSH_CAPTURE_PROMPTS` | `true` | Capture user prompts as Source evidence | | `POWERCONTEXT_DSH_FLUSH_ON_CAPTURE` | `false` | Wait for Source processing after capture | @@ -345,7 +345,7 @@ after changing its environment. | Variable | Default | Meaning | | --- | --- | --- | | `POWERCONTEXT_PI_BASE_URL` | `http://127.0.0.1:8000` | Server base URL; non-loopback endpoints must use HTTPS | -| `POWERCONTEXT_PI_SCOPE_ID` | derived from Git remote or project path | Override project scope | +| `POWERCONTEXT_PI_SCOPE_ID` | unset | Explicit existing Scope before workspace binding and Server default | | `POWERCONTEXT_PI_AUTHORIZATION` | unset | Complete `Bearer <token>` header for package HTTP requests | | `POWERCONTEXT_PI_CAPTURE_PROMPTS` | `true` | Capture eligible user prompts as Source evidence | | `POWERCONTEXT_PI_REQUEST_TIMEOUT_MS` | `1000` | Per-request timeout in milliseconds | diff --git a/docs/en/docs/reference/http-api.md b/docs/en/docs/reference/http-api.md index 645461b17..52d2c839c 100644 --- a/docs/en/docs/reference/http-api.md +++ b/docs/en/docs/reference/http-api.md @@ -106,7 +106,7 @@ curl --fail \ | Experience and Skill | `/v1/experience/*`, `/v1/skill/*` | Propose, generate, and read Artifact revisions | | Review | `/v1/artifact-candidates/*` | List, inspect, revise, approve, or reject pending Candidates | | External Skills | `/v1/external-skills/*` | Scan configured targets and resolve or import packages | -| Handoff Reports | `/v1/handoff-reports/*` | Manage Projects, Workstreams, activities, reports, and workspace bindings | +| Handoff Reports | `/v1/handoff-reports/*` | Generate a read-only report for a Scope selection | | Statistics | `/v1/stats` | Read scoped usage statistics | The OpenAPI contract defines the complete path list, schemas, limits, and status codes. The higher-level workflow and diff --git a/docs/en/docs/reference/interfaces.md b/docs/en/docs/reference/interfaces.md index 495c939de..c40e19096 100644 --- a/docs/en/docs/reference/interfaces.md +++ b/docs/en/docs/reference/interfaces.md @@ -68,19 +68,10 @@ and authorization still take precedence over all Work and Handoff records. For the complete Codex transfer and acknowledgement workflow, see [Hand off work in Codex](../how-to/handoff-with-codex.md). -Handoff Report lists scopes that contain a committed Handoff, and `get_handoff_report` requires `scope_id`. -`project_id` remains deprecated wire-compatibility input and is ignored during report generation. Each returned -Workstream projection includes `handoff_revision_count`, `handoff_history_truncated`, and `handoff_history`, with at -most the latest 20 Revision summaries through the frozen selection. For the web workflow, see -[Use Handoff Report](../how-to/use-handoff-report.md). - -The current scope report returns no Activity events, reports `activity_coverage=not_configured`, and has no period -comparison. Period input is normalized but does not filter Activity. The HTTP and Python Client Markdown operations -remain available without a token when Server authentication is disabled; the current browser download and background -refresh controls require a stored bearer token. - -The Codex scope resolver can bind the current Git workspace once to a fixed Workstream scope. That binding takes -precedence over Git remote and path derivation, but remains below explicit scope configuration. +Handoff Report is a read-only projection over a Scope selection. `all` includes every Scope, `exact` includes only the +listed Scope IDs, and `subtree` includes an organization root and all descendants. Each included Scope contributes its +latest exact Handoff address or an explicit `no_handoff` result; Parent does not imply Context visibility. Codex fixes +ordinary Agent report reads to the current Session Scope. Broader selections belong to host and Dashboard views. ## DeepSeek Harness plugin @@ -105,12 +96,12 @@ labelled untrusted historical evidence; and `PowerContextScope` is a dataclass f carries the scope and per-run connection overrides. The recall node and tools read the active scope from the LangGraph runtime and otherwise fall back to `POWERCONTEXT_LANGGRAPH_*` environment settings. -Scope resolution prefers an explicit `scope_id`, then a Git-remote-derived scope, and otherwise raises. This is the -inverse of the Codex resolver because a deployed graph's working directory rarely identifies the project. `TOKEN` is -a bare token that the Client composes into `Authorization: Bearer`, unlike the `POWERCONTEXT_*_AUTHORIZATION` header used by the -Codex, Claude Code, and DeepSeek Harness plugins. Recall and the tools fail open: on Server unavailability the graph -still reaches its end and the tools return a short unavailable string. The adapter covers Memory read and write and -bounded recall only; automatic capture, checkpointing, and Handoff are out of scope. The adapter deliberately does not +Scope resolution sends an explicit `scope_id`, when configured, to the Server for validation and otherwise uses the +Server default Scope. The adapter does not derive Scope IDs from Git or process paths. `TOKEN` is a bare token that the +Client composes into `Authorization: Bearer`, unlike the `POWERCONTEXT_*_AUTHORIZATION` header used by the Codex, +Claude Code, and DeepSeek Harness plugins. Recall and the tools fail open: on Server unavailability the graph still +reaches its end and the tools return a short unavailable string. The adapter covers Memory read and write and bounded +recall only; automatic capture, checkpointing, and Handoff are out of scope. The adapter deliberately does not implement `BaseStore`, whose get, upsert-by-key, and delete operations the Memory model does not provide. It never starts or embeds the Server. diff --git a/docs/en/docs/tutorials/agent-quickstart.md b/docs/en/docs/tutorials/agent-quickstart.md index 37d0009e0..9978e9665 100644 --- a/docs/en/docs/tutorials/agent-quickstart.md +++ b/docs/en/docs/tutorials/agent-quickstart.md @@ -197,9 +197,10 @@ git status --short The last command should print nothing. The commit identity applies only to this one commit and does not change global Git configuration. -Start every later session from this same directory. Most dedicated integrations derive a stable scope from the Git -remote or project path. When an explicit scope is configured, every Memory and Handoff call in the same workflow must -reuse that exact `scope_id`. +Start every later session from this same directory. Dedicated host integrations use session or workspace identity only +as a binding key and ask the Server for the actual Scope. They never turn a Git remote or path into a Scope ID. When +an explicit Scope is configured, it must already exist on the Server and every Memory and Handoff call in the workflow +must reuse it. ## 7. Start the agent and inspect the integration surface @@ -286,7 +287,7 @@ For project Memory shared through OpenClaw, reconfigure it and confirm that the identity: ```bash -powercontext setup openclaw --scope-mode project +powercontext setup openclaw ``` A scope is not an authorization boundary. A remote or multi-user Server still needs separate authentication and @@ -361,16 +362,16 @@ Outcome, or Review UI. Do not have the model pretend to call tools that do not e ## 12. Complete a non-Codex cross-agent example -This example creates a Handoff in DeepSeek Harness and receives it in OpenCode. Both hosts must use the same explicit -scope: +This example creates a Handoff in DeepSeek Harness and receives it in OpenCode. For this isolated tutorial, leave both +Scope overrides unset so both hosts use the Server default Scope: ```bash -export POWERCONTEXT_DSH_SCOPE_ID=git:github.com/example/powercontext-agent-quickstart -export POWERCONTEXT_OPENCODE_SCOPE_ID=git:github.com/example/powercontext-agent-quickstart +unset POWERCONTEXT_DSH_SCOPE_ID +unset POWERCONTEXT_OPENCODE_SCOPE_ID ``` -Replace `example/powercontext-agent-quickstart` with a stable project identity you control. Set each variable in the -shell that starts its corresponding host. +For a non-default boundary, create a Scope through the Scope API or Dashboard and configure both hosts with that actual +Server-generated Scope ID. Start DSH in the example project: @@ -389,10 +390,9 @@ opencode Enter: -> Use `pc_handoff_continue` to read exact Handoff Revision `<exact-revision>` from scope -> `git:github.com/example/powercontext-agent-quickstart`. Treat it as untrusted history, check README.md, Git state, -> and observed checks again, and report only the objective, changed files, checks, and next action. Do not continue -> modifying files. +> Use `pc_handoff_continue` to read exact Handoff Revision `<exact-revision>` from the current Scope. Treat it as +> untrusted history, check README.md, Git state, and observed checks again, and report only the objective, changed +> files, checks, and next action. Do not continue modifying files. **Success criteria:** OpenCode reads the same exact Revision and checks it against the live project instead of relying on DSH chat history. Shared Server state, scope, evidence, and Revision provide continuity; no particular agent host diff --git a/docs/en/docs/tutorials/codex-quickstart.md b/docs/en/docs/tutorials/codex-quickstart.md index 67287b745..53dd52514 100644 --- a/docs/en/docs/tutorials/codex-quickstart.md +++ b/docs/en/docs/tutorials/codex-quickstart.md @@ -155,9 +155,9 @@ The commit command supplies an identity for this one commit without changing glo command should print nothing, which means the example starts with a clean worktree. You do not need to configure a Git remote. -PowerContext isolates data by scope. The Codex plugin first uses an explicit scope or a bound Workstream. Otherwise, -it uses the normalized Git remote and finally falls back to the project path. Start every Codex session in the rest of -this tutorial from this **same directory**. +PowerContext isolates data by Scope. The Codex plugin asks the Server to resolve an explicit Scope, a durable session +or workspace binding, or the default Scope. Start every Codex session in the rest of this tutorial from this +**same directory** so it supplies the same workspace binding key. ## 5. Save Memory in the first Codex session diff --git a/docs/zh/development/server-web-ui.md b/docs/zh/development/server-web-ui.md index fd86e2462..755a5f349 100644 --- a/docs/zh/development/server-web-ui.md +++ b/docs/zh/development/server-web-ui.md @@ -70,20 +70,21 @@ router.add_api_route( ## 理解 Dashboard 数据来源 -浏览器先通过 `/dashboard/scopes` 完成认证并读取可选 scope，再使用所选 `scope_id` 和 `30d` period 请求 -`/v1/stats`。Server 读取同一个 scope 的 snapshot，返回 inventory、model usage 和 recall statistics。 +浏览器先通过 `/dashboard/scopes` 完成认证并读取 Scope，再用公共 Scope selector 构造 selection，将其和 period +一起提交到 `/v1/stats`。Selector 提供三种观察视图：`all`、某个组织根的 `subtree`、单个 `exact` Scope。Parent +只用于组织展示，不会让子 Scope 自动看到父 Scope 数据。 | Dashboard 数据 | 来源 | | --- | --- | -| Sources | 当前 scope 的 Source journal position | -| Memory entries | 当前 Memory Artifact 中的 entry | -| Artifacts | 按 family 分组的当前 Artifact head | -| Pending review | 按 family 和 status 分组的当前 Candidate head | +| Sources | 所选 Scope 的 Source journal position | +| Memory entries | 所选 Scope 的 Memory Artifact entry | +| Artifacts | 所选 Scope 中按 family 分组的 Artifact head | +| Pending review | 所选 Scope 中按 family 和 status 分组的 Candidate head | | Model usage | 持久化的每日 generation 和 embedding usage | | Recall 命中、Token 减少量与节约趋势 | 当前 estimator 对应的持久化每日 recall measurement | -Runtime 在一个 database transaction 中读取这些数据，并在 Server 端计算 total、pending Source、family count、daily -bucket 和 token reduction。浏览器将 `ready_preparations` 展示为 Recall 命中，并将每日有符号的 +Runtime 先将 selection 解析为 exact Scope ID，再在 Server 端汇总 total、pending Source、family count、daily bucket +和 token reduction，并同时返回 selection 与解析后的 ID。浏览器将 `ready_preparations` 展示为 Recall 命中，并将每日有符号的 `token_reduction` 绘制为节约趋势。Heatmap 的每个日期格同时使用这两个字段，固定分档为：无命中、命中但没有正向 减少、减少 1–255、256–1023，以及 1024 个以上预估 Token。固定阈值避免稀疏活动和异常大值改变其他日期的颜色含义。 @@ -98,17 +99,15 @@ document-level 结构放在 `base.html`。一个片段已经被复用，或者 ## 添加 Handoff Report 页面 -启用 Handoff Report 后，Server 会在 `/handoff-reports` 托管 scope 交接页面，不再要求同时启用 scoped statistics Dashboard 或配置其 scope 列表。单独启用 Dashboard 时，根路径 `/` 仍提供原有统计页面。两个页面只复用 `base.html`、header、footer、`auth.js`、主题和 locale storage，不共享统计或报告计算逻辑。 +启用 Handoff Report 后，Server 会在 `/handoff-reports` 托管只读报告页面，Dashboard 仍是可选功能。两个页面都从 +`/dashboard/scopes` 读取 Scope，并通过 `scope-selection.js` 提供一致的 `all`、`subtree` 和 `exact` 视图。 -Handoff Report 页面通过 `POST /v1/handoff-reports/scopes/list-known` 获取当前 token 可访问且存在 committed Handoff 的 exact `scope_id`，并将它作为可搜索范围选择器的值。选择范围后，浏览器通过 `POST /v1/handoff-reports/get` 发送必填 `scope_id` 请求 canonical JSON；Project catalog 和 `project_id` 不参与报告选择。页面继续以完整宽度显示当前精确交接快照。 +页面将所选 `ScopeSelection` 提交到 `/v1/handoff-reports/get`。Server 把它解析为 exact Scope ID，并投影每个 Scope +的 descriptor 和 latest exact Handoff。没有 committed Handoff 的 Scope 仍以 `no_handoff` 展示。报告不会创建 +Parent 不会推断 Context 共享，报告也不会编辑 Handoff 状态。 -当前快照把目标、当前状态、处置状态、下一步和已知缺失作为一份完整交接内容展示。一个“编辑”操作会同时打开五个字段，一个“保存新版本”操作会把完整内容 prepare 并 commit 为新的不可变 Handoff Revision。编辑器打开期间暂停 scope 切换和后台刷新。页面不提供接手方决策操作，已有连续性记录继续通过只读连续性时间线展示。除显式保存交接版本外，浏览器只格式化 `summary`、`coverage`、Workstream 状态和 digest，不重新计算报告口径。 - -已知 scope 请求成功但没有任何 committed Handoff 时，页面会以明确标记的无数据模板预览替代报告控件。点击重试会重新枚举 Handoff heads；一旦某个 scope 完成交接提交，就以真实报告替换预览。预览不会创建 Handoff，也不会请求伪造报告数据。 - -页面默认请求 UTC 当日周期，并提供本日、ISO 本周、自然月和自定义起止日期输入。日期输入的结束日按包含当天解释，发给 API 时转换为下一日零点的排他边界。当前 scope application 只规范化该输入，不提供 Activity event，`activity_coverage=not_configured`，也不返回 period comparison。Handoff 状态来自当前 exact selection，不能把它显示成历史期末状态。 - -概览请求可以关闭 evidence check 以降低延迟；Markdown 下载必须重新请求 `format=markdown`、`download=true` 且默认启用 evidence check。浏览器不得从已经渲染的 DOM 或 canonical JSON 自行拼接 Markdown。当前后台刷新和浏览器下载都要求已保存的 Bearer token，即使 Server 未启用鉴权也是如此；首次和手动报告加载仍可在无 token 时工作。Handoff Report 功能关闭时不注册 `/handoff-reports` 页面和对应 API，原 Dashboard 路径、scope 切换和统计请求保持不变。 +浏览器使用 JSON 投影。下载 Markdown 时，使用相同 selection 重新请求 `format=markdown`、`download=true`；浏览器 +不会从 DOM 重建 Markdown。关闭 Handoff Report 会移除页面和报告 API，不影响 Dashboard selection 和统计行为。 ## 保持安全边界 diff --git a/docs/zh/docs/explanation/core-concepts.md b/docs/zh/docs/explanation/core-concepts.md index 2b63b6c53..de1057bda 100644 --- a/docs/zh/docs/explanation/core-concepts.md +++ b/docs/zh/docs/explanation/core-concepts.md @@ -11,7 +11,8 @@ PowerContext 使用一组领域值组织项目证据和可复用上下文。Sour ## Scope 是隔离边界 每个内容操作都使用 `scope_id`。Scope 选择相互隔离的 Source journal、Memory 生命周期、Candidate inbox、Handoff -history 和相关 runtime state。Integration 可以根据代码库或路径推导 scope，公共接口也允许调用方显式提供。 +history 和相关 runtime state。Scope ID 是 Server 生成的不透明标识。Integration 解析显式 Scope、持久 binding 或 +Server 默认 Scope；代码库、路径、session 和 Agent identity 只是 binding 输入，不是 Scope ID。 Scope ID 只选择数据，不证明用户身份，不授予工具访问权，也不提供执行授权。 @@ -80,8 +81,8 @@ Work Contract 将目标和完成边界保存为 Source 证据。`handoff_current Handoff。只有用户需要保留里程碑时，commit Handoff 才创建长期 Revision。接收方解析 Handoff 并记录 Acknowledgement；Task Outcome 将最终状态和检查结果保存为 Source 证据。 -[Handoff Report](../how-to/use-handoff-report.md) 将当前 Handoff Revision 投影为可检查、可导出的视图。当前 scope -report 尚不包含 Activity event 或 period comparison，也不会改写 Memory 或底层 Handoff history。 +[Handoff Report](../how-to/use-handoff-report.md) 将每个选中 Scope 的最新 Handoff Revision 投影为可检查、可导出的 +视图。它是只读操作，不会改写 Memory 或底层 Handoff history。 ## 各接口暴露同一个 Server 的不同部分 diff --git a/docs/zh/docs/how-to/configure-claude-code.md b/docs/zh/docs/how-to/configure-claude-code.md index 133ecdd10..55148459d 100644 --- a/docs/zh/docs/how-to/configure-claude-code.md +++ b/docs/zh/docs/how-to/configure-claude-code.md @@ -54,7 +54,7 @@ claude 对于每条用户 prompt，Hook 会： -1. 推导与 Codex 集成一致的项目 scope； +1. 按显式、session、workspace 和默认 binding 解析当前 Scope； 2. 最多调用一次 `POST /v1/context/prepare`； 3. 严格校验 `powercontext.prepared-context.v1`，再通过 `additionalContext` 原样注入； 4. 独立地将 prompt 采集为普通 Content Source 证据。 @@ -68,20 +68,19 @@ v1 不安装 `Stop` Hook，不读取 transcript，也不自动采集 Claude 的 scope 按以下顺序解析： 1. 显式设置的 `POWERCONTEXT_CLAUDE_SCOPE_ID`； -2. 与 Codex 共用的 Git-private Workstream 绑定； -3. Git 顶层目录中规范化后的 `remote.origin.url`； -4. 从解析后的项目目录生成的 `local:sha256:<digest>` 标识。 +2. PowerContext 保存的持久 session binding； +3. PowerContext 保存的持久 workspace binding； +4. Server 的默认 Scope。 -因此，在已经绑定 Workstream 的 checkout 中，Claude Code 和 Codex 会话会优先得到完全相同的 scope。 -未绑定时，两者仍会共享规范化后的 remote scope。可以用随附 resolver 显式绑定： +使用随附 resolver 将 checkout 绑定到一个已知 Scope： ```bash -python3 "${CLAUDE_PLUGIN_ROOT}/scripts/project_scope.py" \ - --cwd "$PWD" --bind-workstream "WORKSTREAM_SCOPE_ID" +python3 "${CLAUDE_PLUGIN_ROOT}/scripts/workspace_scope.py" \ + --cwd "$PWD" --bind-scope "SCOPE_ID" ``` -local fallback 在同一个解析后目录中保持稳定，但不用于连接无关的 checkout。只有确实需要主动隔离或共享时， -才设置显式 scope。 +resolver 只把 workspace 路径哈希用作外部 binding key，不会根据 Git remote 或目录生成 Scope ID。只有确实需要 +主动隔离或共享时，才设置显式 Scope。 ## 使用显式 Memory 和 Handoff 操作 @@ -114,8 +113,7 @@ export POWERCONTEXT_CLAUDE_CAPTURE_PROMPTS=false claude ``` -只有 Memory scope 必须有意区别于 Git remote 和本地项目路径时，才设置 -`POWERCONTEXT_CLAUDE_SCOPE_ID`。 +只有当前工作必须有意覆盖持久 binding 和 Server 默认 Scope 时，才设置 `POWERCONTEXT_CLAUDE_SCOPE_ID`。 `POWERCONTEXT_CLAUDE_FLUSH_ON_CAPTURE=true` 会让 Hook 等待 Source 处理，只适合测试，不适合日常交互。 diff --git a/docs/zh/docs/how-to/configure-codex.md b/docs/zh/docs/how-to/configure-codex.md index bae409c11..fd77ee660 100644 --- a/docs/zh/docs/how-to/configure-codex.md +++ b/docs/zh/docs/how-to/configure-codex.md @@ -35,24 +35,19 @@ powercontext setup codex --source oceanbase/powercontext --ref master 交接 ``` -`project-context` Skill 会把这句话视为创建持久交接里程碑的明确授权。如果目录中存在多个 Workstream，Codex 会先 -打开原生工作选择框；只有一个候选时会自动选中。选定后，Codex 把该 Workstream 绑定到当前工作区，在同一轮中检查 -当前对话和仓库，整理目标、分支与工作区状态、改动文件、已执行检查、阻塞项、缺失项和下一步，然后依次调用 -`handoff_current_work` 和 `commit_handoff`。提交成功后，Codex 返回所选 Workstream 和 exact Handoff Revision；用户 -不需要再填写交接内容或重复确认提交。 +`project-context` Skill 会把这句话视为创建持久交接里程碑的明确授权。Codex 在同一轮中检查当前对话和仓库，整理目标、 +分支与工作区状态、改动文件、已执行检查、阻塞项、缺失项和下一步，然后在当前 Session Scope 中依次调用 +`handoff_current_work` 和 `commit_handoff`。提交成功后，Codex 返回 exact Handoff Revision；用户不需要再填写交接 +内容或重复确认提交。 `交接当前工作`、`把当前工作交接出去` 和 `handoff this work` 使用相同行为。若只想检查内容而不写入，请明确说 `预览交接，不要提交`；Skill 此时只在对话中渲染建议内容，不调用写工具。讨论 Handoff 设计或询问 Handoff 如何工作也不会触发持久化。 -Codex scope 按以下顺序解析：显式的 `POWERCONTEXT_CODEX_SCOPE_ID`、当前 Git 工作区持久绑定的 Workstream -scope、规范化后的 Git remote、项目路径。同一工作区后续开启的新 Codex 会话会复用同一个 scope。 - -选择工具返回面向用户的 `work_id` 和权威 `scope_id`。`project-context` Skill 会把这个 exact scope 传给 scope -resolver 的 `--bind-workstream` 操作，并再次校验解析结果。绑定写在 Git 私有目录的 -`powercontext/codex-workspace.json` 中，不进入工作树或提交。随后，新 Handoff 会继续写入所选 Workstream 的同一 -Artifact lifecycle，并得到下一个 Revision。如果 MCP 客户端不支持原生 elicitation，工具会改为返回结构化候选 -列表；集成仍然必须取得用户的明确选择，不得静默选择。 +Session 启动时，Codex 按以下顺序解析 Scope：显式的 `POWERCONTEXT_CODEX_SCOPE_ID`、已有 Session binding、 +host 管理的 workspace binding、Server 默认 Scope。解析出的 Scope 会固定到当前 Session。仓库和目录身份只用于查找 +binding，不生成 Scope ID。Prompt Hook 使用该 binding 完成召回和采集；`PreToolUse` 将同一 binding 注入 data-plane +工具，Agent 输入不能把读写重定向到其他 Scope。Session 切换工作边界时，应由 host 创建或绑定另一个 Scope。 Codex 开始分析提示词前，Hook 只调用一次 `POST /v1/context/prepare`，请求 8000-byte 总预算。它严格校验 `powercontext.prepared-context.v1`，并原样注入返回内容。Runtime 负责把 Memory 内容标记为不可信历史、保留 diff --git a/docs/zh/docs/how-to/configure-dsh.md b/docs/zh/docs/how-to/configure-dsh.md index f01d24e39..3bdc498dc 100644 --- a/docs/zh/docs/how-to/configure-dsh.md +++ b/docs/zh/docs/how-to/configure-dsh.md @@ -30,7 +30,9 @@ powercontext setup dsh --source . - 每轮模型开口前，先请求 Runtime 准备一个最终、有界的上下文值，再把用户输入采集为 Source 证据； - 具名 `pc_*` 工具通过公开 HTTP API 记忆、检索、修订、停用和审计 Memory。 -存在 Git remote 时，Memory scope 根据规范化后的 remote 生成；否则根据会话工作区路径生成。会话没有工作区 cwd、或 scope 必须独立于这两者时，设置 `POWERCONTEXT_DSH_SCOPE_ID`。插件不会把 Harness 进程目录当成项目 scope。 +插件按 `POWERCONTEXT_DSH_SCOPE_ID`、session workspace 持久 binding、Server 默认 Scope 的顺序解析一个由 +Server 管理的 Scope。workspace 路径只会哈希为外部 binding key。缺少 workspace 时使用 Server 默认 Scope， +不会把 Harness 进程目录作为 Scope。 插件在模型分析提示词前只调用一次 `POST /v1/context/prepare`。显式 `remember_memory` 不需要模型。 diff --git a/docs/zh/docs/how-to/configure-hermes.md b/docs/zh/docs/how-to/configure-hermes.md index 2fde0931d..ddb217a1f 100644 --- a/docs/zh/docs/how-to/configure-hermes.md +++ b/docs/zh/docs/how-to/configure-hermes.md @@ -51,14 +51,13 @@ hermes powercontext search "Python package manager" ``` 在交互式 Hermes 会话中，`/pc status` 应连接到同一个 active provider。输入 `/pc ` 后按 Tab/Down，可查看 -Memory、Handoff、Experience、Skill、审核、统计、trace 和 Workstream 命令。Hermes 0.20.4 没有为 gateway +Memory、Handoff、Experience、Skill、审核、统计、trace 和 Scope 命令。Hermes 0.20.4 没有为 gateway slash command 提供足够的调用上下文，因此该插件会拒绝 gateway 调用；gateway 会话应使用 provider 提供的 Hermes tools。 -provider 默认连接 `http://127.0.0.1:8000`。在 Git workspace 中，默认启用的 Workstream persistence 会先读取 -共享的 `.git/powercontext/codex-workspace.json` scope binding；显式 scope 配置的优先级更高。两者都没有时， -provider 根据当前 Hermes profile 和 gateway user identifier 推导 scope；本地 CLI 会话没有 user identifier 时， -会从 `HERMES_HOME` 推导稳定值。 +provider 默认连接 `http://127.0.0.1:8000`。Server 依次解析显式 Scope、持久 session binding、持久 workspace +binding 和默认 Scope。Hermes 只把 workspace 路径哈希用作外部 binding key，不会根据 profile、user、repository +或目录生成 Scope ID。 ## 配置连接 @@ -70,7 +69,7 @@ provider 根据当前 Hermes profile 和 gateway user identifier 推导 scope； | `POWERCONTEXT_HERMES_BASE_URL` | PowerContext Server URL | | `POWERCONTEXT_HERMES_AUTHORIZATION` | 完整 authorization header，例如 `Bearer <token>` | | `POWERCONTEXT_HERMES_TOKEN` | 未设置 `AUTHORIZATION` 时使用的裸 token 简写 | -| `POWERCONTEXT_HERMES_SCOPE_ID` | 显式 scope 或 scope template | +| `POWERCONTEXT_HERMES_SCOPE_ID` | 显式的服务端 Scope ID | | `POWERCONTEXT_HERMES_MAX_BYTES` | Prepared Context 上限，范围为 512 到 32768 字节 | | `POWERCONTEXT_HERMES_TIMEOUT` | HTTP 请求超时秒数 | | `POWERCONTEXT_HERMES_CAPTURE_TURNS` | 是否把完成的 turn 采集为 Source | @@ -78,7 +77,6 @@ provider 根据当前 Hermes profile 和 gateway user identifier 推导 scope； | `POWERCONTEXT_HERMES_CAPTURE_PRE_COMPRESS` | compression 前采集过滤后的新 turn；默认关闭 | | `POWERCONTEXT_HERMES_EVALUATION_TRACE` | 把召回上下文记录到敏感的本地 JSONL trace；默认关闭 | | `POWERCONTEXT_HERMES_EVALUATION_TRACE_PATH` | 覆盖 evaluation trace 目录 | -| `POWERCONTEXT_HERMES_WORKSTREAM` | 读取 Git-private 的共享 Workstream binding；默认启用 | 应由 Hermes 向导把 authorization 保存到受保护的 `.env` secret store，不要把 token 写入 `config.json`。明文 HTTP 只用于 loopback Server；连接远程部署前请阅读[部署 Server](deploy-server.md)。Evaluation trace 包含 prompt 和 diff --git a/docs/zh/docs/how-to/configure-langchain.md b/docs/zh/docs/how-to/configure-langchain.md index 195bd3442..bc986689d 100644 --- a/docs/zh/docs/how-to/configure-langchain.md +++ b/docs/zh/docs/how-to/configure-langchain.md @@ -48,7 +48,7 @@ agent = create_agent( result = await agent.ainvoke( {"messages": [{"role": "user", "content": "这个服务应该如何部署？"}]}, - context=PowerContextScope(scope_id="git:github.com/acme/api"), + context=PowerContextScope(), ) ``` @@ -94,12 +94,13 @@ middleware 自己持有 `PowerContextScope`，并使用独立的 `POWERCONTEXT_L | --- | --- | --- | | `POWERCONTEXT_LANGCHAIN_BASE_URL` | `http://127.0.0.1:8000` | PowerContext Server 地址 | | `POWERCONTEXT_LANGCHAIN_TOKEN` | 未设置 | 传给 Client 的裸 bearer token | -| `POWERCONTEXT_LANGCHAIN_SCOPE_ID` | 推导 | 跨运行共享的持久 scope | +| `POWERCONTEXT_LANGCHAIN_SCOPE_ID` | 未设置 | 用于替代 Server 默认 Scope 的现有 Server Scope | | `POWERCONTEXT_LANGCHAIN_TIMEOUT` | `10` | Client 超时（秒） | | `POWERCONTEXT_LANGCHAIN_MAX_BYTES` | `8000` | PreparedContext 字节上限 | -显式传入的 `PowerContextScope` 优先于环境配置。没有显式 scope 时，PowerContext 尝试从当前 Git remote 推导；两者都不 -存在时，召回和采集会失败开放，不中断 agent。Token 只保留在 Client 配置中，不会进入 agent state 或消息内容。 +显式传入的 `PowerContextScope` 优先于环境配置，并且必须指向 Server 中已有的 Scope。两者都没有设置时，使用 Server +默认 Scope。适配器不会根据 Git、路径、Agent 或 prompt 推导 Scope ID。Token 只保留在 Client 配置中，不会进入 +agent state 或消息内容。 ## 故障行为 diff --git a/docs/zh/docs/how-to/configure-langgraph.md b/docs/zh/docs/how-to/configure-langgraph.md index 508d4b780..83c5d16e0 100644 --- a/docs/zh/docs/how-to/configure-langgraph.md +++ b/docs/zh/docs/how-to/configure-langgraph.md @@ -45,7 +45,7 @@ agent = create_react_agent( context_schema=PowerContextScope, checkpointer=my_checkpointer, ) -await agent.ainvoke(state, context=PowerContextScope(scope_id="git:github.com/acme/api")) +await agent.ainvoke(state, context=PowerContextScope()) ``` 召回 hook 和 Memory 工具都是异步的，因此请用 `ainvoke`/`astream` 驱动图；同步的 `invoke`/`stream` 无法运行它们。 @@ -75,7 +75,7 @@ builder.add_edge(START, "recall") builder.add_edge("recall", "model") graph = builder.compile(checkpointer=my_checkpointer) -await graph.ainvoke(state, context=PowerContextScope(scope_id="git:github.com/acme/api")) +await graph.ainvoke(state, context=PowerContextScope()) ``` 召回 hook 和工具都从 LangGraph runtime 读取当前 `PowerContextScope`，因此 `context` 上的单个值即可配置整轮运行。在 @@ -89,7 +89,7 @@ await graph.ainvoke(state, context=PowerContextScope(scope_id="git:github.com/ac | --- | --- | --- | | `POWERCONTEXT_LANGGRAPH_BASE_URL` | `http://127.0.0.1:8000` | PowerContext Server 地址 | | `POWERCONTEXT_LANGGRAPH_TOKEN` | 未设置 | 转发给 `PowerContextClient` 的裸 token | -| `POWERCONTEXT_LANGGRAPH_SCOPE_ID` | 推导 | 跨运行共享的持久 scope | +| `POWERCONTEXT_LANGGRAPH_SCOPE_ID` | 未设置 | 用于替代 Server 默认 Scope 的现有 Server Scope | | `POWERCONTEXT_LANGGRAPH_TIMEOUT` | `10` | Client 超时（秒） | | `POWERCONTEXT_LANGGRAPH_MAX_BYTES` | `8000` | 准备上下文的大小上限 | @@ -102,15 +102,13 @@ await graph.ainvoke(state, context=PowerContextScope(scope_id="git:github.com/ac ## 解析 scope -单次运行的 scope 按以下顺序解析： +适配器会为每个操作请求 Server 解析 Scope： -1. `PowerContextScope` 上显式的 `scope_id`，或 `POWERCONTEXT_LANGGRAPH_SCOPE_ID`； -2. 由当前 Git remote 推导的 scope； -3. 否则适配器抛出 `MissingScopeError`。 +1. `PowerContextScope` 上显式且已存在的 `scope_id`，或 `POWERCONTEXT_LANGGRAPH_SCOPE_ID`； +2. 否则使用 Server 默认 Scope。 -该优先级与 Codex 插件**相反**——Codex 优先使用由 Git 或路径推导的本地 scope。LangGraph 部署通常是长期运行的服务， -其工作目录与项目无关，因此显式配置是主路径，Git 推导只是回退。两者都不可用时，适配器直接报错，而不是退回到共享的 -本地 scope——那样会把不相关的租户放到一起。 +Scope ID 是由 Server 拥有的不透明标识符。适配器绝不会从进程工作目录、Git remote 或文件系统路径推导 Scope ID。操作 +继续前，Server 会验证显式 ID；请通过 Scope API 获取它，不要在本地自行构造。 ## 把召回内容当作不可信历史 diff --git a/docs/zh/docs/how-to/configure-openclaw.md b/docs/zh/docs/how-to/configure-openclaw.md index d1a9468c9..94bda6126 100644 --- a/docs/zh/docs/how-to/configure-openclaw.md +++ b/docs/zh/docs/how-to/configure-openclaw.md @@ -50,16 +50,24 @@ side-effecting 工具的执行。 `/v1/context/prepare`。search 将查询限制为 8192 个字符，并把请求的结果上限约束在 1–50（默认 10）； 每次 get 最多返回 120 行、12,000 个字符。 -## 选择 memory scope +## 选择 memory Scope -scope 默认是 `agent`，根据 OpenClaw agent 身份推导 memory scope。需要多个 agent 共享同一项目的 memory 时使用 -project scope： +插件会在每次操作前请求 Server 解析一个已有 Scope。Server 按以下顺序检查： + +1. 插件显式配置的 `scopeId`； +2. OpenClaw session、按 host 顺序排列的 active project，以及 agent identity 的持久 binding； +3. Server 默认 Scope。 + +agent、project、path 和 session identity 只作为 binding 查询输入。插件不会用它们推导 Scope ID，也不会创建 Scope。 +若要让所有 OpenClaw 操作显式使用一个已有 Scope： ```bash -powercontext setup openclaw --scope-mode project +openclaw config set plugins.entries.memory-powercontext.config.scopeId scp_0123456789abcdefghjkmnpqrs +openclaw gateway restart ``` -project scope 仅在 OpenClaw 为一次 turn 提供唯一可信项目身份时启用。 +未配置 `scopeId` 时，仅在 OpenClaw host identity 必须保留选择的情况下，才在 Server 端配置持久 binding；否则使用 +Server 默认 Scope。OpenClaw 当前没有 Scope 选择契约，因此插件不会自行持久化 binding。 ## 连接启用鉴权的 Server diff --git a/docs/zh/docs/how-to/configure-opencode.md b/docs/zh/docs/how-to/configure-opencode.md index d2354367e..e94ce3a86 100644 --- a/docs/zh/docs/how-to/configure-opencode.md +++ b/docs/zh/docs/how-to/configure-opencode.md @@ -42,11 +42,14 @@ OpenCode 会要求确认；Candidate 的批准和拒绝仍由用户通过 CLI ```bash export POWERCONTEXT_OPENCODE_BASE_URL=http://127.0.0.1:8000 -export POWERCONTEXT_OPENCODE_SCOPE_ID=project:example export POWERCONTEXT_OPENCODE_CAPTURE_PROMPTS=true opencode ``` +每个 OpenCode session 按显式的 `POWERCONTEXT_OPENCODE_SCOPE_ID`、持久 Session binding、workspace binding、 +Server 默认 Scope 的顺序解析。解析结果会固定到 Session，resume 时继续使用同一边界。显式变量只能指向一个 +已存在且由 Server 管理的 Scope。 + 启用可选 Bearer 鉴权时，将完整请求头写入 `POWERCONTEXT_OPENCODE_AUTHORIZATION`，不要把凭据写入 URL。 非 loopback 地址必须使用 HTTPS。不应采集当前提示词时，设置 `POWERCONTEXT_OPENCODE_CAPTURE_PROMPTS=false`。 diff --git a/docs/zh/docs/how-to/configure-pi.md b/docs/zh/docs/how-to/configure-pi.md index e795a10a9..91e7489f5 100644 --- a/docs/zh/docs/how-to/configure-pi.md +++ b/docs/zh/docs/how-to/configure-pi.md @@ -36,7 +36,9 @@ Pi 开始 agent turn 前，package 会以默认 8000-byte 预算调用一次 `PO 符合条件的用户提示词会被独立采集为 Content Source。package 不会同步完整 Pi transcript。Server 不可用、超时、 重定向或响应不符合契约时，召回、采集和边界 flush 都会正常降级：Pi 的 prompt 不变，普通工作不会被阻塞。 -scope 优先由规范化 Git remote 推导，无法取得时才根据项目路径推导。只有 scope 必须独立于两者时才设置显式值。 +package 按 `POWERCONTEXT_PI_SCOPE_ID`、workspace 持久 binding、Server 默认 Scope 的顺序解析一个由 Server +管理的 Scope。workspace 路径只会哈希为外部 binding key，不会成为 Scope ID。仅在宿主必须固定到某个已有 +Scope 时设置显式变量。 ## 控制提示词采集 diff --git a/docs/zh/docs/how-to/configure-pydantic-ai.md b/docs/zh/docs/how-to/configure-pydantic-ai.md index 001a64771..6daa57685 100644 --- a/docs/zh/docs/how-to/configure-pydantic-ai.md +++ b/docs/zh/docs/how-to/configure-pydantic-ai.md @@ -29,7 +29,7 @@ from powercontext_pydantic_ai import PowerContext agent = Agent( "openai:gpt-5.2", - capabilities=[PowerContext(scope_id="project:example")], + capabilities=[PowerContext()], ) ``` @@ -58,7 +58,7 @@ export POWERCONTEXT_PYDANTIC_AI_SCOPE_ID=project:example | --- | --- | --- | | `POWERCONTEXT_PYDANTIC_AI_BASE_URL` | `http://127.0.0.1:8000` | HTTP(S)，不能含凭证、query 或 fragment | | `POWERCONTEXT_PYDANTIC_AI_TOKEN` | 未设置 | 以 `SecretStr` 保存的裸可打印 Token | -| `POWERCONTEXT_PYDANTIC_AI_SCOPE_ID` | 自动推导 | 非空，并确定性收敛到最多 256 个字符 | +| `POWERCONTEXT_PYDANTIC_AI_SCOPE_ID` | 未设置 | 最多 256 个字符的已有 Server Scope；未设置时选择 Server 默认 Scope | | `POWERCONTEXT_PYDANTIC_AI_TIMEOUT` | `10` | 正秒数 | | `POWERCONTEXT_PYDANTIC_AI_MAX_BYTES` | `8000` | `512`–`32768` Context 字节 | | `POWERCONTEXT_PYDANTIC_AI_CAPTURE_EVENTS` | `false` | 显式同意采集可见事件 | @@ -85,8 +85,10 @@ def tenant_scope(ctx: RunContext[dict[str, str]]) -> str: capability = PowerContext(settings=settings, scope_id=tenant_scope) ``` -回调在每个 Agent run 内只执行一次。Scope 优先级是：构造器字符串或回调、环境变量 `SCOPE_ID`、规范化 Git -origin，最后是 `local:<project-path-sha256>`。显式配置时不会调用 Git。 +回调在每个 Agent run 内只执行一次。Scope 优先级是构造器字符串或回调，其次是环境变量 `SCOPE_ID`。适配器在每个 +run 内只把该显式 ID（未配置时为 `None`）发送给 `resolve_scope_binding` 一次，并在该 run 的 Recall、Capture、 +Flush 和工具调用中复用 Server 返回的 Scope ID。显式 ID 必须对应 Server 中已有的 Scope；未配置时选择 Server +默认 Scope。适配器不会读取 cwd、Git 元数据或路径来创建 Scope ID。 ## 决定是否采集事件 diff --git a/docs/zh/docs/how-to/configure-workbuddy.md b/docs/zh/docs/how-to/configure-workbuddy.md index a02a53304..d4b3dda6e 100644 --- a/docs/zh/docs/how-to/configure-workbuddy.md +++ b/docs/zh/docs/how-to/configure-workbuddy.md @@ -63,8 +63,8 @@ cp "$PLUGIN"/hooks/workbuddy_powercontext_hook.py \ "$PLUGIN"/hooks/workbuddy_settings.py \ "$PLUGIN"/hooks/prepared_context.py \ "$WORKBUDDY_HOOKS_DIR"/ -cp "$PLUGIN/scripts/project_scope.py" \ - "$WORKBUDDY_HOOKS_DIR/powercontext_project_scope.py" +cp "$PLUGIN/scripts/workspace_scope.py" \ + "$WORKBUDDY_HOOKS_DIR/powercontext_scope_binding.py" ``` ### 2. 注册 Hook @@ -122,8 +122,8 @@ EOF ``` 然后把 `~/.workbuddy/skills/project-context/SKILL.md` 中的 `${POWERCONTEXT_PYTHON}` 替换为 shell-safe -的 Python executable 参数，把 `${POWERCONTEXT_PROJECT_SCOPE_SCRIPT}` 替换为 shell-safe 的完整 -`<WORKBUDDY_HOOKS_DIR>/powercontext_project_scope.py` 路径。 +的 Python executable 参数，把 `${POWERCONTEXT_SCOPE_BINDING_SCRIPT}` 替换为 shell-safe 的完整 +`<WORKBUDDY_HOOKS_DIR>/powercontext_scope_binding.py` 路径。 ### 5. 启动 Server、重启 WorkBuddy 并验证 @@ -187,7 +187,7 @@ export POWERCONTEXT_WORKBUDDY_FLUSH_ON_CAPTURE=true | --- | --- | | `POWERCONTEXT_WORKBUDDY_SERVER_URL` | PowerContext Server URL（默认 `http://127.0.0.1:8000`） | | `POWERCONTEXT_WORKBUDDY_AUTHORIZATION` | 完整的 Authorization header，例如 `Bearer <token>` | -| `POWERCONTEXT_WORKBUDDY_SCOPE_ID` | 显式 scope 或 scope 模板覆盖 | +| `POWERCONTEXT_WORKBUDDY_SCOPE_ID` | 显式的服务端 Scope ID | | `POWERCONTEXT_WORKBUDDY_CAPTURE_PROMPTS` | 是否把用户提示词采集为 Source（默认 `true`） | | `POWERCONTEXT_WORKBUDDY_FLUSH_ON_CAPTURE` | 是否等待采集的 Source 被处理（仅测试，默认 `false`） | | `POWERCONTEXT_WORKBUDDY_REQUEST_TIMEOUT_SECONDS` | 单次 HTTP 请求超时（默认 `1.0`） | @@ -199,16 +199,15 @@ Hook 会校验其 PowerContext MCP URL，并通过去掉末尾 `/mcp` 路径段 ## 解析项目 scope -WorkBuddy 按以下顺序解析 scope： +Server 按以下顺序为 WorkBuddy 解析 Scope： 1. 显式的 `POWERCONTEXT_WORKBUDDY_SCOPE_ID`； -2. 当前 Git 工作区持久绑定的 Workstream scope（存储在 Git 私有目录的 - `powercontext/codex-workspace.json` 中，与 Codex 和 Claude Code 插件共享）； -3. 规范化后的 Git remote； -4. 解析后的本地项目目录的哈希。 +2. 持久 session binding； +3. 持久 workspace binding； +4. Server 的默认 Scope。 -同一工作区后续开启的新 WorkBuddy 会话会复用同一个 scope。`project-context` Skill 的 -`--bind-workstream` 操作会为选中的 Handoff 持久化 Workstream 绑定；绑定不会进入工作树或提交。 +同一工作区后续开启的新 WorkBuddy 会话会复用同一个 Scope。`project-context` Skill 的 `--bind-scope` 操作会在 +PowerContext 中持久化 workspace binding。插件只把 workspace 路径哈希用作外部 binding key，不会据此生成 Scope ID。 ## 连接启用鉴权的本地 Server diff --git a/docs/zh/docs/how-to/full-capability-runtime.md b/docs/zh/docs/how-to/full-capability-runtime.md index 72aa5e90b..206e5da2b 100644 --- a/docs/zh/docs/how-to/full-capability-runtime.md +++ b/docs/zh/docs/how-to/full-capability-runtime.md @@ -1,90 +1,50 @@ --- title: 完整功能 Quick Start -description: 5 分钟启动 PowerContext 完整功能。 +description: 配置模型、启动 Server，并验证完整 Memory 闭环。 --- # 完整功能 Quick Start -## 最小运行与完整能力的差别 +`powercontext server run` 不配置模型也可以运行，但依赖模型的提取和向量检索不会启用。引导式配置会启用 generation、 +embedding、定时 Source 处理，并写入 metrics 和 tracing 设置。 -不带任何配置执行 `powercontext server run`，得到的是最小 Server：进程可以启动、可以接收 Source，但依赖模型的 -能力默认关闭。通过 `config init` 引导生成的一份 `.env` 可以把全部能力打开： - -| 能力 | 默认最小运行 | 完整能力运行 | +| 能力 | 最小 Server | 完整功能 Runtime | | --- | --- | --- | -| Source 采集 | 启用 | 启用 | -| Memory 提取 | 关闭；Source 保持 pending | 启用；Scheduler 每 60 秒处理一次 | -| 搜索模式 | 仅 `auto, fts` | `auto, fts, vector, hybrid` | -| Dashboard Scope | 未配置 | 可见 `project:quickstart` | -| MCP 端点 | `/mcp` 启用 | `/mcp` 启用 | - -两种模式默认都使用 SQLite。向量搜索额外使用内置的 `sqlite-vec` 扩展；当 Embedding model 或其 profile 未配置时， -Server 会回退到 SQLite FTS 并报告 `Search modes: auto, fts`。此时召回仍然可用，但语义搜索和混合搜索需要配置 -Embedding model。 - -## 先确定 Scope ID - -Scope ID 是 PowerContext 的数据命名空间，可以把它理解成“项目 ID”。Source、Memory 和 Handoff 都归属于某个 -Scope；只有 Dashboard 和 Coding Agent 使用同一个 Scope ID，网页里才能看到 Agent 写入的数据。 - -同一个 Server 可以保存多个 Scope。Server 启动时配置的是 **Dashboard 可以查看哪些 Scope**，Coding Agent 启动时 -配置的是 **本次会话把数据读写到哪个 Scope**： - -```text -Coding Agent ──读写──> project:quickstart <──展示── Dashboard -``` - -Scope ID 可以使用任意简短、稳定、非空的字符串，不要包含密钥或其他秘密。例如： +| Source capture | 启用 | 启用 | +| Memory extraction | 关闭 | 启用 | +| Search mode | `auto, fts` | `auto, fts, vector, hybrid` | +| Dashboard | 默认 Scope | 默认 Scope 和所有已创建 Scope | +| MCP endpoint | `/mcp` | `/mcp` | -```text -project:quickstart -git:github.com/oceanbase/powercontext -team:payment-service -``` - -下面的 Quick Start 统一使用： - -```text -project:quickstart -``` +Server 首次启动时创建一个使用不透明 ID 的默认 Scope。Dashboard 从 Server 发现 Scope descriptor，不使用预配置列表。 +Integration 可以把 Session 或 workspace 绑定到默认 Scope，也可以绑定到其他已经存在的 Scope。 -## 快速启动 - -### 第一部分：启动 Server - -#### 1. 安装 +## 1. 安装并生成配置 ```bash uv tool install --force "powercontext[cli,server] @ git+https://github.com/oceanbase/powercontext.git@master" +powercontext config init --output .env ``` -#### 2. 生成配置 +按提示输入 provider connection 和 credential。本地 provider 忽略鉴权时，使用该 provider 接受的非秘密占位值。 + +在不打印 credential 的情况下检查并校验配置： ```bash -powercontext config init --output .env +powercontext config show --env-file .env +powercontext config validate --env-file .env ``` -按照提示填写 provider credential。Pydantic AI provider 在构造时要求提供 credential；如果本地服务忽略认证， -请填写该服务允许的非敏感占位值。 - -生成完成后会列出 Codex、Claude Code、DeepSeek Harness、OpenCode 和 Pi 的全部 setup 与启动命令。生成的 `.env` -按组写入了原本需要手工拼装的配置：Server HTTP、Dashboard、Scope、Generation model、Embedding model（含 -profile ID 与维度）、数据库类型与位置、调度间隔，以及各宿主集成 URL。随时可以用 -`powercontext config show --env-file .env` 查看（凭据显示为 `<redacted>`），用 -`powercontext config validate --env-file .env` 校验语法和模型配置。 +生成文件包含 Server、模型、数据库、Scheduler 和 integration transport 设置。Scope identity 由运行中的 Server 管理， +Config Generator 不会凭空生成 Scope ID。 -#### 3. 启动 Server +## 2. 启动并检查 Server ```bash powercontext server run --env-file .env ``` -使用 `--env-file` 时，文件内的赋值覆盖 shell 中的同名值；文件中没有的旧 `POWERCONTEXT_SERVER_*` 变量会被忽略。 -因此 `config validate` 与 `server run` 使用同一份 Server 配置。 - -#### 4. 验证 Server - -在第二个终端执行： +在另一个终端执行： ```bash set -a @@ -95,117 +55,84 @@ powercontext ready powercontext capabilities ``` -确认输出包含： +Readiness 为 `ready`、Memory extraction 已启用，并且 search mode 包含 `vector` 和 `hybrid` 时，完整 Runtime 可用。 +如果只有 `auto, fts`，检查 Embedding model、profile ID、dimension、credential 和 Base URL。 -```text -package: ok - powercontext <version> -server liveness: ok - http://127.0.0.1:8000 status=ok -server readiness: ok - http://127.0.0.1:8000 status=ready -Status: ready -Memory extraction: enabled -Search modes: auto, fts, vector, hybrid -``` - -`doctor` 全部检查为 `ok`、`Status: ready`、`Memory extraction: enabled`、四种搜索模式齐全，并且 -<http://127.0.0.1:8000/> 的 Dashboard 中存在 `Quick Start`，说明完整功能已经启动。 +打开 <http://127.0.0.1:8000/>，确认默认 Scope 可见。获取其不透明 ID，供后续 API 检查使用： -如果 `powercontext capabilities` 只列出 `auto, fts`，Server 处于仅 FTS 的回退模式，vector 和 hybrid 搜索 -不可用，因此不满足上面的完整能力检查。 +```bash +SCOPE_ID="$(curl -fsS http://127.0.0.1:8000/v1/scopes/default \ + | python -c 'import json, sys; print(json.load(sys.stdin)["scope_id"])')" +export SCOPE_ID +``` -### 第二部分：验证 Memory 闭环 +## 3. 验证 Memory 闭环 -提取发生在 Source flush 时，因此在启动 Coding Agent 前，先验证一次完整闭环。使用唯一 Source ID，保证重复执行 -本指南时仍能验证本轮行为。在加载了同一环境变量的终端里执行： +使用唯一 ID 捕获 Source： ```bash SOURCE_ID="quickstart-$(date +%s)-$$" curl -fsS -X POST http://127.0.0.1:8000/v1/sources/content \ -H 'content-type: application/json' \ - -d "{\"scope_id\":\"project:quickstart\",\"source_id\":\"${SOURCE_ID}\",\"content\":\"PowerContext quick start check: prefer small, verifiable steps.\"}" + -d "{\"scope_id\":\"${SCOPE_ID}\",\"source_id\":\"${SOURCE_ID}\",\"content\":\"PowerContext quick start check: prefer small, verifiable steps.\"}" ``` -Server 返回 `202`、`"status":"accepted"` 和数字 `position`；记录 Source ID 与 position。然后 flush 该 Scope， -这一步会执行 Memory 提取： +保留响应中的 `position`，再 flush 同一 Scope： ```bash -curl -X POST http://127.0.0.1:8000/v1/memory/flush \ +curl -fsS -X POST http://127.0.0.1:8000/v1/memory/flush \ -H 'content-type: application/json' \ - -d '{"scope_id":"project:quickstart"}' + -d "{\"scope_id\":\"${SCOPE_ID}\"}" ``` -flush 响应包含 `current_cursor`，它必须大于等于 capture 响应中的 `position`。Scheduler 可能已经抢先处理该 -Source；只要 cursor 已到达该 position，`status:"idle"` 也是合法结果。如果尚未到达，请再次 flush。 +返回的 `current_cursor` 必须不小于 capture `position`。Scheduler 已经处理 Source 时，`status: "idle"` 也是有效结果。 -然后列出当前 Memory entry： +列出 Memory entry： ```bash curl -fsS -X POST http://127.0.0.1:8000/v1/memory/entries/list \ -H 'content-type: application/json' \ - -d '{"scope_id":"project:quickstart"}' + -d "{\"scope_id\":\"${SCOPE_ID}\"}" ``` -找到 `source_refs` 中包含本次 capture `source_id` 的 entry，并记录它的 `citation.entry_id`。这才能证明本次 -Source 生成了 Memory。如果没有 entry 引用该 Source，说明提取已运行但没有产生候选项；请换一个新的 Source ID， -写入更明确、可长期保留的事实或偏好后重试。 - -通过向量搜索确认 Embedding 可用： +找到 `source_refs` 包含已捕获 Source 的 entry，记录其 `citation.entry_id`，再验证向量检索： ```bash -curl -X POST http://127.0.0.1:8000/v1/memory/search \ +curl -fsS -X POST http://127.0.0.1:8000/v1/memory/search \ -H 'content-type: application/json' \ - -d '{"scope_id":"project:quickstart","query":"verifiable steps","mode":"vector","limit":50}' + -d "{\"scope_id\":\"${SCOPE_ID}\",\"query\":\"verifiable steps\",\"mode\":\"vector\",\"limit\":50}" ``` -只有响应同时包含 `"mode":"vector"`，并且某个 hit 的 `citation.entry_id` 等于上一步记录的 source-linked entry， -同时其 `matched_by` 包含 `"vector"`，才能确认本轮 Embedding 可用。命中其他 entry、空 `hits` 或 -`"mode":null` 都不能证明本轮闭环。此时检查 `powercontext capabilities`： -如果 `Search modes` 中没有 `vector`，Server 处于仅 FTS 的回退模式；如果存在 `vector`，则本次闭环尚未产生 -可供向量搜索的 Memory。当已有 Memory 但 vector capability 不可用时，显式 vector 请求会返回 HTTP 422。 - -最后检查模型使用统计： +响应包含 `mode: "vector"`、已记录的 `entry_id`，且 `matched_by` 包含 `vector` 时，该闭环验证通过。检查模型用量： ```bash -powercontext stats --scope-id project:quickstart -``` - -```text -Embedding: 1 requests, ... +powercontext stats --scope-id "$SCOPE_ID" ``` -Embedding 请求计数是累计值。非零计数只能辅助说明模型曾被调用；只有上面的 source-linked vector hit 能证明本轮闭环。 - -### 第三部分：启动 Coding Agent - -Config Generator 已经打印全部受支持 Coding Agent 的 setup 和启动命令。新开一个终端，找到要使用的 Agent，复制它下面 -的两行即可；第一行安装 PowerContext 集成，第二行加载刚生成的 `.env` 并启动 Agent，因此不需要再次填写 Scope ID。 - -Coding Agent 启动后，在项目中发送一条普通 prompt。集成会先从 `project:quickstart` 召回相关 Memory，再把本轮 prompt -保存为 Source；Scheduler 会在大约 60 秒内从新 Source 提取 Memory，因此第二部分的 flush 只需做一次用于验证闭环。 - -## 数据存在哪里 +## 4. 启动 Codex -生成的配置不指定数据库位置，因此 Server 把数据保存在用户数据目录，而不是项目内文件。在未设置 -`POWERCONTEXT_HOME` 时，SQLite 的 `powercontext.db` 与调度状态的 `scheduler.db` 位于： +使用 Config Generator 输出的命令安装插件，加载 `.env` 后启动 Codex。普通 Session 流程不要设置 +`POWERCONTEXT_CODEX_SCOPE_ID`：插件依次解析 Session binding、workspace binding 和 Server 默认 Scope。只有宿主必须 +显式选择一个已存在 Scope 时才设置该变量。 -- macOS：`~/Library/Application Support/powercontext/` -- Linux：`~/.local/share/powercontext/` +Codex 启动后发送普通 prompt。插件从绑定 Scope 召回内容，并把 prompt 捕获为 Source 证据。Scheduler 会在配置的间隔内 +处理新 Source。 -如需迁移，在启动 Server 前设置 `POWERCONTEXT_HOME` 即可。之后再修改数据库 URL 会把 Server 指向另一个（可能是 -空的）数据库；需要旧数据时请保留原来的值。 +## 数据与重启 -## 停止与恢复 +没有覆盖数据库设置时，SQLite 在用户数据目录保存 `powercontext.db` 和 `scheduler.db`： -在 Server 终端按 `Ctrl+C` 停止进程。数据持久保存在 SQLite 中，重启不会丢失。恢复时重新加载同一个 `.env`，再次 -执行 `powercontext server run --env-file .env`；pending 的 Source 会在下一次调度或 flush 时继续处理。 +- Linux：`$XDG_DATA_HOME/powercontext`，或 `~/.local/share/powercontext`； +- macOS：`~/Library/Application Support/powercontext`。 -## 快速排障 +按 `Ctrl+C` 停止 Server。使用同一 `.env` 和数据目录重启后，默认 Scope 及其不透明 ID 保持稳定，因为它们保存在数据库中。 | 现象 | 处理方式 | | --- | --- | -| Dashboard 为空 | 对比 Dashboard 与 Agent 的完整 scope 字符串 | -| `ready` 为 `degraded` | 检查 Generation、Embedding 的模型、密钥和 Base URL | -| 没有 `vector`、`hybrid` | 同时配置 Embedding model、profile ID 和正确维度；未配置时召回保持 FTS（`auto, fts`） | -| Source 一直 pending | 启用 scheduler，或调用 `/v1/memory/flush` | -| 原有数据不见了 | 恢复之前的数据库 URL 或 `POWERCONTEXT_HOME` | +| Dashboard 中缺少 Scope | 确认 Scope 已通过 Scope API 创建，然后刷新页面 | +| Readiness 为 `degraded` | 检查模型标识、credential 和 Base URL | +| 没有 `vector` 或 `hybrid` | 同时配置 Embedding model、profile ID 和 dimension | +| Source 一直 pending | 启用 Scheduler，或调用 `/v1/memory/flush` | +| 已有数据消失 | 恢复原数据库 URL 或 `POWERCONTEXT_HOME` | -更多错误状态见[排查问题](troubleshoot.md)，完整变量见[配置参考](../reference/configuration.md)。 +更多信息见[故障排查](troubleshoot.md)和[配置](../reference/configuration.md)。 diff --git a/docs/zh/docs/how-to/handoff-with-codex.md b/docs/zh/docs/how-to/handoff-with-codex.md index a2bc44cba..d7673d00a 100644 --- a/docs/zh/docs/how-to/handoff-with-codex.md +++ b/docs/zh/docs/how-to/handoff-with-codex.md @@ -17,7 +17,8 @@ Work Contract → Handoff → Acknowledgement → Task Outcome ## 开始之前 先完成[安装和运行](install-and-run.md)，保持 Server 运行，并在当前项目中启动已配置 PowerContext 插件的 Codex -会话。工作记录属于所选 scope。Report catalog 中存在多个 Workstream 时，让 Codex 显示 picker 并选择目标 Workstream。 +会话。Integration 会在读取或写入工作记录前将 Session 绑定到一个 Scope。只有独立工作确实需要单独隔离和继续时， +才为它创建新的 Scope。 不要把密钥、访问令牌或其他敏感信息写入 Work Contract、Handoff、Acknowledgement 或 Outcome。 @@ -37,9 +38,9 @@ Codex 调用 `create_work_contract` 并返回精确 Source receipt。Contract > 使用 PowerContext 交接当前工作。检查当前目标、branch、worktree、changed files、已运行检查、阻塞项、遗漏和下一步， > 提交完成的 Handoff，并给我精确 Revision。 -Codex Skill 会选择 Workstream、检查 live state、调用 `handoff_current_work`，并在同一个 turn 中提交返回的 Prepared -Handoff。成功结果包含 scope 和精确 Handoff Revision。如果 prepare 成功但 commit 失败，boundary Source 已经存在， -但没有创建 durable milestone。 +Codex Skill 会使用当前 Session Scope、检查 live state、调用 `handoff_current_work`，并在同一个 turn 中提交返回的 +Prepared Handoff。成功结果包含 Scope 和精确 Handoff Revision。如果 prepare 成功但 commit 失败，boundary Source +已经存在，但没有创建 durable milestone。 只需要只读预览时，明确要求 preview PowerContext Handoff 且不执行写操作。需要临时转交但不保留 milestone 时，让 Codex 准备 Handoff 但不要 commit。该操作会记录 boundary Source，并返回一份完整 Prepared Handoff 给接收方。 diff --git a/docs/zh/docs/how-to/install-and-run.md b/docs/zh/docs/how-to/install-and-run.md index 8f193ee2d..43f4edf29 100644 --- a/docs/zh/docs/how-to/install-and-run.md +++ b/docs/zh/docs/how-to/install-and-run.md @@ -37,7 +37,7 @@ powercontext setup select --host codex --host dsh --source oceanbase/powercontex ``` 未传入 `--server-url` 时，Claude Code 和 OpenClaw 保留 `http://127.0.0.1:8000` 默认值；显式传入该选项时会覆盖 -两个被选中宿主的地址。OpenClaw 的 `--scope-mode` 默认值为 `agent`。Codex、DSH、OpenCode、Pi 和 Hermes 只有在 +两个被选中宿主的地址。Codex、DSH、OpenCode、Pi 和 Hermes 只有在 通过现有安装后诊断后才会报告为 installed。安装 Hermes 后，还需运行 `hermes memory setup` 并选择 PowerContext， 然后再启动 Hermes。 @@ -54,7 +54,7 @@ powercontext server run - 监听 `127.0.0.1:8000`； - 在 `/mcp` 启用 Streamable HTTP MCP； -- 在 `/` 启用 Dashboard；尚未配置 scope 时，页面会显示明确的空状态； +- 创建默认 Scope，并在 `/` 启用 Dashboard； - 在操作系统的用户数据目录中创建持久化 SQLite 数据库； - 无需推理服务即可支持显式 Memory 操作。 diff --git a/docs/zh/docs/how-to/use-handoff-report.md b/docs/zh/docs/how-to/use-handoff-report.md index 71180a63c..eb63d07ba 100644 --- a/docs/zh/docs/how-to/use-handoff-report.md +++ b/docs/zh/docs/how-to/use-handoff-report.md @@ -1,12 +1,11 @@ --- title: 使用 Handoff Report -description: 打开 Server 报告，选择 scope，检查 Handoff history，并保存 Revision。 +description: 选择 Scope 视图，检查当前 Handoff，并下载 Markdown 报告。 --- # 使用 Handoff Report -Handoff Report 在 Server 托管的网页中展示 committed Handoff Revision。使用该页面可以按 scope 检查当前工作、 -保存完整 Handoff snapshot，或请求 Markdown projection。 +Handoff Report 是各个选中 Scope 最新 committed Handoff 的只读视图。它不会创建或编辑 Scope、Handoff。 ## 开始之前 @@ -17,58 +16,38 @@ powercontext server run ``` Handoff Report 默认启用，地址是 `http://127.0.0.1:8000/handoff-reports`。它使用 Server 的 listener 和鉴权设置， -但不要求启用统计 Dashboard 或配置其 scope list。启用 Bearer 鉴权后，在页面登录表单中输入配置的 token。 +但不要求启用统计 Dashboard。启用 Bearer 鉴权后，在页面登录表单中输入配置的 token。 -默认未鉴权模式下，首次加载和手动加载不需要 token。当前浏览器代码要求存在已保存的 Bearer token 才执行后台刷新和 -Markdown 下载，因此只有启用鉴权并在页面保存 token 后，这两个控件才会发送报告请求。 +Server 启动时会创建默认 Scope。通过 integration 或 Scope API 创建其他 Scope 后，它们也会出现在报告中。Scope +不需要已经包含 committed Handoff。 -页面会发现至少包含一个 committed Handoff 的 scope。没有这类 scope 时，页面显示无数据模板预览，并禁用搜索、周期 -筛选、编辑和下载。 +## 1. 提交 Handoff -## 1. 在目标 scope 中提交 Handoff +在需要查看报告的 Scope 中创建 durable Handoff milestone。在 Codex 中按照 +[在 Codex 中交接工作](handoff-with-codex.md)操作。Codex integration 会写入当前 Session 绑定的 Scope。 -在需要查看报告的 scope 中创建 durable Handoff milestone。在 Codex 中按照 -[在 Codex 中交接工作](handoff-with-codex.md)操作，并保留结果中的精确 scope 和 Handoff Revision。 +报告只读取 committed Handoff Revision，不包含临时 Prepared Handoff。 -Commit 成功后重新加载 Handoff Report。页面调用 `list_handoff_report_known_scopes`，结果中应包含这个 scope。提交 -Handoff 后即可发现 scope，不需要创建 Report Project 或注册 Workstream。 +## 2. 选择 Scope 视图 -## 2. 选择 scope +打开 Handoff Report，选择一项共用的 Scope selection： -按 `scope_id` 搜索并选择 scope。页面使用 `scope_id` 请求报告，显示当前 objective、state、disposition、next action -和 known omissions。 +- **全部**包含该 Server 可见的所有 Scope。 +- **Scope 及其下级**包含一个根 Scope 及其所有后代。 +- **聚焦**只包含一个精确 Scope。 -报告还会按最新优先展示 Handoff history。JSON projection 最多包含最近 20 个 Revision 摘要，并标明更早的 history -是否被截断。HTTP request schema 保留可选的 `project_id` 字段以兼容旧 wire contract，但该字段已 deprecated， -Server 生成 scope report 时会忽略它。 +Parent 只表达组织关系，不会让父 Scope 隐式看到子 Scope 的 Context 或 Handoff。因此，每一行只显示该 Scope +自身最新的 Handoff。选中的 Scope 没有 committed Handoff 时，显示为**无交接**。 -页面会启动 5 秒刷新 timer，但当前只有保存了 Bearer token 才会发送后台请求。未启用鉴权时，使用 **刷新** 手动加载 -变更。存在未保存编辑或正在执行 Handoff action 时，后台刷新也会暂停。 +Handoff 或 Scope 发生变化后，使用**刷新**重新加载。 -## 3. 保存新的 Handoff Revision +## 3. 阅读或下载报告 -选择 **编辑**，将五个 current snapshot 字段作为一份完整文档修改，再选择 **保存新版本**。Server 会 prepare 并 -commit 完整内容，创建新的不可变 Handoff Revision。 +页面显示选中的 Scope、Parent 关系、Handoff 状态、目标、下一步和精确 Revision 地址。摘要计数和明细行使用同一份 +冻结 selection。 -保存属于写操作。编辑器打开时，scope 切换保持暂停。页面不记录接收方是否接受；Acknowledgement 和 Task Outcome -只作为只读记录显示在 **连续性时间线** 中。 - -## 4. 了解当前周期控件 - -当前 scope report 接收并规范化本日、本周、自然月或自定义 period，但尚未配置 Activity integration。响应不包含 -Activity event，`activity_coverage` 为 `not_configured`，也不会生成 previous-period comparison。 - -目前不要使用周期控件推断历史工作或比较 Activity。Handoff snapshot 表示当前精确 selection，不是根据所选周期结束 -时间重建的状态。 - -## 5. 下载 Markdown - -启用 Bearer 鉴权并在页面保存 token 后，选择 **下载 Markdown**，导出相同 scope、locale 和规范化 period。浏览器 -直接向 Server 请求 Markdown，不会根据已渲染页面重新拼接。下载默认启用 evidence check，文件名为 -`handoff-report.md`。 - -默认未鉴权模式下，当前浏览器 guard 不会发送下载请求。Server 未启用鉴权时，底层 HTTP operation 和 Python Client -仍可在不提供 token 的情况下使用。 +选择**下载 Markdown**，由 Server 生成 Markdown projection；浏览器不会根据已渲染页面重新拼接。JSON 和 Markdown +projection 都带有 selection digest 和 report digest，便于使用方识别本次生成的精确结果。 ## 关闭 Handoff Report @@ -82,5 +61,4 @@ powercontext server run 关闭后不会注册 `/handoff-reports` 和 Report API route。Dashboard、HTTP API、MCP、Memory 和 Handoff operation 仍可独立配置。 -Scope discovery 和 Report operation 见[接口](../reference/interfaces.md)，精确 Server 设置见 -[配置](../reference/configuration.md)。 +Scope 和 Report operation 见[接口](../reference/interfaces.md)，精确 Server 设置见[配置](../reference/configuration.md)。 diff --git a/docs/zh/docs/reference/configuration.md b/docs/zh/docs/reference/configuration.md index e7c6d3c4c..18891f1d5 100644 --- a/docs/zh/docs/reference/configuration.md +++ b/docs/zh/docs/reference/configuration.md @@ -54,7 +54,6 @@ Server 配置使用 `POWERCONTEXT_SERVER_` 前缀。 | `POWERCONTEXT_SERVER_AUTH_TOKEN` | 未设置 | 静态 Bearer token；启用鉴权时必须设置 | | `POWERCONTEXT_SERVER_ALLOW_UNAUTHENTICATED_NON_LOOPBACK` | `false` | 在鉴权关闭时显式允许绑定非 loopback 地址 | | `POWERCONTEXT_SERVER_DASHBOARD_ENABLED` | `true` | 在 Server 根路径 `/` 启用 Dashboard | -| `POWERCONTEXT_SERVER_DASHBOARD_SCOPES` | `[]` | Dashboard 可选择的 scope JSON 数组 | | `POWERCONTEXT_SERVER_HANDOFF_REPORT_ENABLED` | `true` | 启用 Handoff Report 及其 API route | | `POWERCONTEXT_SERVER_LOGGING_LEVEL` | `INFO` | operational log 级别 | | `POWERCONTEXT_SERVER_LOGGING_FORMAT` | `console` | `console` 或结构化 `json` 输出 | @@ -97,8 +96,8 @@ Python Client 和 CLI 对出站请求应用相同规则：配置的明文 `http: 安全的 Docker 和远程访问配置见[部署 Server](../how-to/deploy-server.md)。 -Dashboard 默认启用，并与 HTTP API、MCP 共用监听地址和端口。默认未配置 scope，页面会显示空状态；Dashboard -初始化失败只记录包含直接原因的 warning，不影响 Server 的 HTTP API、MCP 和健康检查启动。 +Dashboard 默认启用，并与 HTTP API、MCP 共用监听地址和端口。它从 Server 发现默认 Scope 和所有已创建 Scope； +Dashboard 初始化失败只记录包含直接原因的 warning，不影响 Server 的 HTTP API、MCP 和健康检查启动。 启用 Bearer 鉴权后，`/`、`/skills`、`/reviews`、`/handoff-reports` 的 HTML 外壳及其静态资源仍保持公开，以便 浏览器渲染登录表单；数据请求仍受鉴权保护。在表单中输入 Server token 后，浏览器只把它保存在当前标签页的 session @@ -284,7 +283,7 @@ powercontext capabilities | 变量 | 默认值 | 含义 | | --- | --- | --- | -| `POWERCONTEXT_CODEX_SCOPE_ID` | 根据 Git remote 或项目路径生成 | 覆盖项目 scope | +| `POWERCONTEXT_CODEX_SCOPE_ID` | 未设置 | 显式选择一个已存在 Scope，不再解析 binding 和 Server 默认 Scope | | `POWERCONTEXT_CODEX_AUTHORIZATION` | 未设置 | Hook 与 MCP 请求使用的完整 `Bearer <token>` header | | `POWERCONTEXT_CODEX_CAPTURE_PROMPTS` | `true` | 把用户提示词采集为 Source 证据 | | `POWERCONTEXT_CODEX_FLUSH_ON_CAPTURE` | `false` | 采集后等待 Source 处理 | @@ -292,15 +291,16 @@ powercontext capabilities | `POWERCONTEXT_CODEX_HTTP_BUDGET_SECONDS` | `4` | Hook 共享 HTTP 时间预算 | | `POWERCONTEXT_CODEX_FLUSH_MAX_CALLS` | `4` | 每个提示词最多执行的 flush 次数 | -Codex Hook 外层超时为十秒。Server 不可用或拒绝鉴权时，恢复、采集和 flush 独立降级，不会阻塞 Codex。 -该变量必须存在于启动 Codex 的进程环境中；修改后需要重启 Codex。 +Codex Hook 外层超时为十秒。Server 不可用或拒绝鉴权时，恢复、采集和 flush 独立降级，不会阻塞 Codex。未显式指定 +Scope 时，插件依次解析 Session binding、workspace binding 和 Server 默认 Scope。配置变量必须存在于启动 Codex 的 +进程环境中；修改后需要重启 Codex。 ## Claude Code 插件 | 变量 | 默认值 | 含义 | | --- | --- | --- | | `POWERCONTEXT_CLAUDE_SERVER_URL` | `http://127.0.0.1:8000` | Hook 使用的 Server base URL | -| `POWERCONTEXT_CLAUDE_SCOPE_ID` | 根据 Git remote 或项目路径生成 | 覆盖项目 scope | +| `POWERCONTEXT_CLAUDE_SCOPE_ID` | 未设置 | 覆盖持久 binding 和 Server 默认 Scope | | `POWERCONTEXT_CLAUDE_AUTHORIZATION` | 未设置 | Hook 与 MCP 请求使用的完整 `Bearer <token>` header | | `POWERCONTEXT_CLAUDE_CAPTURE_PROMPTS` | `true` | 把用户 prompt 采集为普通 Source 证据 | | `POWERCONTEXT_CLAUDE_FLUSH_ON_CAPTURE` | `false` | 采集后等待 Source 处理 | @@ -320,7 +320,7 @@ Authorization 只能来自环境变量，不能加入 Server URL 或插件选项 | 变量 | 默认值 | 含义 | | --- | --- | --- | | `POWERCONTEXT_DSH_BASE_URL` | `http://127.0.0.1:8000` | 插件使用的 Server 地址 | -| `POWERCONTEXT_DSH_SCOPE_ID` | 根据 Git remote 或项目路径生成 | 覆盖项目 scope | +| `POWERCONTEXT_DSH_SCOPE_ID` | 未设置 | 在 workspace binding 和 Server 默认值之前显式选择已有 Scope | | `POWERCONTEXT_DSH_AUTHORIZATION` | 未设置 | 插件 HTTP 请求使用的完整 `Bearer <token>` header | | `POWERCONTEXT_DSH_CAPTURE_PROMPTS` | `true` | 把用户提示词采集为 Source 证据 | | `POWERCONTEXT_DSH_FLUSH_ON_CAPTURE` | `false` | 采集后等待 Source 处理 | @@ -332,7 +332,7 @@ Authorization 只能来自环境变量，不能加入 Server URL 或插件选项 | 变量 | 默认值 | 含义 | | --- | --- | --- | | `POWERCONTEXT_PI_BASE_URL` | `http://127.0.0.1:8000` | Server base URL；非 loopback endpoint 必须使用 HTTPS | -| `POWERCONTEXT_PI_SCOPE_ID` | 根据 Git remote 或项目路径生成 | 覆盖项目 scope | +| `POWERCONTEXT_PI_SCOPE_ID` | 未设置 | 在 workspace binding 和 Server 默认值之前显式选择已有 Scope | | `POWERCONTEXT_PI_AUTHORIZATION` | 未设置 | package HTTP 请求使用的完整 `Bearer <token>` header | | `POWERCONTEXT_PI_CAPTURE_PROMPTS` | `true` | 把符合条件的用户提示词采集为 Source 证据 | | `POWERCONTEXT_PI_REQUEST_TIMEOUT_MS` | `1000` | 单请求超时，单位毫秒 | diff --git a/docs/zh/docs/reference/http-api.md b/docs/zh/docs/reference/http-api.md index 3121392dc..913afe7e6 100644 --- a/docs/zh/docs/reference/http-api.md +++ b/docs/zh/docs/reference/http-api.md @@ -99,7 +99,7 @@ curl --fail \ | Experience 与 Skill | `/v1/experience/*`、`/v1/skill/*` | propose、generate 和读取 Artifact Revision | | 审核 | `/v1/artifact-candidates/*` | 列出、检查、修订、批准或拒绝 pending Candidate | | 外部 Skill | `/v1/external-skills/*` | 扫描已配置 target，解析或导入 package | -| Handoff Report | `/v1/handoff-reports/*` | 管理 Project、Workstream、activity、report 和 workspace binding | +| Handoff Report | `/v1/handoff-reports/*` | 按 Scope selection 生成只读报告 | | 统计 | `/v1/stats` | 读取指定 scope 的使用统计 | 完整路径、schema、限制和状态码以 OpenAPI 契约为准。高层工作流和 Python 示例见[接口](interfaces.md)。 diff --git a/docs/zh/docs/reference/interfaces.md b/docs/zh/docs/reference/interfaces.md index 7455389ee..00a383d16 100644 --- a/docs/zh/docs/reference/interfaces.md +++ b/docs/zh/docs/reference/interfaces.md @@ -62,17 +62,10 @@ Claim 和 check 要么是没有 evidence 的 `declared`，要么是拥有同 sco 完整 Codex 转交和接收确认流程见[在 Codex 中交接工作](../how-to/handoff-with-codex.md)。 -Handoff Report 会列出包含 committed Handoff 的 scope，`get_handoff_report` 要求提供 `scope_id`。`project_id` 仅作为 -deprecated wire-compatibility input 保留，生成报告时会被忽略。每个返回的 Workstream projection 包含 -`handoff_revision_count`、`handoff_history_truncated` 和 `handoff_history`，最多返回 frozen selection 之前最近 20 个 -Revision 摘要。Web 操作见[使用 Handoff Report](../how-to/use-handoff-report.md)。 - -当前 scope report 不返回 Activity event，`activity_coverage=not_configured`，并且没有 period comparison。Period -输入只会被规范化，不会筛选 Activity。Server 未启用鉴权时，HTTP 和 Python Client 的 Markdown operation 仍可不带 -token 使用；当前浏览器下载和后台刷新控件要求已保存的 Bearer token。 - -Codex scope resolver 支持把当前 Git 工作区一次绑定到固定 Workstream scope，绑定优先于 Git remote 和路径推导，但低于 -显式 scope 配置。 +Handoff Report 是 Scope selection 上的只读投影。`all` 包含全部 Scope，`exact` 只包含列出的 Scope ID，`subtree` +包含一个组织根及其全部后代。每个选中 Scope 提供 latest exact Handoff address，或者明确的 `no_handoff`；Parent 不会 +隐式授予 Context 可见性。Codex 会把普通 Agent 的报告读取固定为当前 Session Scope；更宽的 selection 由 host 和 +Dashboard 使用。 ## DeepSeek Harness 插件 @@ -94,8 +87,8 @@ Capture 或 Flush。参见 [Pydantic AI 适配器预览](../how-to/configure-pyd `PowerContextScope` 是用于图 `context_schema` 的 dataclass，承载 scope 和单次运行的连接覆盖项。召回节点和工具 从 LangGraph runtime 读取当前 scope，否则回退到 `POWERCONTEXT_LANGGRAPH_*` 环境配置。 -Scope 解析优先取显式 `scope_id`，其次取由 Git remote 推导的 scope，都没有时报错。这与 Codex resolver 相反， -因为已部署的图其工作目录通常无法标识项目。`TOKEN` 是裸 token，由 Client 组装为 `Authorization: Bearer`，不同于 +Scope 解析会把已配置的显式 `scope_id` 交给 Server 校验，否则使用 Server 默认 Scope。适配器不会根据 Git 或进程路径 +推导 Scope ID。`TOKEN` 是裸 token，由 Client 组装为 `Authorization: Bearer`，不同于 Codex、Claude Code 和 DeepSeek Harness 插件使用的 `POWERCONTEXT_*_AUTHORIZATION` header。召回和工具都会失败开放： Server 不可用时图仍能到达终点，工具返回一段简短的不可用字符串。适配器只覆盖 Memory 读写和有界召回；自动采集、 checkpointing 和 Handoff 不在范围内。适配器有意不实现 `BaseStore`——Memory 模型不提供其所需的按 key 读取、upsert diff --git a/docs/zh/docs/tutorials/agent-quickstart.md b/docs/zh/docs/tutorials/agent-quickstart.md index d6bd9cb89..f5ebe77a0 100644 --- a/docs/zh/docs/tutorials/agent-quickstart.md +++ b/docs/zh/docs/tutorials/agent-quickstart.md @@ -190,8 +190,9 @@ git status --short 最后一条命令应没有输出。commit 的身份只用于这一次提交，不会修改全局 Git 配置。 -后续每个会话都应从这个同一目录启动。多数专属集成会从 Git remote 或项目路径推导稳定 scope；如果显式配置了 -scope，则同一条流程中的 Memory 与 Handoff 调用必须始终复用这个 exact `scope_id`。 +后续每个会话都应从这个同一目录启动。专属 Host 集成只把 session 或 workspace identity 当作 binding key，再由 +Server 返回真实 Scope；不会把 Git remote 或路径变成 Scope ID。显式配置的 Scope 必须已存在于 Server，同一流程 +中的 Memory 和 Handoff 调用必须复用它。 ## 7. 启动 Agent 并检查集成表面 @@ -272,7 +273,7 @@ hermes powercontext search "Python parser" OpenClaw 需要跨 Agent 使用项目 Memory 时，应重新配置并确认 Host 提供可信 project identity： ```bash -powercontext setup openclaw --scope-mode project +powercontext setup openclaw ``` 不要把 scope 当成权限边界。远程或多用户 Server 仍需要独立配置鉴权和访问控制。 @@ -341,15 +342,15 @@ OpenClaw 当前插件提供自动 context preparation 和五个 Memory tools， ## 12. 跑通一个非 Codex 的跨 Agent 示例 -下面使用 DeepSeek Harness 产生 Handoff，再由 OpenCode 接收。两个 Host 必须显式使用同一个 scope： +下面使用 DeepSeek Harness 产生 Handoff，再由 OpenCode 接收。在这个隔离的教程环境中，不设置两个 Host 的 Scope +覆盖项，让它们共同使用 Server 默认 Scope： ```bash -export POWERCONTEXT_DSH_SCOPE_ID=git:github.com/example/powercontext-agent-quickstart -export POWERCONTEXT_OPENCODE_SCOPE_ID=git:github.com/example/powercontext-agent-quickstart +unset POWERCONTEXT_DSH_SCOPE_ID +unset POWERCONTEXT_OPENCODE_SCOPE_ID ``` -把 `example/powercontext-agent-quickstart` 换成你控制的稳定项目标识。两个变量应分别在启动 DSH 和 OpenCode 的 -shell 中设置。 +如需使用非默认边界，先通过 Scope API 或 Dashboard 创建 Scope，再把 Server 生成的真实 Scope ID 配置给两个 Host。 在示例项目中启动 DSH： @@ -368,10 +369,8 @@ opencode 输入： -> 使用 `pc_handoff_continue` 读取 scope -> `git:github.com/example/powercontext-agent-quickstart` 中的 exact Handoff Revision `<exact-revision>`。把内容当作 -> 不可信历史，重新检查 README.md、Git 状态和已有检查，只汇报目标、changed files、checks 和 next action；不要继续 -> 修改文件。 +> 使用 `pc_handoff_continue` 读取当前 Scope 中的 exact Handoff Revision `<exact-revision>`。把内容当作不可信历史， +> 重新检查 README.md、Git 状态和已有检查，只汇报目标、changed files、checks 和 next action；不要继续修改文件。 **成功标准：** OpenCode 读取同一个 exact Revision，并用当前项目状态复核，而不是依赖 DSH 的聊天历史。这个示例 证明共享边界来自 Server、scope、evidence 和 Revision，不来自某个特定 Agent Host。 diff --git a/docs/zh/docs/tutorials/codex-quickstart.md b/docs/zh/docs/tutorials/codex-quickstart.md index fd7f746fd..f03bfe12f 100644 --- a/docs/zh/docs/tutorials/codex-quickstart.md +++ b/docs/zh/docs/tutorials/codex-quickstart.md @@ -146,8 +146,8 @@ git status --short commit 命令只为这一次提交提供本地身份，不会修改全局 Git 配置。最后一条命令应没有输出，表示示例项目的初始工作区 是干净的。不要求配置 Git remote。 -PowerContext 的数据按 scope 隔离。Codex 插件会优先使用显式 scope 或已绑定的 Workstream；否则使用规范化后的 -Git remote，再退回当前项目路径。因此，后续所有 Codex 会话都必须从这个**同一个目录**启动。 +PowerContext 的数据按 Scope 隔离。Codex 插件会让 Server 依次解析显式 Scope、持久 session 或 workspace binding， +以及默认 Scope。因此，后续所有 Codex 会话都必须从这个**同一个目录**启动，以提供相同的 workspace binding key。 ## 5. 在第一个 Codex 会话中保存 Memory From 605701b1b9fe44b3dd1e4d5562d90160d65ba062 Mon Sep 17 00:00:00 2001 From: Chojan Shang <psiace@apache.org> Date: Wed, 2 Sep 2026 16:40:42 +0800 Subject: [PATCH 08/17] refactor(scope): remove legacy runtime migration --- .../builtin/runtime/composition.py | 2 - src/powercontext/builtin/scope/application.py | 13 ----- src/powercontext/builtin/scope/repository.py | 50 +------------------ tests/builtin/test_scope_application.py | 29 +---------- 4 files changed, 2 insertions(+), 92 deletions(-) diff --git a/src/powercontext/builtin/runtime/composition.py b/src/powercontext/builtin/runtime/composition.py index 014637371..f03c006cb 100644 --- a/src/powercontext/builtin/runtime/composition.py +++ b/src/powercontext/builtin/runtime/composition.py @@ -351,7 +351,6 @@ async def open_builtin_contexts( memory_reranker=memory_reranker, memory_rerank_candidate_limit=config.runtime.memory_rerank_candidate_limit, ) - await contexts.scopes.register_existing() await contexts.scopes.bootstrap_default() yield contexts return @@ -386,7 +385,6 @@ async def open_builtin_contexts( memory_reranker=memory_reranker, memory_rerank_candidate_limit=config.runtime.memory_rerank_candidate_limit, ) - await contexts.scopes.register_existing() await contexts.scopes.bootstrap_default() yield contexts diff --git a/src/powercontext/builtin/scope/application.py b/src/powercontext/builtin/scope/application.py index bfdd658fc..65b125d55 100644 --- a/src/powercontext/builtin/scope/application.py +++ b/src/powercontext/builtin/scope/application.py @@ -65,9 +65,6 @@ async def bootstrap_default(self) -> ScopeDescriptor: existing = await self.default_scope() if existing is not None: return existing - scopes = await self.list() - if len(scopes) == 1: - return await self.set_default(scopes[0].scope_id) created = await self.create( ScopeDraft( title="Default", @@ -78,16 +75,6 @@ async def bootstrap_default(self) -> ScopeDescriptor: await self.set_default(created.scope_id) return created - async def register_existing(self) -> tuple[ScopeDescriptor, ...]: - """Register Scope identities already present in durable runtime data.""" - - async with self._write_lock, self._database.transaction() as connection: - scope_ids = await self._repository.unregistered_runtime_scope_ids(connection) - registered = [] - for scope_id in scope_ids: - registered.append(await self._repository.register_existing(connection, scope_id)) - return tuple(registered) - async def create(self, draft: ScopeDraft, /) -> ScopeDescriptor: async with self._write_lock: return await self._create(draft) diff --git a/src/powercontext/builtin/scope/repository.py b/src/powercontext/builtin/scope/repository.py index 360b7fcbb..dd7f7ebb0 100644 --- a/src/powercontext/builtin/scope/repository.py +++ b/src/powercontext/builtin/scope/repository.py @@ -19,25 +19,17 @@ from collections import defaultdict from hashlib import sha256 -from sqlalchemy import delete, insert, select, union, update +from sqlalchemy import delete, insert, select, update from sqlalchemy.exc import IntegrityError from sqlalchemy.ext.asyncio import AsyncConnection from powercontext.builtin.persistence.tables import ( - ARTIFACT_CANDIDATE_VERSIONS_TABLE, - ARTIFACTS_TABLE, - EXTERNAL_SKILL_REGISTRATIONS_TABLE, - MODEL_USAGE_DAILY_TABLE, - RECALL_TOKEN_DAILY_TABLE, SCOPE_BINDINGS_TABLE, SCOPE_CONTEXT_REFERENCES_TABLE, SCOPE_CREATION_REQUESTS_TABLE, SCOPE_EXTERNAL_REFERENCES_TABLE, SCOPE_SETTINGS_TABLE, SCOPES_TABLE, - SOURCE_CURSORS_TABLE, - SOURCE_JOURNAL_HEADS_TABLE, - SOURCES_TABLE, ) from powercontext.builtin.scope.models import ( ScopeBinding, @@ -49,49 +41,9 @@ ) _DEFAULT_SETTING = "default" -_RUNTIME_SCOPE_TABLES = ( - SOURCES_TABLE, - SOURCE_JOURNAL_HEADS_TABLE, - ARTIFACTS_TABLE, - ARTIFACT_CANDIDATE_VERSIONS_TABLE, - SOURCE_CURSORS_TABLE, - EXTERNAL_SKILL_REGISTRATIONS_TABLE, - MODEL_USAGE_DAILY_TABLE, - RECALL_TOKEN_DAILY_TABLE, -) class ScopeRepository: - async def unregistered_runtime_scope_ids(self, connection: AsyncConnection, /) -> tuple[str, ...]: - discovered = union(*(select(table.c.scope_id) for table in _RUNTIME_SCOPE_TABLES)).subquery() - values = await connection.execute( - select(discovered.c.scope_id) - .outerjoin(SCOPES_TABLE, SCOPES_TABLE.c.scope_id == discovered.c.scope_id) - .where(SCOPES_TABLE.c.scope_id.is_(None)) - .order_by(discovered.c.scope_id) - ) - return tuple(str(scope_id) for scope_id in values.scalars()) - - async def register_existing( - self, - connection: AsyncConnection, - scope_id: str, - /, - ) -> ScopeDescriptor: - await connection.execute( - insert(SCOPES_TABLE).values( - scope_id=scope_id, - title=scope_id, - summary="Registered from existing runtime data.", - parent_scope_id=None, - version=1, - ) - ) - registered = await self.get(connection, scope_id) - if registered is None: - raise AssertionError - return registered - async def get(self, connection: AsyncConnection, scope_id: str, /) -> ScopeDescriptor | None: scopes = await self.get_many(connection, (scope_id,)) return None if not scopes else scopes[0] diff --git a/tests/builtin/test_scope_application.py b/tests/builtin/test_scope_application.py index 19078cfaa..5e8935703 100644 --- a/tests/builtin/test_scope_application.py +++ b/tests/builtin/test_scope_application.py @@ -21,7 +21,7 @@ from sqlalchemy.exc import IntegrityError from powercontext.builtin.persistence.sqlite import SQLiteConfig, SQLiteProfile -from powercontext.builtin.persistence.tables import BUILTIN_TABLES, SOURCES_TABLE +from powercontext.builtin.persistence.tables import BUILTIN_TABLES from powercontext.builtin.scope import ( ScopeApplication, ScopeBindingKey, @@ -51,33 +51,6 @@ async def scenario() -> None: asyncio.run(scenario()) -def test_existing_runtime_scope_is_registered_and_reused_as_default() -> None: - async def scenario() -> None: - async with SQLiteProfile.open(SQLiteConfig(), tables=BUILTIN_TABLES) as profile: - async with profile.database.transaction() as connection: - await connection.execute( - SOURCES_TABLE.insert().values( - scope_id="legacy-scope", - source_type="text", - source_id="source-1", - payload=b"existing", - journal_position=1, - ) - ) - scopes = ScopeApplication(profile.database) - - registered = await scopes.register_existing() - default = await scopes.bootstrap_default() - - assert tuple(scope.scope_id for scope in registered) == ("legacy-scope",) - assert await scopes.register_existing() == () - assert default.scope_id == "legacy-scope" - assert default.title == "legacy-scope" - assert default.summary == "Registered from existing runtime data." - - asyncio.run(scenario()) - - def test_scope_creation_is_idempotent_but_not_ambiguous() -> None: async def scenario() -> None: async with SQLiteProfile.open(SQLiteConfig(), tables=BUILTIN_TABLES) as profile: From d8a637d70fef429f2cd61a8f83c6522648998dd8 Mon Sep 17 00:00:00 2001 From: Chojan Shang <psiace@apache.org> Date: Wed, 2 Sep 2026 17:00:52 +0800 Subject: [PATCH 09/17] fix(scope): retry bindings without savepoints --- src/powercontext/builtin/scope/application.py | 27 ++++++++++++- src/powercontext/builtin/scope/repository.py | 39 ++++++------------- 2 files changed, 36 insertions(+), 30 deletions(-) diff --git a/src/powercontext/builtin/scope/application.py b/src/powercontext/builtin/scope/application.py index 65b125d55..93eb75b66 100644 --- a/src/powercontext/builtin/scope/application.py +++ b/src/powercontext/builtin/scope/application.py @@ -149,13 +149,36 @@ async def default_scope(self) -> ScopeDescriptor | None: return None if scope_id is None else await self._required(connection, scope_id) async def set_default(self, scope_id: str, /) -> ScopeDescriptor: - async with self._write_lock, self._database.transaction() as connection: + async with self._write_lock: + try: + return await self._set_default(scope_id) + except IntegrityError: + async with self._database.transaction() as connection: + if await self._repository.default_scope_id(connection) is None: + raise + scope = await self._required(connection, scope_id) + await self._repository.set_default(connection, scope_id) + return scope + + async def _set_default(self, scope_id: str) -> ScopeDescriptor: + async with self._database.transaction() as connection: scope = await self._required(connection, scope_id) await self._repository.set_default(connection, scope_id) return scope async def bind(self, key: ScopeBindingKey, scope_id: str, /) -> ScopeBinding: - async with self._write_lock, self._database.transaction() as connection: + async with self._write_lock: + try: + return await self._bind(key, scope_id) + except IntegrityError: + async with self._database.transaction() as connection: + if await self._repository.binding(connection, key) is None: + raise + await self._required(connection, scope_id) + return await self._repository.set_binding(connection, key, scope_id) + + async def _bind(self, key: ScopeBindingKey, scope_id: str) -> ScopeBinding: + async with self._database.transaction() as connection: await self._required(connection, scope_id) return await self._repository.set_binding(connection, key, scope_id) diff --git a/src/powercontext/builtin/scope/repository.py b/src/powercontext/builtin/scope/repository.py index dd7f7ebb0..f1e7f2008 100644 --- a/src/powercontext/builtin/scope/repository.py +++ b/src/powercontext/builtin/scope/repository.py @@ -20,7 +20,6 @@ from hashlib import sha256 from sqlalchemy import delete, insert, select, update -from sqlalchemy.exc import IntegrityError from sqlalchemy.ext.asyncio import AsyncConnection from powercontext.builtin.persistence.tables import ( @@ -196,22 +195,13 @@ async def default_scope_id(self, connection: AsyncConnection, /) -> str | None: return None if value is None else str(value) async def set_default(self, connection: AsyncConnection, scope_id: str, /) -> None: - statement = ( + result = await connection.execute( update(SCOPE_SETTINGS_TABLE) .where(SCOPE_SETTINGS_TABLE.c.name == _DEFAULT_SETTING) .values(scope_id=scope_id) ) - result = await connection.execute(statement) if result.rowcount == 0: - try: - async with connection.begin_nested(): - await connection.execute( - insert(SCOPE_SETTINGS_TABLE).values(name=_DEFAULT_SETTING, scope_id=scope_id) - ) - except IntegrityError: - await connection.execute(statement) - if await self.default_scope_id(connection) != scope_id: - raise + await connection.execute(insert(SCOPE_SETTINGS_TABLE).values(name=_DEFAULT_SETTING, scope_id=scope_id)) async def binding(self, connection: AsyncConnection, key: ScopeBindingKey, /) -> ScopeBinding | None: value = ( @@ -232,7 +222,7 @@ async def set_binding( scope_id: str, /, ) -> ScopeBinding: - statement = ( + result = await connection.execute( update(SCOPE_BINDINGS_TABLE) .where( SCOPE_BINDINGS_TABLE.c.integration == key.integration, @@ -241,22 +231,15 @@ async def set_binding( ) .values(scope_id=scope_id) ) - result = await connection.execute(statement) if result.rowcount == 0: - try: - async with connection.begin_nested(): - await connection.execute( - insert(SCOPE_BINDINGS_TABLE).values( - integration=key.integration, - kind=key.kind, - external_id=key.external_id, - scope_id=scope_id, - ) - ) - except IntegrityError: - await connection.execute(statement) - if await self.binding(connection, key) != ScopeBinding(key=key, scope_id=scope_id): - raise + await connection.execute( + insert(SCOPE_BINDINGS_TABLE).values( + integration=key.integration, + kind=key.kind, + external_id=key.external_id, + scope_id=scope_id, + ) + ) return ScopeBinding(key=key, scope_id=scope_id) async def clear_binding(self, connection: AsyncConnection, key: ScopeBindingKey, /) -> bool: From 325f20d6e0c3c30c053f6f3ce95f2b6cb2a05a1f Mon Sep 17 00:00:00 2001 From: Chojan Shang <psiace@apache.org> Date: Thu, 3 Sep 2026 00:07:26 +0800 Subject: [PATCH 10/17] fix(scope): reject unregistered runtime partitions --- .../builtin/runtime/application.py | 25 ++-- tests/builtin/review/test_generation.py | 59 +++++---- tests/builtin/review/test_service.py | 122 ++++++++++-------- .../runtime/test_experience_incubation.py | 16 ++- tests/builtin/runtime/test_external_skills.py | 27 +++- tests/builtin/runtime/test_scheduler.py | 7 + tests/builtin/runtime/test_scope_cache.py | 23 ++++ tests/builtin/runtime/test_statistics.py | 35 +++-- tests/builtin/runtime/test_work_continuity.py | 52 +++++--- tests/e2e/test_builtin_runtime.py | 40 +++++- tests/e2e/test_handoff_runtime.py | 54 +++++--- tests/e2e/test_memory_search_concurrency.py | 29 ++++- tests/e2e/test_observability.py | 40 +++--- 13 files changed, 368 insertions(+), 161 deletions(-) diff --git a/src/powercontext/builtin/runtime/application.py b/src/powercontext/builtin/runtime/application.py index 4b0a01dc4..e8e172f1d 100644 --- a/src/powercontext/builtin/runtime/application.py +++ b/src/powercontext/builtin/runtime/application.py @@ -139,7 +139,7 @@ RuntimeReadinessChecks, ) from powercontext.builtin.runtime.statistics import RelationalScopedStatistics -from powercontext.builtin.scope import ScopeApplication, ScopeNotFoundError, ScopeSelection +from powercontext.builtin.scope import ScopeApplication, ScopeDescriptor, ScopeSelection from powercontext.builtin.sources import ( ContentCapture, ContentSource, @@ -224,6 +224,7 @@ def __init__(self, code: str) -> None: "external-skill-registry": "External Skill Registry is not configured", "review": "Candidate Review services are not configured", "scheduler": "Built-in Runtime scheduler is already started", + "scope": "Scope services are not configured", "statistics": "Statistics services are not configured", } super().__init__(messages[code]) @@ -360,19 +361,12 @@ def __init__(self, runtime: BuiltinRuntime, scope_id: str) -> None: self.scope_id = validate_scope_id(scope_id) async def prepare(self, request: PrepareContextRequest, /) -> PreparedContext: - async with self._runtime._scope_operation(self.scope_id): - return await self._prepare(request) + async with self._runtime._scope_operation(self.scope_id) as scope: + return await self._prepare(request, scope) - async def _prepare(self, request: PrepareContextRequest, /) -> PreparedContext: + async def _prepare(self, request: PrepareContextRequest, scope: ScopeDescriptor, /) -> PreparedContext: builder = PreparedContextBuilder() - scope_ids = [self.scope_id] - if self._runtime.scopes is not None: - try: - scope = await self._runtime.scopes.get(self.scope_id) - except ScopeNotFoundError: - pass - else: - scope_ids.extend(scope.context_references) + scope_ids = [self.scope_id, *scope.context_references] memory_candidates: list[PreparedMemoryCandidates] = [] experience_candidates: list[PreparedExperienceCandidates] = [] @@ -1496,11 +1490,14 @@ async def _operation(self) -> AsyncIterator[None]: self._lifecycle.notify_all() @asynccontextmanager - async def _scope_operation(self, scope_id: str) -> AsyncIterator[None]: + async def _scope_operation(self, scope_id: str) -> AsyncIterator[ScopeDescriptor]: scope = validate_scope_id(scope_id) async with self._operation(): + if self.scopes is None: + raise _RuntimeStateError("scope") + registered = await self.scopes.get(scope) with self._scope_cache.lease(scope): - yield + yield registered @asynccontextmanager async def _scoped_operation( diff --git a/tests/builtin/review/test_generation.py b/tests/builtin/review/test_generation.py index 45a0a83b4..03a0defc0 100644 --- a/tests/builtin/review/test_generation.py +++ b/tests/builtin/review/test_generation.py @@ -27,6 +27,7 @@ from powercontext.builtin.runtime import ( ApproveArtifactCandidateRequest, BuiltinConfig, + BuiltinRuntime, CaptureSource, GenerateExperienceRequest, GenerateSkillRequest, @@ -34,6 +35,15 @@ SkillGenerationOrigin, open_builtin_runtime, ) +from powercontext.builtin.scope import ScopeDraft + + +async def _create_scope(runtime: BuiltinRuntime, idempotency_key: str = "project") -> str: + assert runtime.scopes is not None + scope = await runtime.scopes.create( + ScopeDraft(title="Project", summary="Review generation tests", idempotency_key=idempotency_key) + ) + return scope.scope_id def _experience() -> ExperienceContent: @@ -77,16 +87,17 @@ async def generate(self, value: ArtifactGenerationInput, /) -> SkillContent | No def test_generation_without_model_fails_before_candidate_persistence() -> None: async def scenario() -> None: async with open_builtin_runtime(BuiltinConfig(database=SQLiteConfig())) as runtime: - captured = await runtime.sources.for_scope("project").capture( + scope_id = await _create_scope(runtime) + captured = await runtime.sources.for_scope(scope_id).capture( CaptureSource(source_id="task-1", content="bounded evidence", metadata={}) ) with pytest.raises(GenerationCapabilityUnavailableError): - await runtime.experience.for_scope("project").generate( + await runtime.experience.for_scope(scope_id).generate( GenerateExperienceRequest(sources=(captured.source_ref,)) ) - inbox = await runtime.review.for_scope("project").list(ListArtifactCandidatesRequest()) + inbox = await runtime.review.for_scope(scope_id).list(ListArtifactCandidatesRequest()) capabilities = await runtime.capabilities() assert inbox.candidates == () assert capabilities.experience_generation is False @@ -102,11 +113,12 @@ async def scenario() -> None: BuiltinConfig(database=SQLiteConfig()), experience_generator=generator, ) as runtime: - captured = await runtime.sources.for_scope("project").capture( + scope_id = await _create_scope(runtime) + captured = await runtime.sources.for_scope(scope_id).capture( CaptureSource(source_id="task-1", content="contract validation passed", metadata={}) ) - result = await runtime.experience.for_scope("project").generate( + result = await runtime.experience.for_scope(scope_id).generate( GenerateExperienceRequest( sources=(captured.source_ref,), reason="Generate from a selected successful task.", @@ -123,13 +135,14 @@ async def scenario() -> None: BuiltinConfig(database=SQLiteConfig()), experience_generator=no_op, ) as runtime: - captured = await runtime.sources.for_scope("project").capture( + scope_id = await _create_scope(runtime) + captured = await runtime.sources.for_scope(scope_id).capture( CaptureSource(source_id="task-2", content="nothing reusable", metadata={}) ) - result = await runtime.experience.for_scope("project").generate( + result = await runtime.experience.for_scope(scope_id).generate( GenerateExperienceRequest(sources=(captured.source_ref,)) ) - inbox = await runtime.review.for_scope("project").list(ListArtifactCandidatesRequest()) + inbox = await runtime.review.for_scope(scope_id).list(ListArtifactCandidatesRequest()) assert result.generated is False assert inbox.candidates == () @@ -144,25 +157,26 @@ async def scenario() -> None: BuiltinConfig(database=SQLiteConfig()), experience_generator=generator, ) as runtime: - first_source = await runtime.sources.for_scope("project").capture( + scope_id = await _create_scope(runtime) + first_source = await runtime.sources.for_scope(scope_id).capture( CaptureSource(source_id="task-1", content="contract validation passed", metadata={}) ) - first_candidate = await runtime.experience.for_scope("project").generate( + first_candidate = await runtime.experience.for_scope(scope_id).generate( GenerateExperienceRequest(sources=(first_source.source_ref,)) ) assert first_candidate.candidate is not None - first_approval = await runtime.review.for_scope("project").approve( + first_approval = await runtime.review.for_scope(scope_id).approve( ApproveArtifactCandidateRequest( candidate_id=first_candidate.candidate.candidate_id, expected_version=1, ) ) assert first_approval.result_artifact is not None - later_source = await runtime.sources.for_scope("project").capture( + later_source = await runtime.sources.for_scope(scope_id).capture( CaptureSource(source_id="task-2", content="generation also had to run first", metadata={}) ) - replacement = await runtime.experience.for_scope("project").generate( + replacement = await runtime.experience.for_scope(scope_id).generate( GenerateExperienceRequest( sources=(later_source.source_ref,), artifacts=(first_approval.result_artifact,), @@ -174,7 +188,7 @@ async def scenario() -> None: assert replacement.candidate.target == first_approval.result_artifact assert generator.inputs[-1].target_evidence_id is not None with pytest.raises(InvalidCandidateError): - await runtime.experience.for_scope("project").generate( + await runtime.experience.for_scope(scope_id).generate( GenerateExperienceRequest( sources=(later_source.source_ref,), target=first_approval.result_artifact, @@ -194,14 +208,15 @@ async def scenario() -> None: experience_generator=experience_generator, skill_generator=skill_generator, ) as runtime: - captured = await runtime.sources.for_scope("project").capture( + scope_id = await _create_scope(runtime) + captured = await runtime.sources.for_scope(scope_id).capture( CaptureSource(source_id="task-1", content="contract validation passed", metadata={}) ) - experience_candidate = await runtime.experience.for_scope("project").generate( + experience_candidate = await runtime.experience.for_scope(scope_id).generate( GenerateExperienceRequest(sources=(captured.source_ref,)) ) assert experience_candidate.candidate is not None - approved = await runtime.review.for_scope("project").approve( + approved = await runtime.review.for_scope(scope_id).approve( ApproveArtifactCandidateRequest( candidate_id=experience_candidate.candidate.candidate_id, expected_version=1, @@ -209,7 +224,7 @@ async def scenario() -> None: ) assert approved.result_artifact is not None - generated = await runtime.skill.for_scope("project").generate( + generated = await runtime.skill.for_scope(scope_id).generate( GenerateSkillRequest( origin=SkillGenerationOrigin.EXPERIENCE, sources=(captured.source_ref,), @@ -223,17 +238,17 @@ async def scenario() -> None: evidence.evidence_id.startswith("artifact:experience/") for evidence in skill_generator.inputs[0].evidence ) - skill_approval = await runtime.review.for_scope("project").approve( + skill_approval = await runtime.review.for_scope(scope_id).approve( ApproveArtifactCandidateRequest( candidate_id=generated.candidate.candidate_id, expected_version=1, ) ) assert skill_approval.result_artifact is not None - usage = await runtime.sources.for_scope("project").capture( + usage = await runtime.sources.for_scope(scope_id).capture( CaptureSource(source_id="task-2", content="Skill validation passed.", metadata={}) ) - replacement = await runtime.skill.for_scope("project").generate( + replacement = await runtime.skill.for_scope(scope_id).generate( GenerateSkillRequest( origin=SkillGenerationOrigin.USAGE, sources=(usage.source_ref,), @@ -245,7 +260,7 @@ async def scenario() -> None: assert replacement.candidate.target == skill_approval.result_artifact with pytest.raises(InvalidCandidateError): - await runtime.skill.for_scope("project").generate( + await runtime.skill.for_scope(scope_id).generate( GenerateSkillRequest( origin=SkillGenerationOrigin.EXPERIENCE, sources=(captured.source_ref,), diff --git a/tests/builtin/review/test_service.py b/tests/builtin/review/test_service.py index a2f440679..5e8c0e0aa 100644 --- a/tests/builtin/review/test_service.py +++ b/tests/builtin/review/test_service.py @@ -37,6 +37,7 @@ from powercontext.builtin.runtime import ( ApproveArtifactCandidateRequest, BuiltinConfig, + BuiltinRuntime, CaptureSource, GetArtifactCandidateRequest, GetExperienceRequest, @@ -51,9 +52,18 @@ open_builtin_runtime, ) from powercontext.builtin.runtime.relational import RelationalContexts +from powercontext.builtin.scope import ScopeDraft from powercontext.builtin.sources import ContentCapture +async def _create_scope(runtime: BuiltinRuntime, idempotency_key: str = "project") -> str: + assert runtime.scopes is not None + scope = await runtime.scopes.create( + ScopeDraft(title="Project", summary="Review service tests", idempotency_key=idempotency_key) + ) + return scope.scope_id + + class _InjectedCandidateStatusError(RuntimeError): pass @@ -109,10 +119,11 @@ def _skill_proposal( def test_memory_write_remains_direct_and_does_not_create_a_candidate() -> None: async def scenario() -> None: async with open_builtin_runtime(BuiltinConfig(database=SQLiteConfig())) as runtime: - remembered = await runtime.memory.for_scope("project").remember( + scope_id = await _create_scope(runtime) + remembered = await runtime.memory.for_scope(scope_id).remember( RememberMemoryRequest(entries=(MemoryEntryInput(kind="decision", text="Keep Memory direct."),)) ) - inbox = await runtime.review.for_scope("project").list(ListArtifactCandidatesRequest()) + inbox = await runtime.review.for_scope(scope_id).list(ListArtifactCandidatesRequest()) assert remembered.memory_ref.family == "memory" assert inbox.candidates == () @@ -163,21 +174,23 @@ async def scenario() -> None: def test_experience_candidate_revise_approve_and_retrieval_gate() -> None: async def scenario() -> None: async with open_builtin_runtime(BuiltinConfig(database=SQLiteConfig())) as runtime: - captured = await runtime.sources.for_scope("project").capture( + scope_id = await _create_scope(runtime) + isolated_scope_id = await _create_scope(runtime, "other-project") + captured = await runtime.sources.for_scope(scope_id).capture( CaptureSource(source_id="task-1", content="api-generate then contract-test passed", metadata={}) ) - candidate = await runtime.experience.for_scope("project").propose( + candidate = await runtime.experience.for_scope(scope_id).propose( ProposeExperienceRequest( proposal=_proposal(), sources=(captured.source_ref,), ) ) - inbox = await runtime.review.for_scope("project").list(ListArtifactCandidatesRequest()) - prepared = await runtime.context.for_scope("project").prepare( + inbox = await runtime.review.for_scope(scope_id).list(ListArtifactCandidatesRequest()) + prepared = await runtime.context.for_scope(scope_id).prepare( PrepareContextRequest(query="Regenerate the Client before contract tests.") ) with pytest.raises(InvalidCandidateError): - await runtime.review.for_scope("project").revise( + await runtime.review.for_scope(scope_id).revise( ReviseArtifactCandidateRequest( candidate_id=candidate.candidate_id, expected_version=1, @@ -185,7 +198,7 @@ async def scenario() -> None: sources=(captured.source_ref,), ) ) - revised = await runtime.review.for_scope("project").revise( + revised = await runtime.review.for_scope(scope_id).revise( ReviseArtifactCandidateRequest( candidate_id=candidate.candidate_id, expected_version=1, @@ -194,24 +207,24 @@ async def scenario() -> None: ) ) with pytest.raises(CandidateConflictError): - await runtime.review.for_scope("project").approve( + await runtime.review.for_scope(scope_id).approve( ApproveArtifactCandidateRequest(candidate_id=candidate.candidate_id, expected_version=1) ) - approved = await runtime.review.for_scope("project").approve( + approved = await runtime.review.for_scope(scope_id).approve( ApproveArtifactCandidateRequest(candidate_id=candidate.candidate_id, expected_version=2) ) assert approved.result_artifact is not None - experience = await runtime.experience.for_scope("project").get( + experience = await runtime.experience.for_scope(scope_id).get( GetExperienceRequest(artifact=approved.result_artifact) ) - approved_context = await runtime.context.for_scope("project").prepare( + approved_context = await runtime.context.for_scope(scope_id).prepare( PrepareContextRequest(query="Regenerate and inspect the Client before contract tests.") ) - isolated_context = await runtime.context.for_scope("other-project").prepare( + isolated_context = await runtime.context.for_scope(isolated_scope_id).prepare( PrepareContextRequest(query="Regenerate and inspect the Client before contract tests.") ) - pending = await runtime.review.for_scope("project").list(ListArtifactCandidatesRequest()) - approved_page = await runtime.review.for_scope("project").list( + pending = await runtime.review.for_scope(scope_id).list(ListArtifactCandidatesRequest()) + approved_page = await runtime.review.for_scope(scope_id).list( ListArtifactCandidatesRequest(status=CandidateStatus.APPROVED) ) @@ -229,7 +242,7 @@ async def scenario() -> None: assert pending.candidates == () assert approved_page.candidates == (approved,) with pytest.raises(CandidateTerminalError): - await runtime.review.for_scope("project").approve( + await runtime.review.for_scope(scope_id).approve( ApproveArtifactCandidateRequest(candidate_id=candidate.candidate_id, expected_version=2) ) @@ -239,24 +252,26 @@ async def scenario() -> None: def test_rejected_candidate_is_terminal_and_scope_evidence_isolated() -> None: async def scenario() -> None: async with open_builtin_runtime(BuiltinConfig(database=SQLiteConfig())) as runtime: - captured = await runtime.sources.for_scope("scope-a").capture( + scope_a = await _create_scope(runtime, "scope-a") + scope_b = await _create_scope(runtime, "scope-b") + captured = await runtime.sources.for_scope(scope_a).capture( CaptureSource(source_id="task-1", content="bounded evidence", metadata={}) ) with pytest.raises(InvalidCandidateError): - await runtime.experience.for_scope("scope-b").propose( + await runtime.experience.for_scope(scope_b).propose( ProposeExperienceRequest(proposal=_proposal(), sources=(captured.source_ref,)) ) - candidate = await runtime.experience.for_scope("scope-a").propose( + candidate = await runtime.experience.for_scope(scope_a).propose( ProposeExperienceRequest(proposal=_proposal(), sources=(captured.source_ref,)) ) - rejected = await runtime.review.for_scope("scope-a").reject( + rejected = await runtime.review.for_scope(scope_a).reject( RejectArtifactCandidateRequest( candidate_id=candidate.candidate_id, expected_version=1, reason="The outcome does not support the lesson.", ) ) - prepared = await runtime.context.for_scope("scope-a").prepare( + prepared = await runtime.context.for_scope(scope_a).prepare( PrepareContextRequest(query="Regenerate the Client before contract tests.") ) @@ -265,7 +280,7 @@ async def scenario() -> None: assert rejected.decision_reason == "The outcome does not support the lesson." assert prepared.status == "empty" with pytest.raises(CandidateTerminalError): - await runtime.review.for_scope("scope-a").revise( + await runtime.review.for_scope(scope_a).revise( ReviseArtifactCandidateRequest( candidate_id=candidate.candidate_id, expected_version=1, @@ -280,13 +295,14 @@ async def scenario() -> None: def test_managed_skill_uses_review_gate_and_exact_replacement_lineage() -> None: async def scenario() -> None: async with open_builtin_runtime(BuiltinConfig(database=SQLiteConfig())) as runtime: - task = await runtime.sources.for_scope("project").capture( + scope_id = await _create_scope(runtime) + task = await runtime.sources.for_scope(scope_id).capture( CaptureSource(source_id="task-1", content="api generation and contract validation passed", metadata={}) ) - experience_candidate = await runtime.experience.for_scope("project").propose( + experience_candidate = await runtime.experience.for_scope(scope_id).propose( ProposeExperienceRequest(proposal=_proposal(), sources=(task.source_ref,)) ) - experience_approval = await runtime.review.for_scope("project").approve( + experience_approval = await runtime.review.for_scope(scope_id).approve( ApproveArtifactCandidateRequest( candidate_id=experience_candidate.candidate_id, expected_version=1, @@ -294,17 +310,17 @@ async def scenario() -> None: ) assert experience_approval.result_artifact is not None - candidate = await runtime.skill.for_scope("project").propose( + candidate = await runtime.skill.for_scope(scope_id).propose( ProposeSkillRequest( proposal=_skill_proposal(), artifacts=(experience_approval.result_artifact,), reason="Incubated from reviewed task evidence.", ) ) - pending_skills = await runtime.review.for_scope("project").list( + pending_skills = await runtime.review.for_scope(scope_id).list( ListArtifactCandidatesRequest(family="skill") ) - pending_context = await runtime.context.for_scope("project").prepare( + pending_context = await runtime.context.for_scope(scope_id).prepare( PrepareContextRequest(query="Regenerate clients and run contract tests") ) @@ -316,20 +332,20 @@ async def scenario() -> None: assert '"kind":"experience"' in pending_context.content assert '"family":"skill"' not in pending_context.content - approved = await runtime.review.for_scope("project").approve( + approved = await runtime.review.for_scope(scope_id).approve( ApproveArtifactCandidateRequest(candidate_id=candidate.candidate_id, expected_version=1) ) assert approved.result_artifact is not None - first = await runtime.skill.for_scope("project").get(GetSkillRequest(artifact=approved.result_artifact)) + first = await runtime.skill.for_scope(scope_id).get(GetSkillRequest(artifact=approved.result_artifact)) - usage = await runtime.sources.for_scope("project").capture( + usage = await runtime.sources.for_scope(scope_id).capture( CaptureSource( source_id="task-2", content="The managed Skill was used and both validation commands passed.", metadata={}, ) ) - replacement = await runtime.skill.for_scope("project").propose( + replacement = await runtime.skill.for_scope(scope_id).propose( ProposeSkillRequest( proposal=_skill_proposal( "Regenerate clients, inspect the diff, run generation checks, and then run contract tests." @@ -340,15 +356,15 @@ async def scenario() -> None: reason="Usage evidence showed that the generation check must be explicit.", ) ) - replacement_approval = await runtime.review.for_scope("project").approve( + replacement_approval = await runtime.review.for_scope(scope_id).approve( ApproveArtifactCandidateRequest(candidate_id=replacement.candidate_id, expected_version=1) ) assert replacement_approval.result_artifact is not None - second = await runtime.skill.for_scope("project").get( + second = await runtime.skill.for_scope(scope_id).get( GetSkillRequest(artifact=replacement_approval.result_artifact) ) - historical = await runtime.skill.for_scope("project").get(GetSkillRequest(artifact=first.as_ref())) - approved_context = await runtime.context.for_scope("project").prepare( + historical = await runtime.skill.for_scope(scope_id).get(GetSkillRequest(artifact=first.as_ref())) + approved_context = await runtime.context.for_scope(scope_id).prepare( PrepareContextRequest(query="Regenerate clients and run contract tests") ) @@ -364,30 +380,31 @@ async def scenario() -> None: def test_managed_skill_approval_validates_family_lineage() -> None: async def scenario() -> None: async with open_builtin_runtime(BuiltinConfig(database=SQLiteConfig())) as runtime: - source = await runtime.sources.for_scope("project").capture( + scope_id = await _create_scope(runtime) + source = await runtime.sources.for_scope(scope_id).capture( CaptureSource(source_id="skill-source", content="reviewed Skill source", metadata={}) ) - initial = await runtime.skill.for_scope("project").propose( + initial = await runtime.skill.for_scope(scope_id).propose( ProposeSkillRequest(proposal=_skill_proposal(), sources=(source.source_ref,)) ) - initial_approval = await runtime.review.for_scope("project").approve( + initial_approval = await runtime.review.for_scope(scope_id).approve( ApproveArtifactCandidateRequest(candidate_id=initial.candidate_id, expected_version=1) ) assert initial_approval.result_artifact is not None - unsupported_create = await runtime.skill.for_scope("project").propose( + unsupported_create = await runtime.skill.for_scope(scope_id).propose( ProposeSkillRequest( proposal=_skill_proposal("Use another managed Skill as the only evidence."), artifacts=(initial_approval.result_artifact,), ) ) with pytest.raises(InvalidCandidateError) as unsupported_error: - await runtime.review.for_scope("project").approve( + await runtime.review.for_scope(scope_id).approve( ApproveArtifactCandidateRequest(candidate_id=unsupported_create.candidate_id, expected_version=1) ) assert unsupported_error.value.field == "artifacts" - unsupported_replacement = await runtime.skill.for_scope("project").propose( + unsupported_replacement = await runtime.skill.for_scope(scope_id).propose( ProposeSkillRequest( proposal=_skill_proposal("Replace without direct usage evidence."), artifacts=(initial_approval.result_artifact,), @@ -395,7 +412,7 @@ async def scenario() -> None: ) ) with pytest.raises(InvalidCandidateError) as replacement_error: - await runtime.review.for_scope("project").approve( + await runtime.review.for_scope(scope_id).approve( ApproveArtifactCandidateRequest( candidate_id=unsupported_replacement.candidate_id, expected_version=1, @@ -409,18 +426,19 @@ async def scenario() -> None: def test_stale_experience_target_keeps_candidate_pending() -> None: async def scenario() -> None: async with open_builtin_runtime(BuiltinConfig(database=SQLiteConfig())) as runtime: - captured = await runtime.sources.for_scope("project").capture( + scope_id = await _create_scope(runtime) + captured = await runtime.sources.for_scope(scope_id).capture( CaptureSource(source_id="task-1", content="first result", metadata={}) ) - initial = await runtime.experience.for_scope("project").propose( + initial = await runtime.experience.for_scope(scope_id).propose( ProposeExperienceRequest(proposal=_proposal(), sources=(captured.source_ref,)) ) - approved = await runtime.review.for_scope("project").approve( + approved = await runtime.review.for_scope(scope_id).approve( ApproveArtifactCandidateRequest(candidate_id=initial.candidate_id, expected_version=1) ) assert approved.result_artifact is not None with pytest.raises(InvalidCandidateError): - await runtime.experience.for_scope("project").propose( + await runtime.experience.for_scope(scope_id).propose( ProposeExperienceRequest( proposal=_proposal("This revision omits predecessor lineage."), sources=(captured.source_ref,), @@ -433,17 +451,17 @@ async def scenario() -> None: artifacts=(approved.result_artifact,), target=approved.result_artifact, ) - winner = await runtime.experience.for_scope("project").propose(replacement_request) - stale = await runtime.experience.for_scope("project").propose(replacement_request) - winner_result = await runtime.review.for_scope("project").approve( + winner = await runtime.experience.for_scope(scope_id).propose(replacement_request) + stale = await runtime.experience.for_scope(scope_id).propose(replacement_request) + winner_result = await runtime.review.for_scope(scope_id).approve( ApproveArtifactCandidateRequest(candidate_id=winner.candidate_id, expected_version=1) ) with pytest.raises(ArtifactTargetConflictError): - await runtime.review.for_scope("project").approve( + await runtime.review.for_scope(scope_id).approve( ApproveArtifactCandidateRequest(candidate_id=stale.candidate_id, expected_version=1) ) - current_stale = await runtime.review.for_scope("project").get( + current_stale = await runtime.review.for_scope(scope_id).get( GetArtifactCandidateRequest(candidate_id=stale.candidate_id) ) diff --git a/tests/builtin/runtime/test_experience_incubation.py b/tests/builtin/runtime/test_experience_incubation.py index e6bbb8309..34d360190 100644 --- a/tests/builtin/runtime/test_experience_incubation.py +++ b/tests/builtin/runtime/test_experience_incubation.py @@ -25,12 +25,14 @@ ApproveArtifactCandidateRequest, BuiltinConfig, BuiltinConfigurationError, + BuiltinRuntime, CaptureSource, GetExperienceRequest, ListArtifactCandidatesRequest, RuntimeConfig, open_builtin_runtime, ) +from powercontext.builtin.scope import ScopeDraft from powercontext.builtin.sources import ContentSource from powercontext.sources import Source, SourceRef @@ -64,6 +66,14 @@ async def incubate(self, sources: tuple[Source, ...], /) -> tuple[ExperienceCand ) +async def _create_scope(runtime: BuiltinRuntime, idempotency_key: str) -> str: + assert runtime.scopes is not None + scope = await runtime.scopes.create( + ScopeDraft(title="Experience Test", summary="Experience incubation test", idempotency_key=idempotency_key) + ) + return scope.scope_id + + def test_incubation_uses_an_independent_cursor_and_keeps_candidates_gated() -> None: async def scenario() -> None: pipeline = _TaskOutcomePipeline() @@ -71,7 +81,7 @@ async def scenario() -> None: BuiltinConfig(database=SQLiteConfig()), experience_pipeline=pipeline, ) as runtime: - scope = "scheduled-experience" + scope = await _create_scope(runtime, "scheduled-experience") await runtime.sources.for_scope(scope).capture( CaptureSource( source_id="prompt", @@ -127,7 +137,7 @@ async def scenario() -> None: BuiltinConfig(database=SQLiteConfig()), experience_pipeline=pipeline, ) as runtime: - scope = "retry-experience" + scope = await _create_scope(runtime, "retry-experience") await runtime.sources.for_scope(scope).capture( CaptureSource( source_id="task-1", @@ -157,7 +167,7 @@ async def scenario() -> None: BuiltinConfig(database=SQLiteConfig()), experience_pipeline=pipeline, ) as runtime: - scope = "bounded-experience" + scope = await _create_scope(runtime, "bounded-experience") for index in range(33): await runtime.sources.for_scope(scope).capture( CaptureSource( diff --git a/tests/builtin/runtime/test_external_skills.py b/tests/builtin/runtime/test_external_skills.py index 75b20592d..e6bb3fa71 100644 --- a/tests/builtin/runtime/test_external_skills.py +++ b/tests/builtin/runtime/test_external_skills.py @@ -29,12 +29,14 @@ from powercontext.builtin.review.generation import GenerationCapabilityUnavailableError from powercontext.builtin.runtime import ( BuiltinConfig, + BuiltinRuntime, ExternalSkillsConfig, ImportExternalSkillRequest, ListExternalSkillsRequest, ResolveExternalSkillRequest, open_builtin_runtime, ) +from powercontext.builtin.scope import ScopeDraft from powercontext.builtin.sources import ExternalSkillImportMode @@ -48,6 +50,16 @@ def _write_skill(root: Path) -> Path: return package +async def _create_scope(runtime: BuiltinRuntime) -> str: + assert runtime.scopes is not None + scope = await runtime.scopes.create( + ScopeDraft( + title="External Skills Test", summary="External skill integration test", idempotency_key="external-skills" + ) + ) + return scope.scope_id + + def test_runtime_exposes_configured_external_skill_registry_without_a_model(tmp_path: Path) -> None: async def exercise() -> None: root = tmp_path / ".agents" / "skills" @@ -72,7 +84,8 @@ async def exercise() -> None: assert capabilities.experience_generation is False assert capabilities.managed_skill_generation is False - scoped = runtime.external_skills.for_scope("project:example") + scope_id = await _create_scope(runtime) + scoped = runtime.external_skills.for_scope(scope_id) registration = (await scoped.scan()).registrations[0] available = await scoped.list(ListExternalSkillsRequest()) assert len(available) == 1 @@ -94,8 +107,9 @@ async def exercise() -> None: config = BuiltinConfig(database=SQLiteConfig(url=f"sqlite+aiosqlite:///{database}")) async with open_builtin_runtime(config) as runtime: assert (await runtime.capabilities()).external_skill_registry is False + scope_id = await _create_scope(runtime) with pytest.raises(ExternalSkillRegistryUnavailableError): - await runtime.external_skills.for_scope("project:example").scan() + await runtime.external_skills.for_scope(scope_id).scan() asyncio.run(exercise()) @@ -127,7 +141,8 @@ async def exercise() -> None: ) generator = _SkillGenerator() async with open_builtin_runtime(config, skill_generator=generator) as runtime: - scoped = runtime.external_skills.for_scope("project:example") + scope_id = await _create_scope(runtime) + scoped = runtime.external_skills.for_scope(scope_id) registration = (await scoped.scan()).registrations[0] result = await scoped.import_managed( @@ -162,7 +177,8 @@ async def exercise() -> None: ), ) async with open_builtin_runtime(config) as runtime: - scoped = runtime.external_skills.for_scope("project:example") + scope_id = await _create_scope(runtime) + scoped = runtime.external_skills.for_scope(scope_id) registration = (await scoped.scan()).registrations[0] with pytest.raises(GenerationCapabilityUnavailableError): @@ -190,7 +206,8 @@ async def exercise() -> None: ) generator = _SkillGenerator() async with open_builtin_runtime(config, skill_generator=generator) as runtime: - scoped = runtime.external_skills.for_scope("project:example") + scope_id = await _create_scope(runtime) + scoped = runtime.external_skills.for_scope(scope_id) registration = (await scoped.scan()).registrations[0] manifest = package / "SKILL.md" manifest.write_text(manifest.read_text(encoding="utf-8") + "\nChanged.\n", encoding="utf-8") diff --git a/tests/builtin/runtime/test_scheduler.py b/tests/builtin/runtime/test_scheduler.py index dd94a4635..809bab1e9 100644 --- a/tests/builtin/runtime/test_scheduler.py +++ b/tests/builtin/runtime/test_scheduler.py @@ -39,6 +39,7 @@ SchedulerStateError, scheduler_database_path, ) +from powercontext.builtin.scope import ScopeDescriptor from powercontext.builtin.sources import SourceCursor from powercontext.server.tracing import ServerTracing @@ -52,6 +53,11 @@ async def get(self, scope_id: str, /) -> PowerContext[Any, Any, Any]: return self.context +class _Scopes: + async def get(self, scope_id: str, /) -> ScopeDescriptor: + return ScopeDescriptor(scope_id=scope_id, title="Scheduled", summary="Scheduled scope", version=1) + + class _ScheduledTriggers: def __init__(self, *, source_count: int = 0) -> None: self.dispatched = asyncio.Event() @@ -157,6 +163,7 @@ def _runtime( provider=_Provider(PowerContext(sources=object(), artifacts=object(), triggers=triggers)), # type: ignore[arg-type] capabilities=RuntimeCapabilities(memory_extraction=True, memory_search_modes=("fts",)), scope_ids=scope_ids, + scope_application=_Scopes(), # ty: ignore[invalid-argument-type] experience_incubator=experience_incubator, tracing=tracing, ) diff --git a/tests/builtin/runtime/test_scope_cache.py b/tests/builtin/runtime/test_scope_cache.py index 9280f8b11..4ffa9f049 100644 --- a/tests/builtin/runtime/test_scope_cache.py +++ b/tests/builtin/runtime/test_scope_cache.py @@ -17,12 +17,15 @@ import asyncio from typing import Any +import pytest + from powercontext.builtin.artifacts.experience import ExperienceContent from powercontext.builtin.runtime import ( BuiltinRuntime, ProposeExperienceRequest, RuntimeCapabilities, ) +from powercontext.builtin.scope import ScopeDescriptor class _UnusedProvider: @@ -30,6 +33,11 @@ async def get(self, scope_id: str, /) -> Any: raise AssertionError(scope_id) +class _Scopes: + async def get(self, scope_id: str, /) -> ScopeDescriptor: + return ScopeDescriptor(scope_id=scope_id, title="Test", summary="Test scope", version=1) + + class _ReviewService: def __init__(self, *, block_first: bool = False) -> None: self._block_first = block_first @@ -64,6 +72,20 @@ def _proposal() -> ProposeExperienceRequest: ) +def test_scoped_operation_fails_closed_without_scope_services() -> None: + async def scenario() -> None: + runtime = BuiltinRuntime( + provider=_UnusedProvider(), + capabilities=RuntimeCapabilities(memory_extraction=False, memory_search_modes=()), + ) + + with pytest.raises(RuntimeError, match="Scope services are not configured"): + await runtime.experience.for_scope("unregistered").propose(_proposal()) + await runtime.close() + + asyncio.run(scenario()) + + def test_scope_cache_does_not_evict_a_lock_with_holders_or_waiters() -> None: async def scenario() -> None: services = {"same": _ReviewService(block_first=True)} @@ -85,6 +107,7 @@ def observe(cached: int, active: int) -> None: provider=_UnusedProvider(), capabilities=RuntimeCapabilities(memory_extraction=False, memory_search_modes=()), review_service=review_service, + scope_application=_Scopes(), # ty: ignore[invalid-argument-type] scope_cache_size=1, scope_evictor=evicted.append, scope_cache_observer=observe, diff --git a/tests/builtin/runtime/test_statistics.py b/tests/builtin/runtime/test_statistics.py index 00a65ecd5..6a6f6f55f 100644 --- a/tests/builtin/runtime/test_statistics.py +++ b/tests/builtin/runtime/test_statistics.py @@ -23,6 +23,7 @@ from powercontext.builtin.runtime import ( ApproveArtifactCandidateRequest, BuiltinConfig, + BuiltinRuntime, CaptureSource, PrepareContextRequest, ProposeExperienceRequest, @@ -43,20 +44,29 @@ async def extract(self, request: MemoryCandidateRequest, /) -> tuple[MemoryEntry ) +async def _create_scope(runtime: BuiltinRuntime, idempotency_key: str) -> str: + assert runtime.scopes is not None + scope = await runtime.scopes.create( + ScopeDraft(title="Statistics Test", summary="Runtime statistics test", idempotency_key=idempotency_key) + ) + return scope.scope_id + + def test_scoped_statistics_reports_current_inventory_and_recall_reduction() -> None: async def scenario() -> None: async with open_builtin_runtime( BuiltinConfig(database=SQLiteConfig()), candidate_pipeline=_ContentCandidatePipeline(), ) as runtime: - captured = await runtime.sources.for_scope("project").capture( + scope_id = await _create_scope(runtime, "statistics-inventory") + captured = await runtime.sources.for_scope(scope_id).capture( CaptureSource(source_id="task-1", content="Remember the contract.", metadata={}) ) - await runtime.memory.for_scope("project").flush() - await runtime.memory.for_scope("project").remember( + await runtime.memory.for_scope(scope_id).flush() + await runtime.memory.for_scope(scope_id).remember( RememberMemoryRequest(entries=(MemoryEntryInput(kind="project_note", text="Keep kinds open."),)) ) - candidate = await runtime.experience.for_scope("project").propose( + candidate = await runtime.experience.for_scope(scope_id).propose( ProposeExperienceRequest( proposal=ExperienceContent( situation="A statistics contract was needed.", @@ -67,14 +77,14 @@ async def scenario() -> None: sources=(captured.source_ref,), ) ) - await runtime.review.for_scope("project").approve( + await runtime.review.for_scope(scope_id).approve( ApproveArtifactCandidateRequest( candidate_id=candidate.candidate_id, expected_version=candidate.version, ) ) - statistics = runtime.statistics.for_scope("project") - prepared = await runtime.context.for_scope("project").prepare(PrepareContextRequest(query="contract")) + statistics = runtime.statistics.for_scope(scope_id) + prepared = await runtime.context.for_scope(scope_id).prepare(PrepareContextRequest(query="contract")) result = await statistics.overview(period=StatisticsPeriod.TODAY) @@ -119,10 +129,11 @@ async def scenario() -> None: def test_recall_estimates_each_source_as_complete_text() -> None: async def scenario() -> None: async with open_builtin_runtime(BuiltinConfig(database=SQLiteConfig())) as runtime: - sources = runtime.sources.for_scope("project") + scope_id = await _create_scope(runtime, "statistics-recall") + sources = runtime.sources.for_scope(scope_id) first = await sources.capture(CaptureSource(source_id="short-a", content="a", metadata={})) second = await sources.capture(CaptureSource(source_id="short-b", content="b", metadata={})) - candidate = await runtime.experience.for_scope("project").propose( + candidate = await runtime.experience.for_scope(scope_id).propose( ProposeExperienceRequest( proposal=ExperienceContent( situation="A short Source recall baseline was needed.", @@ -133,16 +144,16 @@ async def scenario() -> None: sources=(first.source_ref, second.source_ref), ) ) - await runtime.review.for_scope("project").approve( + await runtime.review.for_scope(scope_id).approve( ApproveArtifactCandidateRequest( candidate_id=candidate.candidate_id, expected_version=candidate.version, ) ) - prepared = await runtime.context.for_scope("project").prepare( + prepared = await runtime.context.for_scope(scope_id).prepare( PrepareContextRequest(query="estimate each complete Source separately") ) - result = await runtime.statistics.for_scope("project").overview(period=StatisticsPeriod.TODAY) + result = await runtime.statistics.for_scope(scope_id).overview(period=StatisticsPeriod.TODAY) estimator = character_token_estimator() assert prepared.status == "ready" diff --git a/tests/builtin/runtime/test_work_continuity.py b/tests/builtin/runtime/test_work_continuity.py index 9ed83f415..4f0f9d6f9 100644 --- a/tests/builtin/runtime/test_work_continuity.py +++ b/tests/builtin/runtime/test_work_continuity.py @@ -23,6 +23,7 @@ from powercontext.builtin.persistence.sqlite import SQLiteConfig from powercontext.builtin.runtime import ( BuiltinConfig, + BuiltinRuntime, CaptureSource, HandoffContent, HandoffSourceCitation, @@ -31,6 +32,7 @@ PreparedHandoff, open_builtin_runtime, ) +from powercontext.builtin.scope import ScopeDraft from powercontext.builtin.work import ( AcknowledgeHandoff, CreateWorkContract, @@ -56,6 +58,14 @@ ) +async def _create_scope(runtime: BuiltinRuntime, idempotency_key: str) -> str: + assert runtime.scopes is not None + scope = await runtime.scopes.create( + ScopeDraft(title="Work Test", summary="Work continuity test", idempotency_key=idempotency_key) + ) + return scope.scope_id + + def test_verified_work_claims_require_exact_evidence() -> None: with pytest.raises(ValidationError, match="verified Work claims require exact evidence"): WorkClaim(text="Tests pass.", basis="verified") @@ -89,17 +99,18 @@ async def scenario() -> None: missing = HandoffSourceCitation( source_ref=SourceRef(source_type="content", source_id="missing-output"), ) - prepared = PreparedHandoff( - scope_id="project", - base=None, - content=HandoffContent( - objective="Continue a partially verified change.", - state=(HandoffStatement(text="The change was reported as implemented.", citations=(missing,)),), - disposition="continuable", - ), - ) async with open_builtin_runtime(BuiltinConfig(database=SQLiteConfig())) as runtime: - work = runtime.work.for_scope("project") + scope_id = await _create_scope(runtime, "unavailable-handoff-evidence") + prepared = PreparedHandoff( + scope_id=scope_id, + base=None, + content=HandoffContent( + objective="Continue a partially verified change.", + state=(HandoffStatement(text="The change was reported as implemented.", citations=(missing,)),), + disposition="continuable", + ), + ) + work = runtime.work.for_scope(scope_id) with pytest.raises(InvalidRuntimeRequestError, match="handoff-evidence-unavailable"): await work.acknowledge( @@ -182,8 +193,9 @@ async def scenario() -> None: completion_criteria=("Reject unavailable verified evidence.",), ) async with open_builtin_runtime(BuiltinConfig(database=SQLiteConfig())) as runtime: + scope_id = await _create_scope(runtime, "missing-contract-evidence") with pytest.raises(LookupError): - await runtime.work.for_scope("project").create_contract( + await runtime.work.for_scope(scope_id).create_contract( CreateWorkContract(source_id="contract-1", contract=contract) ) @@ -193,7 +205,8 @@ async def scenario() -> None: def test_continuity_projects_the_result_loop_in_stable_journal_order() -> None: async def scenario() -> None: async with open_builtin_runtime(BuiltinConfig(database=SQLiteConfig())) as runtime: - work = runtime.work.for_scope("project") + scope_id = await _create_scope(runtime, "continuity-result-loop") + work = runtime.work.for_scope(scope_id) await work.create_contract( CreateWorkContract( source_id="contract-1", @@ -215,7 +228,7 @@ async def scenario() -> None: ), ) ) - committed = await runtime.handoff.for_scope("project").commit(prepared.handoff) + committed = await runtime.handoff.for_scope(scope_id).commit(prepared.handoff) before_acceptance = await work.continuity() acknowledgement = await work.acknowledge( AcknowledgeHandoff( @@ -269,7 +282,8 @@ async def scenario() -> None: def test_continuity_does_not_cover_an_acceptance_with_an_unlinked_outcome() -> None: async def scenario() -> None: async with open_builtin_runtime(BuiltinConfig(database=SQLiteConfig())) as runtime: - work = runtime.work.for_scope("project") + scope_id = await _create_scope(runtime, "continuity-unlinked-outcome") + work = runtime.work.for_scope(scope_id) prepared = await work.handoff_current( HandoffCurrentWork( source_id="handoff-1", @@ -280,7 +294,7 @@ async def scenario() -> None: ), ) ) - committed = await runtime.handoff.for_scope("project").commit(prepared.handoff) + committed = await runtime.handoff.for_scope(scope_id).commit(prepared.handoff) await work.acknowledge( AcknowledgeHandoff( source_id="receipt-1", @@ -315,8 +329,9 @@ async def scenario() -> None: def test_task_outcome_rejects_a_non_receipt_result_link() -> None: async def scenario() -> None: async with open_builtin_runtime(BuiltinConfig(database=SQLiteConfig())) as runtime: + scope_id = await _create_scope(runtime, "non-receipt-result-link") with pytest.raises(InvalidRuntimeRequestError, match="task-outcome-handoff-receipt"): - await runtime.work.for_scope("project").record_outcome( + await runtime.work.for_scope(scope_id).record_outcome( RecordTaskOutcome( source_id="outcome-1", outcome=TaskOutcome( @@ -338,13 +353,14 @@ async def scenario() -> None: def test_continuity_excludes_malformed_work_records_without_failing_the_report() -> None: async def scenario() -> None: async with open_builtin_runtime(BuiltinConfig(database=SQLiteConfig())) as runtime: - sources = runtime.sources.for_scope("project") + scope_id = await _create_scope(runtime, "malformed-work-records") + sources = runtime.sources.for_scope(scope_id) await sources.capture(CaptureSource(source_id="ordinary-1", content="ordinary", metadata={"kind": []})) await sources.capture( CaptureSource(source_id="malformed-1", content="{}", metadata={"kind": "task-outcome"}) ) - continuity = await runtime.work.for_scope("project").continuity() + continuity = await runtime.work.for_scope(scope_id).continuity() assert continuity.total_event_count == 0 assert continuity.invalid_record_count == 1 diff --git a/tests/e2e/test_builtin_runtime.py b/tests/e2e/test_builtin_runtime.py index 8de6b301a..ab6a1d353 100644 --- a/tests/e2e/test_builtin_runtime.py +++ b/tests/e2e/test_builtin_runtime.py @@ -17,6 +17,8 @@ import asyncio import json +import pytest + from powercontext.builtin.artifacts.memory import MemoryCandidateRequest, MemoryEntryInput, MemoryRerankDecision from powercontext.builtin.inference import InferenceUsage from powercontext.builtin.persistence.sqlite import SQLiteConfig @@ -26,9 +28,10 @@ PrepareContextRequest, RememberMemoryRequest, SearchMemoryRequest, + open_builtin_contexts, open_builtin_runtime, ) -from powercontext.builtin.scope import ScopeDraft, ScopeMutation +from powercontext.builtin.scope import ScopeDraft, ScopeMutation, ScopeNotFoundError from powercontext.builtin.sources import ContentSource @@ -45,6 +48,41 @@ async def extract(self, request: MemoryCandidateRequest, /) -> tuple[MemoryEntry ) +def test_builtin_runtime_rejects_unregistered_scope_without_persisting_data(tmp_path) -> None: + async def scenario() -> None: + database = SQLiteConfig(url=f"sqlite+aiosqlite:///{tmp_path / 'runtime.db'}") + config = BuiltinConfig(database=database) + orphan_scope_id = "project:orphan" + + async with open_builtin_runtime(config) as runtime: + assert runtime.scopes is not None + registered = await runtime.scopes.create( + ScopeDraft(title="Registered", summary="Registered scope", idempotency_key="registered") + ) + + captured = await runtime.sources.for_scope(registered.scope_id).capture( + CaptureSource(source_id="registered-turn", content="registered content", metadata={}) + ) + prepared = await runtime.context.for_scope(registered.scope_id).prepare( + PrepareContextRequest(query="registered") + ) + + assert captured.sequence == 1 + assert prepared.status == "empty" + with pytest.raises(ScopeNotFoundError): + await runtime.sources.for_scope(orphan_scope_id).capture( + CaptureSource(source_id="orphan-turn", content="orphan content", metadata={}) + ) + with pytest.raises(ScopeNotFoundError): + await runtime.context.for_scope(orphan_scope_id).prepare(PrepareContextRequest(query="orphan")) + + async with open_builtin_contexts(config) as contexts: + orphan = await contexts.get(orphan_scope_id) + assert await orphan.sources.journal.entries() == () + + asyncio.run(scenario()) + + def test_builtin_runtime_uses_sqlite_fts_without_vector_extension(tmp_path, monkeypatch) -> None: missing_extension = tmp_path / "missing-sqlite-vec" monkeypatch.setattr( diff --git a/tests/e2e/test_handoff_runtime.py b/tests/e2e/test_handoff_runtime.py index a05936480..5aee16b84 100644 --- a/tests/e2e/test_handoff_runtime.py +++ b/tests/e2e/test_handoff_runtime.py @@ -37,6 +37,7 @@ RememberMemoryRequest, open_builtin_runtime, ) +from powercontext.builtin.scope import ScopeDraft from powercontext.errors import RevisionConflictError @@ -65,14 +66,18 @@ async def scenario() -> None: BuiltinConfig(database=SQLiteConfig()), handoff_pipeline=_EchoHandoffPipeline(), ) as runtime: - source = await runtime.sources.for_scope("project").capture( + assert runtime.scopes is not None + scope = await runtime.scopes.create( + ScopeDraft(title="Project", summary="Handoff activation", idempotency_key="project") + ) + source = await runtime.sources.for_scope(scope.scope_id).capture( CaptureSource( source_id="turn-1", content="The parser maps malformed input to a stable public error.", metadata={}, ) ) - handoffs = runtime.handoff.for_scope("project") + handoffs = runtime.handoff.for_scope(scope.scope_id) generated = await handoffs.activate( ActivateHandoff( boundary_source=source.source_ref, @@ -108,14 +113,18 @@ async def scenario() -> None: ) ) async with open_builtin_runtime(config, handoff_pipeline=_EchoHandoffPipeline()) as runtime: - source = await runtime.sources.for_scope("project").capture( + assert runtime.scopes is not None + scope = await runtime.scopes.create( + ScopeDraft(title="Project", summary="Restarted Handoff trigger", idempotency_key="project") + ) + source = await runtime.sources.for_scope(scope.scope_id).capture( CaptureSource( source_id="boundary-1", content="The provider observed one participant boundary.", metadata={}, ) ) - first = await runtime.handoff.for_scope("project").activate( + first = await runtime.handoff.for_scope(scope.scope_id).activate( ActivateHandoff( boundary_source=source.source_ref, objective="Transfer the current work.", @@ -123,7 +132,7 @@ async def scenario() -> None: ) async with open_builtin_runtime(config, handoff_pipeline=_EchoHandoffPipeline()) as runtime: - repeated = await runtime.handoff.for_scope("project").activate( + repeated = await runtime.handoff.for_scope(scope.scope_id).activate( ActivateHandoff( boundary_source=source.source_ref, objective="Transfer the current work.", @@ -140,14 +149,18 @@ async def scenario() -> None: def test_handoff_runtime_supports_temporary_transfer_and_durable_milestones() -> None: async def scenario() -> None: async with open_builtin_runtime(BuiltinConfig(database=SQLiteConfig())) as runtime: - source = await runtime.sources.for_scope("project").capture( + assert runtime.scopes is not None + scope = await runtime.scopes.create( + ScopeDraft(title="Project", summary="Handoff milestones", idempotency_key="project") + ) + source = await runtime.sources.for_scope(scope.scope_id).capture( CaptureSource( source_id="turn-1", content="The parser maps malformed input to a stable public error.", metadata={"origin": "e2e"}, ) ) - memory = await runtime.memory.for_scope("project").remember( + memory = await runtime.memory.for_scope(scope.scope_id).remember( RememberMemoryRequest( entries=( MemoryEntryInput( @@ -160,7 +173,7 @@ async def scenario() -> None: assert memory.entry is not None source_citation = HandoffSourceCitation(source_ref=source.source_ref) memory_citation = HandoffMemoryCitation(memory_citation=memory.entry.citation) - handoffs = runtime.handoff.for_scope("project") + handoffs = runtime.handoff.for_scope(scope.scope_id) empty = await handoffs.continue_latest() prepared = await handoffs.finalize( @@ -246,7 +259,14 @@ async def scenario() -> None: def test_handoff_runtime_rejects_stale_and_cross_scope_use() -> None: async def scenario() -> None: async with open_builtin_runtime(BuiltinConfig(database=SQLiteConfig())) as runtime: - source = await runtime.sources.for_scope("project").capture( + assert runtime.scopes is not None + scope = await runtime.scopes.create( + ScopeDraft(title="Project", summary="Handoff concurrency", idempotency_key="project") + ) + other = await runtime.scopes.create( + ScopeDraft(title="Other", summary="Cross-Scope Handoff", idempotency_key="other") + ) + source = await runtime.sources.for_scope(scope.scope_id).capture( CaptureSource( source_id="turn-1", content="A stable source for concurrent Handoffs.", @@ -254,7 +274,7 @@ async def scenario() -> None: ) ) citation = HandoffSourceCitation(source_ref=source.source_ref) - handoffs = runtime.handoff.for_scope("project") + handoffs = runtime.handoff.for_scope(scope.scope_id) initial = await handoffs.finalize( HandoffDraft( objective="Coordinate the next milestone.", @@ -282,7 +302,7 @@ async def scenario() -> None: with pytest.raises(RevisionConflictError) as stale: await handoffs.commit(session_b) with pytest.raises(HandoffScopeMismatchError): - await runtime.handoff.for_scope("other").continue_from(session_a) + await runtime.handoff.for_scope(other.scope_id).continue_from(session_a) assert stale.value.artifact == session_b.base assert stale.value.current == current @@ -299,14 +319,18 @@ async def scenario() -> None: ) ) async with open_builtin_runtime(config) as runtime: - source = await runtime.sources.for_scope("project").capture( + assert runtime.scopes is not None + scope = await runtime.scopes.create( + ScopeDraft(title="Project", summary="Durable Handoff", idempotency_key="project") + ) + source = await runtime.sources.for_scope(scope.scope_id).capture( CaptureSource( source_id="turn-1", content="Persist only an explicitly selected milestone.", metadata={}, ) ) - prepared = await runtime.handoff.for_scope("project").finalize( + prepared = await runtime.handoff.for_scope(scope.scope_id).finalize( HandoffDraft( objective="Recover the selected milestone.", state=( @@ -325,7 +349,7 @@ async def scenario() -> None: transferred_value = prepared.model_dump_json(by_alias=True) async with open_builtin_runtime(config) as runtime: - handoffs = runtime.handoff.for_scope("project") + handoffs = runtime.handoff.for_scope(scope.scope_id) restored_temporary = PreparedHandoff.model_validate_json(transferred_value) assert (await handoffs.continue_latest()).status == "empty" @@ -333,7 +357,7 @@ async def scenario() -> None: committed = await handoffs.commit(restored_temporary) async with open_builtin_runtime(config) as runtime: - handoffs = runtime.handoff.for_scope("project") + handoffs = runtime.handoff.for_scope(scope.scope_id) recovered = await handoffs.continue_latest() assert recovered.status == "resolved" diff --git a/tests/e2e/test_memory_search_concurrency.py b/tests/e2e/test_memory_search_concurrency.py index 940d92c3d..630088e26 100644 --- a/tests/e2e/test_memory_search_concurrency.py +++ b/tests/e2e/test_memory_search_concurrency.py @@ -41,6 +41,7 @@ SearchMemoryRequest, open_builtin_runtime, ) +from powercontext.builtin.scope import ScopeDraft from powercontext.errors import RevisionConflictError DatabaseKind = Literal["sqlite", "oceanbase"] @@ -103,7 +104,15 @@ async def scenario() -> None: BuiltinConfig(database=database), embedding_model=embedding_model, ) as runtime: - memory = runtime.memory.for_scope(f"concurrent-memory-search-{uuid4()}") + assert runtime.scopes is not None + scope = await runtime.scopes.create( + ScopeDraft( + title="Concurrent Memory search", + summary="Index snapshot consistency", + idempotency_key=f"concurrent-memory-search-{uuid4()}", + ) + ) + memory = runtime.memory.for_scope(scope.scope_id) initial = await memory.remember( RememberMemoryRequest(entries=(MemoryEntryInput(kind="fact", text="Stable searchable fact."),)) ) @@ -159,7 +168,13 @@ async def scenario() -> None: reranker = _PausingReranker() database = SQLiteConfig(url=f"sqlite+aiosqlite:///{tmp_path / 'rerank-snapshot.db'}") async with open_builtin_runtime(BuiltinConfig(database=database), memory_reranker=reranker) as runtime: - memory = runtime.memory.for_scope("rerank-snapshot") + assert runtime.scopes is not None + scope = await runtime.scopes.create( + ScopeDraft( + title="Rerank snapshot", summary="Stable revision snapshot", idempotency_key="rerank-snapshot" + ) + ) + memory = runtime.memory.for_scope(scope.scope_id) initial = await memory.remember( RememberMemoryRequest(entries=(MemoryEntryInput(kind="fact", text="Stable searchable fact."),)) ) @@ -192,7 +207,15 @@ async def scenario() -> None: def test_memory_search_reports_revision_conflict_when_every_attempt_starts_from_a_stale_head() -> None: async def scenario() -> None: async with open_builtin_runtime(BuiltinConfig(database=SQLiteConfig())) as runtime: - scope_id = "perpetually-stale-search" + assert runtime.scopes is not None + scope = await runtime.scopes.create( + ScopeDraft( + title="Perpetually stale search", + summary="Revision conflict retry limit", + idempotency_key="perpetually-stale-search", + ) + ) + scope_id = scope.scope_id memory = runtime.memory.for_scope(scope_id) await memory.remember( RememberMemoryRequest(entries=(MemoryEntryInput(kind="fact", text="Stable searchable fact."),)) diff --git a/tests/e2e/test_observability.py b/tests/e2e/test_observability.py index 8c26446ba..d2ea729a1 100644 --- a/tests/e2e/test_observability.py +++ b/tests/e2e/test_observability.py @@ -51,6 +51,7 @@ from powercontext.builtin.persistence.sqlite import SQLiteConfig from powercontext.builtin.runtime import BuiltinConfig, RememberMemoryRequest, open_builtin_runtime from powercontext.builtin.runtime.config import InferenceConfig, RuntimeConfig +from powercontext.builtin.scope import ScopeDraft from powercontext.errors import RevisionConflictError from powercontext.server.factory import create_server_app from powercontext.server.logging import OperationalContextFilter @@ -614,14 +615,20 @@ def test_scope_lock_stage_span_reports_contention_and_closes_at_acquisition(tmp_ exporter = InMemorySpanExporter() provider = TracerProvider(sampler=ALWAYS_ON, shutdown_on_exit=False) provider.add_span_processor(SimpleSpanProcessor(exporter)) - scope_id = "project:private-lock-scope" + scope_id = "" memory_content = "Private lock sentinel evidence." async def scenario() -> None: + nonlocal scope_id async with open_builtin_runtime( BuiltinConfig(database=SQLiteConfig(url=f"sqlite+aiosqlite:///{tmp_path / 'scope-lock.db'}")), tracing=ServerTracing(provider), ) as runtime: + assert runtime.scopes is not None + scope = await runtime.scopes.create( + ScopeDraft(title="Private lock", summary="Lock observability", idempotency_key="private-lock") + ) + scope_id = scope.scope_id memory = runtime.memory.for_scope(scope_id) first = await memory.remember( RememberMemoryRequest(entries=(MemoryEntryInput(kind="fact", text=memory_content),)) @@ -669,22 +676,23 @@ async def scenario() -> None: def test_scope_lock_is_released_when_stage_teardown_fails(tmp_path) -> None: - scope_id = "project:private-broken-tracing" - async def scenario() -> bool: - async with ( - open_builtin_runtime( - BuiltinConfig(database=SQLiteConfig(url=f"sqlite+aiosqlite:///{tmp_path / 'broken-tracing.db'}")), - tracing=_ScopeLockTeardownFailingTracing(), - ) as runtime, - runtime._scope_operation(scope_id), - ): - lock = runtime._lock(scope_id) - with pytest.raises(_StageTeardownError): - await runtime.memory.for_scope(scope_id).remember( - RememberMemoryRequest(entries=(MemoryEntryInput(kind="fact", text="Guarded fact."),)) - ) - return lock.locked() + async with open_builtin_runtime( + BuiltinConfig(database=SQLiteConfig(url=f"sqlite+aiosqlite:///{tmp_path / 'broken-tracing.db'}")), + tracing=_ScopeLockTeardownFailingTracing(), + ) as runtime: + assert runtime.scopes is not None + scope = await runtime.scopes.create( + ScopeDraft(title="Broken tracing", summary="Lock teardown", idempotency_key="broken-tracing") + ) + scope_id = scope.scope_id + async with runtime._scope_operation(scope_id): + lock = runtime._lock(scope_id) + with pytest.raises(_StageTeardownError): + await runtime.memory.for_scope(scope_id).remember( + RememberMemoryRequest(entries=(MemoryEntryInput(kind="fact", text="Guarded fact."),)) + ) + return lock.locked() assert asyncio.run(scenario()) is False From f45cc692bdc5a14dce04020c0e6f76e2e8f72fb2 Mon Sep 17 00:00:00 2001 From: Chojan Shang <psiace@apache.org> Date: Thu, 3 Sep 2026 00:07:41 +0800 Subject: [PATCH 11/17] fix(scope): serialize hierarchy mutations --- src/powercontext/builtin/scope/application.py | 1 + src/powercontext/builtin/scope/repository.py | 7 ++++++ tests/builtin/test_scope_application.py | 22 +++++++++++++------ 3 files changed, 23 insertions(+), 7 deletions(-) diff --git a/src/powercontext/builtin/scope/application.py b/src/powercontext/builtin/scope/application.py index 93eb75b66..2f898dbb1 100644 --- a/src/powercontext/builtin/scope/application.py +++ b/src/powercontext/builtin/scope/application.py @@ -129,6 +129,7 @@ async def update(self, scope_id: str, mutation: ScopeMutation, /) -> ScopeDescri async def _update(self, scope_id: str, mutation: ScopeMutation) -> ScopeDescriptor: async with self._database.transaction() as connection: + await self._repository.lock_hierarchy(connection) current = await self._required(connection, scope_id) if current.version != mutation.expected_version: raise ScopeVersionConflictError(scope_id, mutation.expected_version, current.version) diff --git a/src/powercontext/builtin/scope/repository.py b/src/powercontext/builtin/scope/repository.py index f1e7f2008..b9bc15932 100644 --- a/src/powercontext/builtin/scope/repository.py +++ b/src/powercontext/builtin/scope/repository.py @@ -63,6 +63,13 @@ async def get_many( async def list(self, connection: AsyncConnection, /) -> tuple[ScopeDescriptor, ...]: return await self._load(connection, select(SCOPES_TABLE).order_by(SCOPES_TABLE.c.scope_id)) + async def lock_hierarchy(self, connection: AsyncConnection, /) -> None: + """Serialize Parent validation and mutation across Runtime instances.""" + + # A no-op write acquires the same graph-wide boundary on SQLite and + # row-locking databases without relying on dialect-specific locks. + await connection.execute(update(SCOPES_TABLE).values(version=SCOPES_TABLE.c.version)) + async def _load(self, connection: AsyncConnection, statement, /) -> tuple[ScopeDescriptor, ...]: rows = tuple((await connection.execute(statement)).mappings()) scope_ids = tuple(str(row["scope_id"]) for row in rows) diff --git a/tests/builtin/test_scope_application.py b/tests/builtin/test_scope_application.py index 5e8935703..1f90f2359 100644 --- a/tests/builtin/test_scope_application.py +++ b/tests/builtin/test_scope_application.py @@ -197,15 +197,17 @@ async def scenario() -> None: asyncio.run(scenario()) -def test_concurrent_parent_updates_cannot_form_a_cycle() -> None: +def test_concurrent_parent_updates_cannot_form_a_cycle(tmp_path) -> None: async def scenario() -> None: - async with SQLiteProfile.open(SQLiteConfig(), tables=BUILTIN_TABLES) as profile: - scopes = ScopeApplication(profile.database) - left = await scopes.create(ScopeDraft(title="Left", summary="Left", idempotency_key="left")) - right = await scopes.create(ScopeDraft(title="Right", summary="Right", idempotency_key="right")) + config = SQLiteConfig(url=f"sqlite+aiosqlite:///{tmp_path / 'runtime.db'}") + async with SQLiteProfile.open(config, tables=BUILTIN_TABLES) as profile: + left_application = ScopeApplication(profile.database) + right_application = ScopeApplication(profile.database) + left = await left_application.create(ScopeDraft(title="Left", summary="Left", idempotency_key="left")) + right = await left_application.create(ScopeDraft(title="Right", summary="Right", idempotency_key="right")) updates = await asyncio.gather( - scopes.update( + left_application.update( left.scope_id, ScopeMutation( expected_version=left.version, @@ -214,7 +216,7 @@ async def scenario() -> None: parent_scope_id=right.scope_id, ), ), - scopes.update( + right_application.update( right.scope_id, ScopeMutation( expected_version=right.version, @@ -227,6 +229,12 @@ async def scenario() -> None: ) assert sum(isinstance(result, ScopeRelationshipError) for result in updates) == 1 + assert sum(not isinstance(result, BaseException) for result in updates) == 1 + persisted = {scope.scope_id: scope for scope in await left_application.list()} + assert not ( + persisted[left.scope_id].parent_scope_id == right.scope_id + and persisted[right.scope_id].parent_scope_id == left.scope_id + ) asyncio.run(scenario()) From 056dd9ef185425044314ccebd7fbb7ee7f4173fa Mon Sep 17 00:00:00 2001 From: Chojan Shang <psiace@apache.org> Date: Thu, 3 Sep 2026 00:07:48 +0800 Subject: [PATCH 12/17] fix(codex): guard operations by scope mode --- .../plugins/powercontext/hooks/bind_tools.py | 26 +++++-- tests/codex_plugin/test_scope_binding.py | 73 +++++++++++++++++++ 2 files changed, 93 insertions(+), 6 deletions(-) diff --git a/integrations/codex/plugins/powercontext/hooks/bind_tools.py b/integrations/codex/plugins/powercontext/hooks/bind_tools.py index 5ea2ef434..a3d86ff07 100644 --- a/integrations/codex/plugins/powercontext/hooks/bind_tools.py +++ b/integrations/codex/plugins/powercontext/hooks/bind_tools.py @@ -36,9 +36,9 @@ _PREFIX = "mcp__powercontext__" _CONTROL_OPERATIONS = frozenset({"set_scope_binding", "clear_scope_binding"}) -_CURRENT_SCOPE_OPERATIONS = frozenset({"resolve_scope_binding"}) +_RESOLVE_OPERATIONS = frozenset({"resolve_scope_binding"}) _HOST_OPERATIONS = frozenset({"create_scope", "get_scope", "list_scopes", "publish_artifact"}) -_SCOPE_BOUND_OPERATIONS = frozenset({ +_CURRENT_OPERATIONS = frozenset({ "acknowledge_handoff", "activate_handoff", "approve_artifact_candidate", @@ -47,20 +47,34 @@ "continue_handoff", "create_work_contract", "finalize_handoff", + "flush_memory", + "generate_experience", + "generate_skill", "get_artifact_candidate", - "get_handoff_report", + "get_experience", "get_memory_entry", + "get_skill", "handoff_current_work", + "import_external_skill", "list_artifact_candidates", + "list_external_skills", + "list_memory_changes", "list_memory_entries", + "prepare_context", + "prepare_handoff", + "propose_experience", + "propose_skill", "record_task_outcome", "reject_artifact_candidate", "remember_memory", + "resolve_external_skill", "retire_memory_entry", "revise_artifact_candidate", "revise_memory_entry", + "scan_external_skills", "search_memory", }) +_SELECTION_OPERATIONS = frozenset({"get_handoff_report", "get_stats"}) def main(settings: CodexPluginSettings | None = None) -> int: @@ -84,7 +98,7 @@ def main(settings: CodexPluginSettings | None = None) -> int: updated["key"] = session_binding_key(session_id) _allow(updated) return 0 - if operation in _CURRENT_SCOPE_OPERATIONS: + if operation in _RESOLVE_OPERATIONS: settings = CodexPluginSettings() if settings is None else settings _allow({ "explicit_scope_id": settings.scope_id, @@ -94,7 +108,7 @@ def main(settings: CodexPluginSettings | None = None) -> int: if operation in _HOST_OPERATIONS: _allow(dict(tool_input)) return 0 - if operation not in _SCOPE_BOUND_OPERATIONS: + if operation not in _CURRENT_OPERATIONS and operation not in _SELECTION_OPERATIONS: return 0 settings = CodexPluginSettings() if settings is None else settings scope_id = resolve_scope_id( @@ -104,7 +118,7 @@ def main(settings: CodexPluginSettings | None = None) -> int: deadline=monotonic() + settings.http_budget_seconds, ) updated = dict(tool_input) - if operation == "get_handoff_report": + if operation in _SELECTION_OPERATIONS: updated["selection"] = {"mode": "exact", "scope_ids": [scope_id]} else: updated["scope_id"] = scope_id diff --git a/tests/codex_plugin/test_scope_binding.py b/tests/codex_plugin/test_scope_binding.py index 4f60f253a..5ab6c373b 100644 --- a/tests/codex_plugin/test_scope_binding.py +++ b/tests/codex_plugin/test_scope_binding.py @@ -21,6 +21,20 @@ import pytest +from powercontext.http._generated import operations as generated_operations + + +def _operations_with_scope_mode(scope_mode: str) -> frozenset[str]: + return frozenset( + value.operation_id + for value in vars(generated_operations).values() + if isinstance(value, generated_operations.Operation) and value.scope_mode == scope_mode + ) + + +CURRENT_OPERATIONS = _operations_with_scope_mode("current") +SELECTION_OPERATIONS = _operations_with_scope_mode("selection") + def test_pre_tool_hook_overwrites_agent_scope_with_session_binding( bind_tools_module: ModuleType, @@ -54,6 +68,65 @@ def test_pre_tool_hook_overwrites_agent_scope_with_session_binding( assert result["updatedInput"]["text"] == "Use Scope binding." +def test_pre_tool_hook_scope_modes_match_generated_openapi_metadata(bind_tools_module: ModuleType) -> None: + assert bind_tools_module._CURRENT_OPERATIONS == CURRENT_OPERATIONS + assert bind_tools_module._SELECTION_OPERATIONS == SELECTION_OPERATIONS + + +@pytest.mark.parametrize("operation", sorted(CURRENT_OPERATIONS)) +def test_pre_tool_hook_binds_every_current_scope_operation( + operation: str, + bind_tools_module: ModuleType, + monkeypatch: pytest.MonkeyPatch, +) -> None: + monkeypatch.setattr(bind_tools_module, "resolve_scope_id", lambda *_args, **_kwargs: "bound-scope") + monkeypatch.setattr( + sys, + "stdin", + io.StringIO( + json.dumps({ + "session_id": "session-a", + "cwd": "/workspace", + "tool_name": f"mcp__powercontext__{operation}", + "tool_input": {"scope_id": "agent-selected"}, + }) + ), + ) + output = io.StringIO() + monkeypatch.setattr(sys, "stdout", output) + + assert bind_tools_module.main() == 0 + updated = json.loads(output.getvalue())["hookSpecificOutput"]["updatedInput"] + assert updated["scope_id"] == "bound-scope" + + +@pytest.mark.parametrize("operation", sorted(SELECTION_OPERATIONS)) +def test_pre_tool_hook_binds_every_selection_scope_operation( + operation: str, + bind_tools_module: ModuleType, + monkeypatch: pytest.MonkeyPatch, +) -> None: + monkeypatch.setattr(bind_tools_module, "resolve_scope_id", lambda *_args, **_kwargs: "bound-scope") + monkeypatch.setattr( + sys, + "stdin", + io.StringIO( + json.dumps({ + "session_id": "session-a", + "cwd": "/workspace", + "tool_name": f"mcp__powercontext__{operation}", + "tool_input": {"selection": {"mode": "all"}}, + }) + ), + ) + output = io.StringIO() + monkeypatch.setattr(sys, "stdout", output) + + assert bind_tools_module.main() == 0 + updated = json.loads(output.getvalue())["hookSpecificOutput"]["updatedInput"] + assert updated["selection"] == {"mode": "exact", "scope_ids": ["bound-scope"]} + + def test_pre_tool_hook_fixes_control_binding_to_current_session( bind_tools_module: ModuleType, monkeypatch: pytest.MonkeyPatch, From 5e35afde075f68f687d3f8263a48c17d619c5fa6 Mon Sep 17 00:00:00 2001 From: Chojan Shang <psiace@apache.org> Date: Thu, 3 Sep 2026 00:07:57 +0800 Subject: [PATCH 13/17] fix(publication): reject incomplete memory copies --- openapi/powercontext.yaml | 2 + src/powercontext/builtin/publication.py | 13 +++++- src/powercontext/http/_generated/schema.py | 4 ++ src/powercontext/server/app.py | 8 ++++ tests/builtin/test_publication.py | 51 +++++++++++++++++++++- tests/test_scope_api.py | 31 +++++-------- 6 files changed, 86 insertions(+), 23 deletions(-) diff --git a/openapi/powercontext.yaml b/openapi/powercontext.yaml index 7cde60e8f..68e9827d9 100644 --- a/openapi/powercontext.yaml +++ b/openapi/powercontext.yaml @@ -124,6 +124,8 @@ paths: post: tags: [scopes] summary: Publish one exact Artifact revision into another Scope + description: >- + Memory publication is rejected until its complete family-owned state can be created atomically in the target Scope. operationId: publish_artifact requestBody: required: true diff --git a/src/powercontext/builtin/publication.py b/src/powercontext/builtin/publication.py index 8f5b7329f..43ca24781 100644 --- a/src/powercontext/builtin/publication.py +++ b/src/powercontext/builtin/publication.py @@ -80,6 +80,14 @@ class ArtifactPublicationConflictError(PowerContextError, RuntimeError): """Report reuse of an idempotency key for a different publication.""" +class ArtifactPublicationUnsupportedError(PowerContextError, RuntimeError): + """Report an Artifact family that cannot yet form a complete target revision.""" + + def __init__(self, family: str) -> None: + self.family = family + super().__init__(f"Artifact publication is not supported for family: {family}") + + class ArtifactPublicationApplication: def __init__( self, @@ -103,13 +111,15 @@ async def _publish(self, request: ArtifactPublicationRequest) -> ArtifactPublica await self._scopes.get(request.source.scope_id) await self._scopes.get(request.target_scope_id) async with self._database.transaction() as connection: + source = await self._artifacts.get(connection, request.source.scope_id, request.source.artifact) + if source.family == "memory": + raise ArtifactPublicationUnsupportedError(source.family) existing = await self._find_request(connection, request.target_scope_id, request.idempotency_key) if existing is not None: if existing.source != request.source: raise ArtifactPublicationConflictError(request.idempotency_key) return existing - source = await self._artifacts.get(connection, request.source.scope_id, request.source.artifact) content_digest = hashlib.sha256(dump_model(source.content, kind="artifact", name=source.family)).hexdigest() target = await self._artifacts.copy_exact( connection, @@ -218,4 +228,5 @@ def _decode_publication(row: Mapping[Any, Any]) -> ArtifactPublication: "ArtifactPublicationApplication", "ArtifactPublicationConflictError", "ArtifactPublicationRequest", + "ArtifactPublicationUnsupportedError", ] diff --git a/src/powercontext/http/_generated/schema.py b/src/powercontext/http/_generated/schema.py index c7137c08d..565c41b1c 100644 --- a/src/powercontext/http/_generated/schema.py +++ b/src/powercontext/http/_generated/schema.py @@ -98,6 +98,10 @@ "post": { "tags": ["scopes"], "summary": "Publish one exact Artifact revision into another Scope", + "description": "Memory publication is rejected " + "until its complete family-owned " + "state can be created atomically " + "in the target Scope.", "operationId": "publish_artifact", "requestBody": { "content": { diff --git a/src/powercontext/server/app.py b/src/powercontext/server/app.py index 49aac5962..2e8657943 100644 --- a/src/powercontext/server/app.py +++ b/src/powercontext/server/app.py @@ -74,6 +74,7 @@ from powercontext.builtin.publication import ( ArtifactPublicationApplication, ArtifactPublicationConflictError, + ArtifactPublicationUnsupportedError, ) from powercontext.builtin.publication import ( ArtifactPublicationRequest as DomainArtifactPublicationRequest, @@ -1544,6 +1545,13 @@ def _map_error(error: Exception) -> tuple[int, str, str, dict[str, Any] | None]: def _map_scope_error(error: Exception) -> tuple[int, str, str, dict[str, Any] | None] | None: + if isinstance(error, ArtifactPublicationUnsupportedError): + return ( + status.HTTP_422_UNPROCESSABLE_CONTENT, + "artifact_publication_unsupported", + "The Artifact family cannot be published as complete target state.", + {"family": error.family}, + ) if isinstance(error, ArtifactPublicationConflictError): return ( status.HTTP_409_CONFLICT, diff --git a/tests/builtin/test_publication.py b/tests/builtin/test_publication.py index d9baa68d6..b05ea6262 100644 --- a/tests/builtin/test_publication.py +++ b/tests/builtin/test_publication.py @@ -18,7 +18,8 @@ import pytest -from powercontext.artifacts import ArtifactAddress +from powercontext.artifacts import ArtifactAddress, ArtifactRef +from powercontext.builtin.artifacts.memory import MemoryEntryInput from powercontext.builtin.persistence.artifacts import ArtifactRepository from powercontext.builtin.persistence.sqlite import SQLiteConfig, SQLiteProfile from powercontext.builtin.persistence.tables import BUILTIN_TABLES @@ -26,8 +27,11 @@ ArtifactPublicationApplication, ArtifactPublicationConflictError, ArtifactPublicationRequest, + ArtifactPublicationUnsupportedError, ) +from powercontext.builtin.runtime import BuiltinConfig, open_builtin_contexts from powercontext.builtin.scope import ScopeApplication, ScopeDraft +from powercontext.errors import ArtifactNotFoundError from tests.builtin.persistence.contract import Report, ReportContent, ReportDraft @@ -136,3 +140,48 @@ async def scenario() -> None: ) asyncio.run(scenario()) + + +def test_memory_publication_is_rejected_without_target_state() -> None: + async def scenario() -> None: + async with open_builtin_contexts(BuiltinConfig(database=SQLiteConfig())) as contexts: + source_scope = await contexts.scopes.create( + ScopeDraft(title="Source", summary="Private working state", idempotency_key="source") + ) + target_scope = await contexts.scopes.create( + ScopeDraft(title="Target", summary="Accepted result", idempotency_key="target") + ) + source = await contexts.get(source_scope.scope_id) + memory = await source.artifacts.memory.remember( + memory=None, + entries=(MemoryEntryInput(kind="decision", text="Keep publication state complete."),), + mode="append", + ) + assert memory is not None + publications = ArtifactPublicationApplication( + contexts.database, + contexts.repositories.artifacts, + contexts.scopes, + id_factory=lambda: "pub_blocked", + ) + request = ArtifactPublicationRequest( + source=ArtifactAddress(scope_id=source_scope.scope_id, artifact=memory.as_ref()), + target_scope_id=target_scope.scope_id, + idempotency_key="publish-memory", + ) + + for _ in range(2): + with pytest.raises(ArtifactPublicationUnsupportedError, match="family: memory") as raised: + await publications.publish(request) + assert raised.value.family == "memory" + + target_address = ArtifactAddress( + scope_id=target_scope.scope_id, + artifact=ArtifactRef(family="memory", artifact_id="pub_blocked", revision=1), + ) + assert await publications.get(target_address) is None + target = await contexts.get(target_scope.scope_id) + with pytest.raises(ArtifactNotFoundError): + await target.artifacts.memory.revision(target_address.artifact) + + asyncio.run(scenario()) diff --git a/tests/test_scope_api.py b/tests/test_scope_api.py index 59fb91a4e..afc88f73f 100644 --- a/tests/test_scope_api.py +++ b/tests/test_scope_api.py @@ -131,7 +131,7 @@ def test_scope_http_flow_rejects_stale_metadata_and_invalid_selection(tmp_path) assert invalid.status_code == 422 -def test_scope_http_flow_publishes_one_exact_artifact(tmp_path) -> None: +def test_scope_http_flow_rejects_incomplete_memory_publication(tmp_path) -> None: app = create_server_app( settings=ServerSettings( database=SQLiteConfig(url=f"sqlite+aiosqlite:///{tmp_path / 'runtime.db'}"), @@ -158,28 +158,17 @@ def test_scope_http_flow_publishes_one_exact_artifact(tmp_path) -> None: "idempotency_key": "accepted-decision", } - created = client.post("/v1/artifact-publications", json=request) + rejected = client.post("/v1/artifact-publications", json=request) repeated = client.post("/v1/artifact-publications", json=request) - assert created.status_code == 201 - assert repeated.status_code == 201 - assert created.json() == repeated.json() - assert created.json()["source"] == request["source"] - assert created.json()["target"]["scope_id"] == target_scope_id - assert created.json()["target"]["artifact"]["revision"] == 1 - - conflicting = client.post( - "/v1/artifact-publications", - json={ - **request, - "source": { - "scope_id": source_scope_id, - "artifact": {**memory, "revision": memory["revision"] + 1}, - }, - }, - ) - assert conflicting.status_code == 409 - assert conflicting.json()["error"]["code"] == "artifact_publication_conflict" + assert rejected.status_code == 422 + assert repeated.status_code == 422 + assert rejected.json() == repeated.json() + assert rejected.json()["error"] == { + "code": "artifact_publication_unsupported", + "message": "The Artifact family cannot be published as complete target state.", + "details": {"family": "memory"}, + } def test_data_plane_rejects_an_unknown_scope(tmp_path) -> None: From 3daf855ecd4838c40b3aad2c402f888ae2e2cff6 Mon Sep 17 00:00:00 2001 From: Chojan Shang <psiace@apache.org> Date: Thu, 3 Sep 2026 00:29:48 +0800 Subject: [PATCH 14/17] fix(ci): escape plugin shell variable safely --- .github/workflows/build-artifacts.yml | 7 ++++--- tests/codex_plugin/test_contract.py | 7 +++++++ 2 files changed, 11 insertions(+), 3 deletions(-) diff --git a/.github/workflows/build-artifacts.yml b/.github/workflows/build-artifacts.yml index 2cf17bc38..f86821326 100644 --- a/.github/workflows/build-artifacts.yml +++ b/.github/workflows/build-artifacts.yml @@ -254,6 +254,7 @@ jobs: root = Path(os.environ["PLUGIN_ROOT"]) python_executable = f"python{os.environ['PYTHON_VERSION']}" + plugin_root = "$" + "{PLUGIN_ROOT}" hooks_path = root / "hooks/hooks.json" hooks = json.loads(hooks_path.read_text()) hook_scripts = { @@ -264,15 +265,15 @@ jobs: for event, script in hook_scripts.items(): hook = hooks["hooks"][event][0]["hooks"][0] expected = ( - 'uv run --frozen --quiet --project "${PLUGIN_ROOT}" ' - f'python "${{PLUGIN_ROOT}}/hooks/{script}"' + f'uv run --frozen --quiet --project "{plugin_root}" ' + f'python "{plugin_root}/hooks/{script}"' ) if hook["command"] != expected: raise SystemExit(f"unexpected Codex {event} command") hook["command"] = ( 'PYTHONPATH="${PLUGIN_ROOT}/vendor" ' + python_executable - + f' "${{PLUGIN_ROOT}}/hooks/{script}"' + + f' "{plugin_root}/hooks/{script}"' ) hooks_path.write_text(json.dumps(hooks, indent=2) + "\n") diff --git a/tests/codex_plugin/test_contract.py b/tests/codex_plugin/test_contract.py index c6e37c082..de0508ffa 100644 --- a/tests/codex_plugin/test_contract.py +++ b/tests/codex_plugin/test_contract.py @@ -23,6 +23,7 @@ from pydantic import ValidationError PLUGIN_ROOT = Path(__file__).resolve().parents[2] / "integrations" / "codex" / "plugins" / "powercontext" +REPOSITORY_ROOT = PLUGIN_ROOT.parents[3] def test_scope_resolver_uses_server_binding_and_fixes_new_session( @@ -162,6 +163,12 @@ def test_codex_hooks_fix_session_and_data_plane_bindings() -> None: assert "bind_tools.py" in pre_tool_use["hooks"][0]["command"] +def test_customer_artifact_workflow_does_not_parse_plugin_root_as_an_actions_expression() -> None: + workflow = (REPOSITORY_ROOT / ".github" / "workflows" / "build-artifacts.yml").read_text() + + assert "${{PLUGIN_ROOT}}" not in workflow + + def test_powercontext_plugin_advertises_the_one_turn_handoff() -> None: manifest = json.loads((PLUGIN_ROOT / ".codex-plugin" / "plugin.json").read_text()) prompts = manifest["interface"]["defaultPrompt"] From 3a14f3aa2f0c7013f249d632535d398a4736f198 Mon Sep 17 00:00:00 2001 From: Chojan Shang <psiace@apache.org> Date: Thu, 3 Sep 2026 16:07:36 +0800 Subject: [PATCH 15/17] fix(runtime): preserve referenced scope recall --- .../builtin/runtime/application.py | 57 +++++++++++++++++-- .../builtin/runtime/prepared_context.py | 41 +++++++------ tests/e2e/test_builtin_runtime.py | 41 +++++++++++++ 3 files changed, 115 insertions(+), 24 deletions(-) diff --git a/src/powercontext/builtin/runtime/application.py b/src/powercontext/builtin/runtime/application.py index 994bd9874..7411d262e 100644 --- a/src/powercontext/builtin/runtime/application.py +++ b/src/powercontext/builtin/runtime/application.py @@ -404,19 +404,20 @@ async def _prepare(self, request: PrepareContextRequest, scope: ScopeDescriptor, memory_candidates: list[PreparedMemoryCandidates] = [] experience_candidates: list[PreparedExperienceCandidates] = [] - remaining_memory = builder.memory_candidate_limit - remaining_experience = builder.experience_candidate_limit for scope_id in scope_ids: memory, experiences = await self._recall_scope( scope_id, request, - memory_limit=remaining_memory, - experience_limit=remaining_experience, + memory_limit=builder.memory_candidate_limit, + experience_limit=builder.experience_candidate_limit, ) memory_candidates.append(memory) experience_candidates.append(experiences) - remaining_memory -= len(memory.hits) - remaining_experience -= len(experiences.hits) + memory_candidates = _limit_memory_candidates(memory_candidates, builder.memory_candidate_limit) + experience_candidates = _limit_experience_candidates( + experience_candidates, + builder.experience_candidate_limit, + ) with self._runtime._stage( "context.build", @@ -532,6 +533,50 @@ async def _recall_scope( ) +def _limit_memory_candidates( + candidates: list[PreparedMemoryCandidates], + limit: int, +) -> list[PreparedMemoryCandidates]: + counts = _round_robin_counts(tuple(len(group.hits) for group in candidates), limit) + return [ + PreparedMemoryCandidates( + scope_id=group.scope_id, + memory_ref=group.memory_ref, + hits=group.hits[:count], + ) + for group, count in zip(candidates, counts, strict=True) + ] + + +def _limit_experience_candidates( + candidates: list[PreparedExperienceCandidates], + limit: int, +) -> list[PreparedExperienceCandidates]: + counts = _round_robin_counts(tuple(len(group.hits) for group in candidates), limit) + return [ + PreparedExperienceCandidates(scope_id=group.scope_id, hits=group.hits[:count]) + for group, count in zip(candidates, counts, strict=True) + ] + + +def _round_robin_counts(sizes: tuple[int, ...], limit: int) -> tuple[int, ...]: + counts = [0] * len(sizes) + remaining = limit + while remaining > 0: + advanced = False + for index, size in enumerate(sizes): + if counts[index] >= size: + continue + counts[index] += 1 + remaining -= 1 + advanced = True + if remaining == 0: + break + if not advanced: + break + return tuple(counts) + + class ContextApplication: """Select the scoped context-preparation application service.""" diff --git a/src/powercontext/builtin/runtime/prepared_context.py b/src/powercontext/builtin/runtime/prepared_context.py index 218dbc2cd..6837192e8 100644 --- a/src/powercontext/builtin/runtime/prepared_context.py +++ b/src/powercontext/builtin/runtime/prepared_context.py @@ -139,23 +139,25 @@ def build_scopes_result( if sum(len(candidates.hits) for candidates in experience_candidates) > self.experience_candidate_limit: raise PreparedContextInvariantError("experience-candidate-limit") - memory_entries = tuple( - entry - for candidates in memory_candidates - for entry in self._memory_entries( - candidates.memory_ref, - candidates.hits, - scope_id=None if candidates.scope_id == current_scope_id else candidates.scope_id or None, + memory_entries = _interleave_groups( + tuple( + self._memory_entries( + candidates.memory_ref, + candidates.hits, + scope_id=None if candidates.scope_id == current_scope_id else candidates.scope_id or None, + ) + for candidates in memory_candidates ) ) - experience_entries = tuple( - entry - for candidates in experience_candidates - for entry in self._experience_entries( - candidates.hits, - scope_id=None if candidates.scope_id == current_scope_id else candidates.scope_id or None, + experience_entries = _interleave_groups( + tuple( + self._experience_entries( + candidates.hits, + scope_id=None if candidates.scope_id == current_scope_id else candidates.scope_id or None, + ) + for candidates in experience_candidates ) - ) + )[: self.experience_entry_limit] entries = self._fit_entries(request, memory_entries, experience_entries) if not entries: @@ -190,8 +192,6 @@ def _memory_entries( seen.add(citation_key) if not hit.entry_id.strip() or not hit.entry_version_id.strip() or not hit.text.strip(): continue - if len(memory_entries) >= self.entry_limit: - break citation = MemoryCitation( memory_ref=hit.memory_ref, entry_id=hit.entry_id, @@ -237,8 +237,6 @@ def _experience_entries( if identity in seen_experiences: continue seen_experiences.add(identity) - if len(experience_entries) >= self.experience_entry_limit: - break origin: PreparedContextOrigin = hit.artifact_ref rendered_citation: dict[str, object] = {"artifact_ref": hit.artifact_ref.model_dump(mode="json")} if scope_id is not None: @@ -339,6 +337,13 @@ def _interleave( return tuple(ordered) +def _interleave_groups(groups: Sequence[Sequence[_PreparedContextEntry]]) -> tuple[_PreparedContextEntry, ...]: + ordered: list[_PreparedContextEntry] = [] + for index in range(max((len(group) for group in groups), default=0)): + ordered.extend(group[index] for group in groups if index < len(group)) + return tuple(ordered) + + def _render(entries: Sequence[_PreparedContextEntry]) -> str: envelope = { "trust": "untrusted_history", diff --git a/tests/e2e/test_builtin_runtime.py b/tests/e2e/test_builtin_runtime.py index fbc6b9a60..34cd0ba30 100644 --- a/tests/e2e/test_builtin_runtime.py +++ b/tests/e2e/test_builtin_runtime.py @@ -240,6 +240,47 @@ async def scenario() -> None: asyncio.run(scenario()) +def test_prepare_context_keeps_referenced_scope_eligible_when_local_recall_is_full() -> None: + async def scenario() -> None: + async with open_builtin_runtime(BuiltinConfig(database=SQLiteConfig())) as runtime: + assert runtime.scopes is not None + shared = await runtime.scopes.create( + ScopeDraft(title="Shared", summary="Reusable evidence", idempotency_key="shared-full-recall") + ) + reader = await runtime.scopes.create( + ScopeDraft( + title="Reader", + summary="Reads shared evidence", + context_references=(shared.scope_id,), + idempotency_key="reader-full-recall", + ) + ) + await runtime.memory.for_scope(reader.scope_id).remember( + RememberMemoryRequest( + entries=tuple( + MemoryEntryInput(kind="fact", text=f"Candidate saturation local evidence {index}.") + for index in range(16) + ) + ) + ) + await runtime.memory.for_scope(shared.scope_id).remember( + RememberMemoryRequest( + entries=(MemoryEntryInput(kind="fact", text="Candidate saturation shared evidence."),) + ) + ) + + prepared = await runtime.context.for_scope(reader.scope_id).prepare( + PrepareContextRequest(query="candidate saturation evidence") + ) + + assert prepared.status == "ready" + assert prepared.content is not None + items = json.loads(prepared.content.splitlines()[-2])["items"] + assert any(item["citation"].get("memory", {}).get("scope_id") == shared.scope_id for item in items) + + asyncio.run(scenario()) + + class _ConcurrentReranker: policy_id = "test.concurrent-rerank.v1" From a7e5e7b2a612e0d1bd20c059a881a32b71b243d3 Mon Sep 17 00:00:00 2001 From: Chojan Shang <psiace@apache.org> Date: Thu, 3 Sep 2026 16:07:44 +0800 Subject: [PATCH 16/17] fix(publication): make delivery atomic --- src/powercontext/builtin/publication.py | 94 +++++++----- .../builtin/runtime/relational.py | 1 + tests/builtin/test_publication.py | 139 +++++++++++++++++- 3 files changed, 192 insertions(+), 42 deletions(-) diff --git a/src/powercontext/builtin/publication.py b/src/powercontext/builtin/publication.py index 43ca24781..24bb4c042 100644 --- a/src/powercontext/builtin/publication.py +++ b/src/powercontext/builtin/publication.py @@ -16,7 +16,6 @@ from __future__ import annotations -import asyncio import hashlib import secrets from collections.abc import Callable, Mapping @@ -24,12 +23,15 @@ from pydantic import BaseModel, ConfigDict, field_validator, model_validator from sqlalchemy import insert, select +from sqlalchemy.exc import IntegrityError from sqlalchemy.ext.asyncio import AsyncConnection from powercontext.artifacts import ArtifactAddress, ArtifactRef +from powercontext.builtin.artifacts.experience import Experience from powercontext.builtin.persistence.artifacts import ArtifactRepository from powercontext.builtin.persistence.codec import dump_model from powercontext.builtin.persistence.database import AsyncDatabase +from powercontext.builtin.persistence.experience_index import ExperienceIndex from powercontext.builtin.persistence.tables import ARTIFACT_PUBLICATIONS_TABLE from powercontext.builtin.scope import ScopeApplication from powercontext.errors import PowerContextError @@ -95,52 +97,63 @@ def __init__( artifacts: ArtifactRepository, scopes: ScopeApplication, *, + experience_index: ExperienceIndex, id_factory: PublicationIdFactory | None = None, ) -> None: self._database = database self._artifacts = artifacts self._scopes = scopes + self._experience_index = experience_index self._id_factory = generate_publication_artifact_id if id_factory is None else id_factory - self._write_lock = asyncio.Lock() async def publish(self, request: ArtifactPublicationRequest, /) -> ArtifactPublication: - async with self._write_lock: - return await self._publish(request) - - async def _publish(self, request: ArtifactPublicationRequest) -> ArtifactPublication: await self._scopes.get(request.source.scope_id) await self._scopes.get(request.target_scope_id) - async with self._database.transaction() as connection: - source = await self._artifacts.get(connection, request.source.scope_id, request.source.artifact) - if source.family == "memory": - raise ArtifactPublicationUnsupportedError(source.family) - existing = await self._find_request(connection, request.target_scope_id, request.idempotency_key) - if existing is not None: - if existing.source != request.source: - raise ArtifactPublicationConflictError(request.idempotency_key) - return existing - - content_digest = hashlib.sha256(dump_model(source.content, kind="artifact", name=source.family)).hexdigest() - target = await self._artifacts.copy_exact( - connection, - request.target_scope_id, - self._id_factory(), - request.source, - source, - content_digest, - ) - publication = ArtifactPublication( - source=request.source, - target=ArtifactAddress(scope_id=request.target_scope_id, artifact=target.as_ref()), - content_digest=content_digest, - ) - await connection.execute( - insert(ARTIFACT_PUBLICATIONS_TABLE).values( - **_publication_row(publication), - idempotency_key=request.idempotency_key, - ) + try: + async with self._database.transaction() as connection: + return await self._publish(connection, request) + except IntegrityError: + async with self._database.transaction() as connection: + existing = await self._find_request(connection, request.target_scope_id, request.idempotency_key) + if existing is None: + raise + return _resolve_request(existing, request) + + async def _publish( + self, + connection: AsyncConnection, + request: ArtifactPublicationRequest, + ) -> ArtifactPublication: + source = await self._artifacts.get(connection, request.source.scope_id, request.source.artifact) + if source.family == "memory": + raise ArtifactPublicationUnsupportedError(source.family) + existing = await self._find_request(connection, request.target_scope_id, request.idempotency_key) + if existing is not None: + return _resolve_request(existing, request) + + content_digest = hashlib.sha256(dump_model(source.content, kind="artifact", name=source.family)).hexdigest() + target = await self._artifacts.copy_exact( + connection, + request.target_scope_id, + self._id_factory(), + request.source, + source, + content_digest, + ) + if isinstance(target, Experience): + await self._experience_index.replace(connection, request.target_scope_id, target) + publication = ArtifactPublication( + source=request.source, + target=ArtifactAddress(scope_id=request.target_scope_id, artifact=target.as_ref()), + content_digest=content_digest, + ) + await connection.execute( + insert(ARTIFACT_PUBLICATIONS_TABLE).values( + **_publication_row(publication), + idempotency_key=request.idempotency_key, ) - return publication + ) + return publication async def get(self, target: ArtifactAddress, /) -> ArtifactPublication | None: async with self._database.transaction() as connection: @@ -187,6 +200,15 @@ def generate_publication_artifact_id() -> str: return f"pub_{encoded}" +def _resolve_request( + existing: ArtifactPublication, + request: ArtifactPublicationRequest, +) -> ArtifactPublication: + if existing.source != request.source: + raise ArtifactPublicationConflictError(request.idempotency_key) + return existing + + def _publication_row(publication: ArtifactPublication) -> dict[str, object]: return { "target_scope_id": publication.target.scope_id, diff --git a/src/powercontext/builtin/runtime/relational.py b/src/powercontext/builtin/runtime/relational.py index ac3cf3a88..8fc7a328a 100644 --- a/src/powercontext/builtin/runtime/relational.py +++ b/src/powercontext/builtin/runtime/relational.py @@ -370,6 +370,7 @@ def __init__( database, self.repositories.artifacts, self.scopes, + experience_index=self.experience_index, ) self._candidate_pipeline = candidate_pipeline self.memory_extraction = candidate_pipeline is not None diff --git a/tests/builtin/test_publication.py b/tests/builtin/test_publication.py index b05ea6262..591081f2f 100644 --- a/tests/builtin/test_publication.py +++ b/tests/builtin/test_publication.py @@ -19,8 +19,11 @@ import pytest from powercontext.artifacts import ArtifactAddress, ArtifactRef +from powercontext.builtin.artifacts.experience import ExperienceContent, ExperienceDraft from powercontext.builtin.artifacts.memory import MemoryEntryInput from powercontext.builtin.persistence.artifacts import ArtifactRepository +from powercontext.builtin.persistence.errors import RepositoryNotFoundError +from powercontext.builtin.persistence.experience_index import NoExperienceIndex from powercontext.builtin.persistence.sqlite import SQLiteConfig, SQLiteProfile from powercontext.builtin.persistence.tables import BUILTIN_TABLES from powercontext.builtin.publication import ( @@ -35,9 +38,25 @@ from tests.builtin.persistence.contract import Report, ReportContent, ReportDraft -def test_publication_copies_one_exact_revision_with_original_provenance() -> None: +class _IndexUnavailableError(RuntimeError): + pass + + +class _FailingExperienceIndex: + async def initialize(self, _connection, /) -> None: + pass + + async def replace(self, _connection, _scope_id, _experience, /) -> None: + raise _IndexUnavailableError + + async def search(self, _connection, _scope_id, _query, _limit, /): + return () + + +def test_publication_copies_one_exact_revision_with_original_provenance(tmp_path) -> None: async def scenario() -> None: - async with SQLiteProfile.open(SQLiteConfig(), tables=BUILTIN_TABLES) as profile: + config = SQLiteConfig(url=f"sqlite+aiosqlite:///{tmp_path / 'publication.db'}") + async with SQLiteProfile.open(config, tables=BUILTIN_TABLES) as profile: scopes = ScopeApplication(profile.database) source_scope = await scopes.create( ScopeDraft(title="Source", summary="Private working state", idempotency_key="source") @@ -49,7 +68,20 @@ async def scenario() -> None: ScopeDraft(title="Relay", summary="Relayed result", idempotency_key="relay") ) artifacts = ArtifactRepository((Report,)) - publications = ArtifactPublicationApplication(profile.database, artifacts, scopes) + publications = ( + ArtifactPublicationApplication( + profile.database, + artifacts, + scopes, + experience_index=NoExperienceIndex(), + ), + ArtifactPublicationApplication( + profile.database, + artifacts, + scopes, + experience_index=NoExperienceIndex(), + ), + ) async with profile.database.transaction() as connection: first = await artifacts.create( connection, @@ -63,7 +95,7 @@ async def scenario() -> None: target_scope_id=target_scope.scope_id, idempotency_key="accepted-report", ) - results = await asyncio.gather(*(publications.publish(request) for _ in range(8))) + results = await asyncio.gather(*(publications[index % 2].publish(request) for index in range(8))) published = results[0] assert all(result == published for result in results) @@ -81,7 +113,7 @@ async def scenario() -> None: assert copied.lineage.publication_source == request.source assert copied.lineage.publication_digest == published.content_digest - relayed = await publications.publish( + relayed = await publications[0].publish( ArtifactPublicationRequest( source=published.target, target_scope_id=relay_scope.scope_id, @@ -97,6 +129,95 @@ async def scenario() -> None: asyncio.run(scenario()) +def test_published_experience_is_searchable_in_target_scope_immediately() -> None: + async def scenario() -> None: + async with open_builtin_contexts(BuiltinConfig(database=SQLiteConfig())) as contexts: + source_scope = await contexts.scopes.create( + ScopeDraft(title="Source", summary="Private working state", idempotency_key="experience-source") + ) + target_scope = await contexts.scopes.create( + ScopeDraft(title="Target", summary="Accepted result", idempotency_key="experience-target") + ) + async with contexts.database.transaction() as connection: + source = await contexts.repositories.artifacts.create( + connection, + source_scope.scope_id, + "published-experience", + ExperienceDraft( + content=ExperienceContent( + situation="A publication crosses a Scope boundary.", + action="Copy the exact approved revision and its search projection.", + outcome="The target can recall the Experience immediately.", + lesson="Keep publication projection updates atomic.", + ) + ), + ) + + published = await contexts.publications.publish( + ArtifactPublicationRequest( + source=ArtifactAddress(scope_id=source_scope.scope_id, artifact=source.as_ref()), + target_scope_id=target_scope.scope_id, + idempotency_key="publish-experience", + ) + ) + hits = await contexts.search_experience(target_scope.scope_id, "projection updates atomic", 8) + + assert tuple(hit.artifact_ref for hit in hits) == (published.target.artifact,) + + asyncio.run(scenario()) + + +def test_experience_publication_rolls_back_when_projection_update_fails() -> None: + async def scenario() -> None: + async with open_builtin_contexts(BuiltinConfig(database=SQLiteConfig())) as contexts: + source_scope = await contexts.scopes.create( + ScopeDraft(title="Source", summary="Private working state", idempotency_key="rollback-source") + ) + target_scope = await contexts.scopes.create( + ScopeDraft(title="Target", summary="Accepted result", idempotency_key="rollback-target") + ) + async with contexts.database.transaction() as connection: + source = await contexts.repositories.artifacts.create( + connection, + source_scope.scope_id, + "source-experience", + ExperienceDraft( + content=ExperienceContent( + situation="The search projection is unavailable.", + action="Abort the publication transaction.", + outcome="No partial target lifecycle remains.", + lesson="Keep derived state in the publication transaction.", + ) + ), + ) + publications = ArtifactPublicationApplication( + contexts.database, + contexts.repositories.artifacts, + contexts.scopes, + experience_index=_FailingExperienceIndex(), + id_factory=lambda: "pub_rollback", + ) + request = ArtifactPublicationRequest( + source=ArtifactAddress(scope_id=source_scope.scope_id, artifact=source.as_ref()), + target_scope_id=target_scope.scope_id, + idempotency_key="rollback-publication", + ) + + with pytest.raises(_IndexUnavailableError): + await publications.publish(request) + + target = ArtifactAddress( + scope_id=target_scope.scope_id, + artifact=ArtifactRef(family="experience", artifact_id="pub_rollback", revision=1), + ) + assert await publications.get(target) is None + async with contexts.database.transaction() as connection: + with pytest.raises(RepositoryNotFoundError): + await contexts.repositories.artifacts.get(connection, target.scope_id, target.artifact) + + asyncio.run(scenario()) + + def test_publication_idempotency_key_cannot_select_another_revision() -> None: async def scenario() -> None: async with SQLiteProfile.open(SQLiteConfig(), tables=BUILTIN_TABLES) as profile: @@ -108,7 +229,12 @@ async def scenario() -> None: ScopeDraft(title="Target", summary="Accepted result", idempotency_key="target") ) artifacts = ArtifactRepository((Report,)) - publications = ArtifactPublicationApplication(profile.database, artifacts, scopes) + publications = ArtifactPublicationApplication( + profile.database, + artifacts, + scopes, + experience_index=NoExperienceIndex(), + ) async with profile.database.transaction() as connection: first = await artifacts.create( connection, @@ -162,6 +288,7 @@ async def scenario() -> None: contexts.database, contexts.repositories.artifacts, contexts.scopes, + experience_index=contexts.experience_index, id_factory=lambda: "pub_blocked", ) request = ArtifactPublicationRequest( From 94b388a1aeb4aee00fc92c1ae371915efc26bdd6 Mon Sep 17 00:00:00 2001 From: Chojan Shang <psiace@apache.org> Date: Thu, 3 Sep 2026 16:07:51 +0800 Subject: [PATCH 17/17] docs: use registered scope identifiers --- docs/en/docs/how-to/configure-pydantic-ai.md | 1 - .../en/docs/how-to/create-and-export-skill.md | 17 ++++++------ .../how-to/create-and-review-experience.md | 13 +++++----- .../how-to/ingest-text-files-with-opendal.md | 8 +++--- docs/en/docs/how-to/review-candidates.md | 26 +++++++++---------- docs/en/docs/how-to/trace-with-phoenix.md | 7 ++--- docs/en/docs/reference/http-api.md | 24 ++++++++--------- docs/en/docs/reference/interfaces.md | 18 +++++++------ docs/en/docs/tutorials/api-quickstart.md | 12 ++++++--- docs/zh/docs/how-to/configure-pydantic-ai.md | 1 - .../zh/docs/how-to/create-and-export-skill.md | 17 ++++++------ .../how-to/create-and-review-experience.md | 14 +++++----- .../how-to/ingest-text-files-with-opendal.md | 9 ++++--- docs/zh/docs/how-to/review-candidates.md | 25 +++++++++--------- docs/zh/docs/how-to/trace-with-phoenix.md | 6 ++--- docs/zh/docs/reference/http-api.md | 23 ++++++++-------- docs/zh/docs/reference/interfaces.md | 18 +++++++------ docs/zh/docs/tutorials/api-quickstart.md | 12 ++++++--- integrations/bub/README.md | 1 - .../codex/plugins/powercontext/README.md | 5 ++-- 20 files changed, 141 insertions(+), 116 deletions(-) diff --git a/docs/en/docs/how-to/configure-pydantic-ai.md b/docs/en/docs/how-to/configure-pydantic-ai.md index 09b8bb7c9..a60252809 100644 --- a/docs/en/docs/how-to/configure-pydantic-ai.md +++ b/docs/en/docs/how-to/configure-pydantic-ai.md @@ -53,7 +53,6 @@ agent = Agent("openai:gpt-5.2", toolsets=[PowerContextToolset()]) ```bash export POWERCONTEXT_PYDANTIC_AI_BASE_URL=http://127.0.0.1:8000 export POWERCONTEXT_PYDANTIC_AI_TOKEN=opaque-server-token -export POWERCONTEXT_PYDANTIC_AI_SCOPE_ID=project:example ``` | Variable | Default | Validation and behavior | diff --git a/docs/en/docs/how-to/create-and-export-skill.md b/docs/en/docs/how-to/create-and-export-skill.md index 7467b9ba7..47a1246ef 100644 --- a/docs/en/docs/how-to/create-and-export-skill.md +++ b/docs/en/docs/how-to/create-and-export-skill.md @@ -23,7 +23,8 @@ In another terminal: powercontext capabilities ``` -The output should report `Managed Skill generation: enabled`. Choose one provenance origin before generating: +The output should report `Managed Skill generation: enabled`. Set `POWERCONTEXT_SCOPE_ID` to an existing ID returned +by `create_scope`, then choose one provenance origin before generating: | Origin | Use it when | | --- | --- | @@ -37,7 +38,7 @@ From an approved Experience: ```bash powercontext skill generate \ - --scope-id project:example \ + --scope-id "$POWERCONTEXT_SCOPE_ID" \ --origin experience \ --artifact-ref experience/EXPERIENCE_ID@REVISION \ --reason "Turn the reviewed lesson into reusable instructions." @@ -47,7 +48,7 @@ From exact Sources instead: ```bash powercontext skill generate \ - --scope-id project:example \ + --scope-id "$POWERCONTEXT_SCOPE_ID" \ --origin source \ --source-ref content/SOURCE_ID \ --reason "Create a Skill from the approved operating procedure." @@ -61,7 +62,7 @@ approve, install, export, or execute the proposal. Inspect the returned Candidate: ```bash -powercontext candidate show --scope-id project:example CANDIDATE_ID +powercontext candidate show --scope-id "$POWERCONTEXT_SCOPE_ID" CANDIDATE_ID ``` Check its name, discovery description, complete instructions, validation checks, and exact lineage. Then approve the @@ -69,7 +70,7 @@ version you inspected: ```bash powercontext candidate approve \ - --scope-id project:example \ + --scope-id "$POWERCONTEXT_SCOPE_ID" \ --expected-version 1 \ CANDIDATE_ID ``` @@ -83,7 +84,7 @@ Use the Artifact ID and Revision from `result_artifact`: ```bash powercontext skill show \ - --scope-id project:example \ + --scope-id "$POWERCONTEXT_SCOPE_ID" \ --revision 1 \ SKILL_ID ``` @@ -100,7 +101,7 @@ must contain at most 1,024 characters and no angle brackets. The destination dir ```bash powercontext skill export \ --target codex \ - --scope-id project:example \ + --scope-id "$POWERCONTEXT_SCOPE_ID" \ --revision 1 \ --destination .agents/skills/backend-validation \ SKILL_ID @@ -125,7 +126,7 @@ Use the `usage` origin with the exact current Skill Revision and Sources that re ```bash powercontext skill generate \ - --scope-id project:example \ + --scope-id "$POWERCONTEXT_SCOPE_ID" \ --origin usage \ --target skill/SKILL_ID@REVISION \ --source-ref content/USAGE_SOURCE_ID \ diff --git a/docs/en/docs/how-to/create-and-review-experience.md b/docs/en/docs/how-to/create-and-review-experience.md index eaf971fcc..276b322ad 100644 --- a/docs/en/docs/how-to/create-and-review-experience.md +++ b/docs/en/docs/how-to/create-and-review-experience.md @@ -24,7 +24,8 @@ powercontext capabilities ``` The output should report `Experience generation: enabled`. You also need at least one exact Source or Artifact -reference in the target scope. Provider credentials come from the selected inference provider. +reference in the target scope. Set `POWERCONTEXT_SCOPE_ID` to an existing ID returned by `create_scope`. Provider +credentials come from the selected inference provider. ## 1. Generate a Candidate @@ -32,7 +33,7 @@ Pass the exact evidence that supports the proposed Experience: ```bash powercontext experience generate \ - --scope-id project:example \ + --scope-id "$POWERCONTEXT_SCOPE_ID" \ --source-ref content/SOURCE_ID \ --reason "Extract a reusable lesson from the completed task." ``` @@ -49,14 +50,14 @@ Generation does not approve or recall the proposal. For a pending result, copy its `candidate_id` and `version`, then inspect it: ```bash -powercontext candidate show --scope-id project:example CANDIDATE_ID +powercontext candidate show --scope-id "$POWERCONTEXT_SCOPE_ID" CANDIDATE_ID ``` Check all four Experience fields and their exact evidence. Approve only the version you inspected: ```bash powercontext candidate approve \ - --scope-id project:example \ + --scope-id "$POWERCONTEXT_SCOPE_ID" \ --expected-version 1 \ CANDIDATE_ID ``` @@ -69,7 +70,7 @@ follow [Review Candidates](review-candidates.md). Read the Candidate again and record `result_artifact`: ```bash -powercontext candidate show --scope-id project:example CANDIDATE_ID +powercontext candidate show --scope-id "$POWERCONTEXT_SCOPE_ID" CANDIDATE_ID ``` The approved current head is now eligible for same-scope `PreparedContext` recall. Eligibility does not guarantee @@ -82,7 +83,7 @@ Generate a replacement against the exact current Revision and cite the evidence ```bash powercontext experience generate \ - --scope-id project:example \ + --scope-id "$POWERCONTEXT_SCOPE_ID" \ --target experience/EXPERIENCE_ID@REVISION \ --source-ref content/NEW_SOURCE_ID \ --reason "Update the lesson with the verified follow-up result." diff --git a/docs/en/docs/how-to/ingest-text-files-with-opendal.md b/docs/en/docs/how-to/ingest-text-files-with-opendal.md index 8ffc3e29b..425e88022 100644 --- a/docs/en/docs/how-to/ingest-text-files-with-opendal.md +++ b/docs/en/docs/how-to/ingest-text-files-with-opendal.md @@ -23,7 +23,7 @@ uv tool install --python 3.12 --with-editable ".[client]" ./integrations/opendal Choose a stable `source_namespace` that distinguishes storage authorities. Do not put credentials in the namespace, Source payload, or checkpoint. If Server authentication is enabled, provide its bearer token through the -`POWERCONTEXT_TOKEN` environment variable. +`POWERCONTEXT_TOKEN` environment variable. Set `POWERCONTEXT_SCOPE_ID` to an existing ID returned by `create_scope`. ## Run a binding @@ -33,7 +33,7 @@ the `scope_id` determines which Scope owns accepted Sources: ```bash powercontext-connector-opendal \ --base-url http://127.0.0.1:8765 \ - --scope-id project:example \ + --scope-id "$POWERCONTEXT_SCOPE_ID" \ --binding-id project-docs \ --service fs \ --storage-option root=/absolute/path/to/project \ @@ -53,6 +53,8 @@ have durable receipts. Use cron, a Kubernetes Job, or another external scheduler Use the generic remote lifecycle when a deployment needs custom supervision or schedules multiple bindings: ```python +import os + from powercontext.client import PowerContextClient, RemoteConnectorWorker from powercontext.sources import ConnectorBinding, SourceDefinitionRegistry from powercontext_connector_opendal import ( @@ -67,7 +69,7 @@ connector = OpenDALTextFileConnector.from_service( storage_options={"root": "/absolute/path/to/project"}, ) binding = ConnectorBinding( - scope_id="project:example", + scope_id=os.environ["POWERCONTEXT_SCOPE_ID"], binding_id="project-docs", connector_name=connector.name, connector_version=connector.version, diff --git a/docs/en/docs/how-to/review-candidates.md b/docs/en/docs/how-to/review-candidates.md index b3feda397..f73868685 100644 --- a/docs/en/docs/how-to/review-candidates.md +++ b/docs/en/docs/how-to/review-candidates.md @@ -16,20 +16,20 @@ Start the Server and confirm that it is ready: powercontext ready ``` -You need the `scope_id` that contains the Candidate. This guide starts after an Experience or Skill operation has -created a pending Candidate. +Set `POWERCONTEXT_SCOPE_ID` to the existing Scope ID that contains the Candidate. This guide starts after an +Experience or Skill operation has created a pending Candidate. ## 1. List pending Candidates ```bash -powercontext candidate list --scope-id project:example +powercontext candidate list --scope-id "$POWERCONTEXT_SCOPE_ID" ``` The default Review Inbox contains only `pending` Candidate heads. Filter it by family when needed: ```bash -powercontext candidate list --scope-id project:example --family experience -powercontext candidate list --scope-id project:example --family skill +powercontext candidate list --scope-id "$POWERCONTEXT_SCOPE_ID" --family experience +powercontext candidate list --scope-id "$POWERCONTEXT_SCOPE_ID" --family skill ``` The response contains each `candidate_id` and current `version`. If it returns `next_cursor`, pass that value through @@ -38,7 +38,7 @@ The response contains each `candidate_id` and current `version`. If it returns ` ## 2. Inspect one Candidate ```bash -powercontext candidate show --scope-id project:example CANDIDATE_ID +powercontext candidate show --scope-id "$POWERCONTEXT_SCOPE_ID" CANDIDATE_ID ``` Before deciding, inspect: @@ -60,7 +60,7 @@ Use the `version` you inspected as `--expected-version`. ```bash powercontext candidate approve \ - --scope-id project:example \ + --scope-id "$POWERCONTEXT_SCOPE_ID" \ --expected-version 1 \ CANDIDATE_ID ``` @@ -72,7 +72,7 @@ Candidate approved in one transaction. The Candidate is then terminal. ```bash powercontext candidate reject \ - --scope-id project:example \ + --scope-id "$POWERCONTEXT_SCOPE_ID" \ --expected-version 1 \ --reason "The evidence does not support the proposed lesson." \ CANDIDATE_ID @@ -88,7 +88,7 @@ version: ```bash powercontext candidate revise experience \ - --scope-id project:example \ + --scope-id "$POWERCONTEXT_SCOPE_ID" \ --expected-version 1 \ --situation "Only one storage backend was tested." \ --action "Run the same acceptance scenario on both backends." \ @@ -107,7 +107,7 @@ Repeat `--validation` for each check: ```bash powercontext candidate revise skill \ - --scope-id project:example \ + --scope-id "$POWERCONTEXT_SCOPE_ID" \ --expected-version 1 \ --name backend-validation \ --description "Validate storage backends consistently." \ @@ -126,15 +126,15 @@ automatically. Read the Candidate again: ```bash -powercontext candidate show --scope-id project:example CANDIDATE_ID +powercontext candidate show --scope-id "$POWERCONTEXT_SCOPE_ID" CANDIDATE_ID ``` For an approved Candidate, record the exact `result_artifact`. For a rejected Candidate, confirm `decision_reason`. The default Inbox no longer lists either terminal state; audit them explicitly when needed: ```bash -powercontext candidate list --scope-id project:example --status approved -powercontext candidate list --scope-id project:example --status rejected +powercontext candidate list --scope-id "$POWERCONTEXT_SCOPE_ID" --status approved +powercontext candidate list --scope-id "$POWERCONTEXT_SCOPE_ID" --status rejected ``` If a write reports that the Candidate version is stale, show the Candidate again and review the new version. Do not diff --git a/docs/en/docs/how-to/trace-with-phoenix.md b/docs/en/docs/how-to/trace-with-phoenix.md index fde7b96db..3964827f3 100644 --- a/docs/en/docs/how-to/trace-with-phoenix.md +++ b/docs/en/docs/how-to/trace-with-phoenix.md @@ -49,18 +49,19 @@ authentication. Set the provider credentials your generation model needs; PowerC ## Trigger one inference request -Capture a Source, then convert it into Memory: +Set `POWERCONTEXT_SCOPE_ID` to an existing ID returned by `create_scope`, capture a Source, then convert it into +Memory: ```bash curl -X POST http://localhost:8000/v1/sources/content \ -H 'content-type: application/json' \ - -d '{"scope_id":"project:demo","source_id":"task-1","content":"I always book aisle seats."}' + -d "{\"scope_id\":\"${POWERCONTEXT_SCOPE_ID}\",\"source_id\":\"task-1\",\"content\":\"I always book aisle seats.\"}" ``` ```bash curl -X POST http://localhost:8000/v1/memory/flush \ -H 'content-type: application/json' \ - -d '{"scope_id":"project:demo"}' + -d "{\"scope_id\":\"${POWERCONTEXT_SCOPE_ID}\"}" ``` Memory extraction runs during the flush, not during capture. diff --git a/docs/en/docs/reference/http-api.md b/docs/en/docs/reference/http-api.md index ddc3598a8..494b18a50 100644 --- a/docs/en/docs/reference/http-api.md +++ b/docs/en/docs/reference/http-api.md @@ -56,8 +56,8 @@ curl --fail \ ## Store and search one Memory -Choose a stable `scope_id` for the project or tenant. Reuse it across sessions; a session ID is not a durable project -identity. +Set `POWERCONTEXT_SCOPE_ID` to an existing ID returned by `create_scope`. Reuse that Scope across sessions; a Session +ID is not a durable project identity. Store one already-curated Memory entry: @@ -66,11 +66,11 @@ curl --fail \ --request POST \ --header 'Content-Type: application/json' \ --header "$POWERCONTEXT_AUTH_HEADER" \ - --data '{ - "scope_id": "project:example", - "kind": "decision", - "text": "Keep the public API asynchronous." - }' \ + --data "{ + \"scope_id\": \"${POWERCONTEXT_SCOPE_ID}\", + \"kind\": \"decision\", + \"text\": \"Keep the public API asynchronous.\" + }" \ "$POWERCONTEXT_URL/v1/memory/remember" ``` @@ -84,11 +84,11 @@ curl --fail \ --request POST \ --header 'Content-Type: application/json' \ --header "$POWERCONTEXT_AUTH_HEADER" \ - --data '{ - "scope_id": "project:example", - "query": "public API", - "limit": 5 - }' \ + --data "{ + \"scope_id\": \"${POWERCONTEXT_SCOPE_ID}\", + \"query\": \"public API\", + \"limit\": 5 + }" \ "$POWERCONTEXT_URL/v1/memory/search" ``` diff --git a/docs/en/docs/reference/interfaces.md b/docs/en/docs/reference/interfaces.md index 330b34339..0c76ae98f 100644 --- a/docs/en/docs/reference/interfaces.md +++ b/docs/en/docs/reference/interfaces.md @@ -128,6 +128,8 @@ boundary flushing fail open; explicit durable writes require interactive confirm ## CLI +Set `POWERCONTEXT_SCOPE_ID` to an existing ID returned by `create_scope` before running scoped content commands. + ```text powercontext setup <host> --source oceanbase/powercontext --ref master powercontext setup select --host codex --host dsh --source oceanbase/powercontext --ref master @@ -141,16 +143,16 @@ powercontext server run powercontext server run --env-file .env powercontext ready powercontext capabilities -powercontext experience generate --scope-id project:example --source-ref content/SOURCE_ID -powercontext skill generate --scope-id project:example --origin experience \ +powercontext experience generate --scope-id "$POWERCONTEXT_SCOPE_ID" --source-ref content/SOURCE_ID +powercontext skill generate --scope-id "$POWERCONTEXT_SCOPE_ID" --origin experience \ --artifact-ref experience/EXPERIENCE_ID@REVISION -powercontext skill show --scope-id project:example --revision 1 SKILL_ID -powercontext skill export --target codex --scope-id project:example --revision 1 \ +powercontext skill show --scope-id "$POWERCONTEXT_SCOPE_ID" --revision 1 SKILL_ID +powercontext skill export --target codex --scope-id "$POWERCONTEXT_SCOPE_ID" --revision 1 \ --destination .agents/skills/example-skill SKILL_ID -powercontext external-skill scan --scope-id project:example -powercontext external-skill list --scope-id project:example -powercontext external-skill resolve --scope-id project:example --fingerprint SHA256 EXTERNAL_SKILL_ID -powercontext external-skill import --scope-id project:example --fingerprint SHA256 \ +powercontext external-skill scan --scope-id "$POWERCONTEXT_SCOPE_ID" +powercontext external-skill list --scope-id "$POWERCONTEXT_SCOPE_ID" +powercontext external-skill resolve --scope-id "$POWERCONTEXT_SCOPE_ID" --fingerprint SHA256 EXTERNAL_SKILL_ID +powercontext external-skill import --scope-id "$POWERCONTEXT_SCOPE_ID" --fingerprint SHA256 \ --mode import EXTERNAL_SKILL_ID ``` diff --git a/docs/en/docs/tutorials/api-quickstart.md b/docs/en/docs/tutorials/api-quickstart.md index 604deb06a..1a1f913f0 100644 --- a/docs/en/docs/tutorials/api-quickstart.md +++ b/docs/en/docs/tutorials/api-quickstart.md @@ -42,11 +42,17 @@ Experience and Skill proposals. ## 2. Choose the application boundary -Set a stable scope for one project or tenant: +Create a stable Scope for one project or tenant and keep the returned Server-owned ID: ```bash export POWERCONTEXT_URL=http://127.0.0.1:8000 -export POWERCONTEXT_SCOPE=project:billing-assistant +export POWERCONTEXT_SCOPE="$( + curl --fail --silent --show-error \ + --header 'Content-Type: application/json' \ + --data '{"title":"Billing assistant","summary":"Billing application context","idempotency_key":"billing-assistant"}' \ + "$POWERCONTEXT_URL/v1/scopes" \ + | python -c 'import json, sys; print(json.load(sys.stdin)["scope_id"])' +)" ``` Your trusted application or Gateway must choose and authorize `scope_id`. It is a data partition key, not an access @@ -76,7 +82,7 @@ from urllib.request import Request, urlopen BASE_URL = os.environ.get("POWERCONTEXT_URL", "http://127.0.0.1:8000").rstrip("/") -SCOPE_ID = os.environ.get("POWERCONTEXT_SCOPE", "project:billing-assistant") +SCOPE_ID = os.environ["POWERCONTEXT_SCOPE"] TOKEN = os.environ.get("POWERCONTEXT_TOKEN") diff --git a/docs/zh/docs/how-to/configure-pydantic-ai.md b/docs/zh/docs/how-to/configure-pydantic-ai.md index 6daa57685..2d27035f4 100644 --- a/docs/zh/docs/how-to/configure-pydantic-ai.md +++ b/docs/zh/docs/how-to/configure-pydantic-ai.md @@ -51,7 +51,6 @@ agent = Agent("openai:gpt-5.2", toolsets=[PowerContextToolset()]) ```bash export POWERCONTEXT_PYDANTIC_AI_BASE_URL=http://127.0.0.1:8000 export POWERCONTEXT_PYDANTIC_AI_TOKEN=opaque-server-token -export POWERCONTEXT_PYDANTIC_AI_SCOPE_ID=project:example ``` | 变量 | 默认值 | 校验与行为 | diff --git a/docs/zh/docs/how-to/create-and-export-skill.md b/docs/zh/docs/how-to/create-and-export-skill.md index d121b4cab..56d3480ca 100644 --- a/docs/zh/docs/how-to/create-and-export-skill.md +++ b/docs/zh/docs/how-to/create-and-export-skill.md @@ -23,7 +23,8 @@ powercontext server run powercontext capabilities ``` -输出应包含 `Managed Skill generation: enabled`。生成前选择一种 provenance origin： +输出应包含 `Managed Skill generation: enabled`。将 `POWERCONTEXT_SCOPE_ID` 设置为 `create_scope` 返回的已有 +ID，然后选择一种 provenance origin： | Origin | 适用情况 | | --- | --- | @@ -37,7 +38,7 @@ powercontext capabilities ```bash powercontext skill generate \ - --scope-id project:example \ + --scope-id "$POWERCONTEXT_SCOPE_ID" \ --origin experience \ --artifact-ref experience/EXPERIENCE_ID@REVISION \ --reason "把经过审核的经验转为可复用指令。" @@ -47,7 +48,7 @@ powercontext skill generate \ ```bash powercontext skill generate \ - --scope-id project:example \ + --scope-id "$POWERCONTEXT_SCOPE_ID" \ --origin source \ --source-ref content/SOURCE_ID \ --reason "根据已批准的操作规程创建 Skill。" @@ -61,14 +62,14 @@ powercontext skill generate \ 检查返回的 Candidate： ```bash -powercontext candidate show --scope-id project:example CANDIDATE_ID +powercontext candidate show --scope-id "$POWERCONTEXT_SCOPE_ID" CANDIDATE_ID ``` 检查名称、用于发现的描述、完整 instructions、validation checks 和精确 lineage。然后批准你检查过的 version： ```bash powercontext candidate approve \ - --scope-id project:example \ + --scope-id "$POWERCONTEXT_SCOPE_ID" \ --expected-version 1 \ CANDIDATE_ID ``` @@ -82,7 +83,7 @@ powercontext candidate approve \ ```bash powercontext skill show \ - --scope-id project:example \ + --scope-id "$POWERCONTEXT_SCOPE_ID" \ --revision 1 \ SKILL_ID ``` @@ -98,7 +99,7 @@ exact read 和显式导出使用。 ```bash powercontext skill export \ --target codex \ - --scope-id project:example \ + --scope-id "$POWERCONTEXT_SCOPE_ID" \ --revision 1 \ --destination .agents/skills/backend-validation \ SKILL_ID @@ -123,7 +124,7 @@ Codex 会自动检测导出的代码库级 Skill。如果没有出现，再重 ```bash powercontext skill generate \ - --scope-id project:example \ + --scope-id "$POWERCONTEXT_SCOPE_ID" \ --origin usage \ --target skill/SKILL_ID@REVISION \ --source-ref content/USAGE_SOURCE_ID \ diff --git a/docs/zh/docs/how-to/create-and-review-experience.md b/docs/zh/docs/how-to/create-and-review-experience.md index f05b90d14..cb6de3c74 100644 --- a/docs/zh/docs/how-to/create-and-review-experience.md +++ b/docs/zh/docs/how-to/create-and-review-experience.md @@ -23,8 +23,8 @@ powercontext server run powercontext capabilities ``` -输出应包含 `Experience generation: enabled`。目标 scope 中还需要至少一个精确 Source 或 Artifact 引用。Provider -凭据由所选 inference provider 读取。 +输出应包含 `Experience generation: enabled`。目标 Scope 中还需要至少一个精确 Source 或 Artifact 引用。将 +`POWERCONTEXT_SCOPE_ID` 设置为 `create_scope` 返回的已有 ID。Provider 凭据由所选 inference provider 读取。 ## 1. 生成 Candidate @@ -32,7 +32,7 @@ powercontext capabilities ```bash powercontext experience generate \ - --scope-id project:example \ + --scope-id "$POWERCONTEXT_SCOPE_ID" \ --source-ref content/SOURCE_ID \ --reason "从已完成任务中提取可复用经验。" ``` @@ -49,14 +49,14 @@ Generation 不会批准 proposal，也不会让它进入召回。 收到 pending 结果后，复制其中的 `candidate_id` 和 `version`，然后检查内容： ```bash -powercontext candidate show --scope-id project:example CANDIDATE_ID +powercontext candidate show --scope-id "$POWERCONTEXT_SCOPE_ID" CANDIDATE_ID ``` 检查全部四个 Experience 字段及其精确证据。只批准你已经检查过的 version： ```bash powercontext candidate approve \ - --scope-id project:example \ + --scope-id "$POWERCONTEXT_SCOPE_ID" \ --expected-version 1 \ CANDIDATE_ID ``` @@ -69,7 +69,7 @@ powercontext candidate approve \ 再次读取 Candidate，并记录 `result_artifact`： ```bash -powercontext candidate show --scope-id project:example CANDIDATE_ID +powercontext candidate show --scope-id "$POWERCONTEXT_SCOPE_ID" CANDIDATE_ID ``` Approved current head 现在可以参与同 scope 的 `PreparedContext` 召回。Runtime 仍会根据 query 和共享输出预算选择内容， @@ -81,7 +81,7 @@ Approved current head 现在可以参与同 scope 的 `PreparedContext` 召回 ```bash powercontext experience generate \ - --scope-id project:example \ + --scope-id "$POWERCONTEXT_SCOPE_ID" \ --target experience/EXPERIENCE_ID@REVISION \ --source-ref content/NEW_SOURCE_ID \ --reason "根据已经验证的后续结果更新经验。" diff --git a/docs/zh/docs/how-to/ingest-text-files-with-opendal.md b/docs/zh/docs/how-to/ingest-text-files-with-opendal.md index b78dfbd0e..d0aa327d7 100644 --- a/docs/zh/docs/how-to/ingest-text-files-with-opendal.md +++ b/docs/zh/docs/how-to/ingest-text-files-with-opendal.md @@ -22,7 +22,8 @@ uv tool install --python 3.12 --with-editable ".[client]" ./integrations/opendal ``` 选择稳定的 `source_namespace` 来区分不同 storage authority。不要把 credential 写进 namespace、Source payload 或 -checkpoint。Server 启用 authentication 时，通过 `POWERCONTEXT_TOKEN` 环境变量提供 bearer token。 +checkpoint。Server 启用 authentication 时，通过 `POWERCONTEXT_TOKEN` 环境变量提供 bearer token。将 +`POWERCONTEXT_SCOPE_ID` 设置为 `create_scope` 返回的已有 ID。 ## 运行一个 binding @@ -32,7 +33,7 @@ checkpoint。Server 启用 authentication 时，通过 `POWERCONTEXT_TOKEN` 环 ```bash powercontext-connector-opendal \ --base-url http://127.0.0.1:8765 \ - --scope-id project:example \ + --scope-id "$POWERCONTEXT_SCOPE_ID" \ --binding-id project-docs \ --service fs \ --storage-option root=/absolute/path/to/project \ @@ -52,6 +53,8 @@ cron、Kubernetes Job 或其他外部 scheduler 周期执行该命令。 需要自定义进程监管或多 binding 调度时，可直接使用通用远程 lifecycle： ```python +import os + from powercontext.client import PowerContextClient, RemoteConnectorWorker from powercontext.sources import ConnectorBinding, SourceDefinitionRegistry from powercontext_connector_opendal import ( @@ -66,7 +69,7 @@ connector = OpenDALTextFileConnector.from_service( storage_options={"root": "/absolute/path/to/project"}, ) binding = ConnectorBinding( - scope_id="project:example", + scope_id=os.environ["POWERCONTEXT_SCOPE_ID"], binding_id="project-docs", connector_name=connector.name, connector_version=connector.version, diff --git a/docs/zh/docs/how-to/review-candidates.md b/docs/zh/docs/how-to/review-candidates.md index 6d1bc09af..c5e02328e 100644 --- a/docs/zh/docs/how-to/review-candidates.md +++ b/docs/zh/docs/how-to/review-candidates.md @@ -16,19 +16,20 @@ Revision；拒绝会关闭 Candidate，但不会写入 Artifact。 powercontext ready ``` -你需要知道 Candidate 所在的 `scope_id`。本指南从 Experience 或 Skill 操作已经创建 pending Candidate 后开始。 +将 `POWERCONTEXT_SCOPE_ID` 设置为 Candidate 所在的已有 Scope ID。本指南从 Experience 或 Skill 操作已经创建 +pending Candidate 后开始。 ## 1. 列出待审核 Candidate ```bash -powercontext candidate list --scope-id project:example +powercontext candidate list --scope-id "$POWERCONTEXT_SCOPE_ID" ``` 默认 Review Inbox 只列出 `pending` Candidate head。需要时可以按 family 筛选： ```bash -powercontext candidate list --scope-id project:example --family experience -powercontext candidate list --scope-id project:example --family skill +powercontext candidate list --scope-id "$POWERCONTEXT_SCOPE_ID" --family experience +powercontext candidate list --scope-id "$POWERCONTEXT_SCOPE_ID" --family skill ``` 响应包含每个 Candidate 的 `candidate_id` 和当前 `version`。如果响应返回 `next_cursor`，通过 `--cursor` 读取下一页。 @@ -37,7 +38,7 @@ powercontext candidate list --scope-id project:example --family skill ## 2. 检查一个 Candidate ```bash -powercontext candidate show --scope-id project:example CANDIDATE_ID +powercontext candidate show --scope-id "$POWERCONTEXT_SCOPE_ID" CANDIDATE_ID ``` 做决定前，检查以下内容： @@ -58,7 +59,7 @@ powercontext candidate show --scope-id project:example CANDIDATE_ID ```bash powercontext candidate approve \ - --scope-id project:example \ + --scope-id "$POWERCONTEXT_SCOPE_ID" \ --expected-version 1 \ CANDIDATE_ID ``` @@ -70,7 +71,7 @@ powercontext candidate approve \ ```bash powercontext candidate reject \ - --scope-id project:example \ + --scope-id "$POWERCONTEXT_SCOPE_ID" \ --expected-version 1 \ --reason "证据不能支持提议的经验结论。" \ CANDIDATE_ID @@ -85,7 +86,7 @@ powercontext candidate reject \ ```bash powercontext candidate revise experience \ - --scope-id project:example \ + --scope-id "$POWERCONTEXT_SCOPE_ID" \ --expected-version 1 \ --situation "只测试了一个存储后端。" \ --action "在两个后端运行相同的验收场景。" \ @@ -104,7 +105,7 @@ powercontext candidate revise experience \ ```bash powercontext candidate revise skill \ - --scope-id project:example \ + --scope-id "$POWERCONTEXT_SCOPE_ID" \ --expected-version 1 \ --name backend-validation \ --description "以一致方式验证存储后端。" \ @@ -123,15 +124,15 @@ powercontext candidate revise skill \ 再次读取 Candidate： ```bash -powercontext candidate show --scope-id project:example CANDIDATE_ID +powercontext candidate show --scope-id "$POWERCONTEXT_SCOPE_ID" CANDIDATE_ID ``` Candidate 已批准时，记录精确的 `result_artifact`；Candidate 已拒绝时，确认 `decision_reason`。默认 Inbox 不再列出 这两种终态，需要审计时应显式查询： ```bash -powercontext candidate list --scope-id project:example --status approved -powercontext candidate list --scope-id project:example --status rejected +powercontext candidate list --scope-id "$POWERCONTEXT_SCOPE_ID" --status approved +powercontext candidate list --scope-id "$POWERCONTEXT_SCOPE_ID" --status rejected ``` 如果写操作报告 Candidate 版本过期，请重新显示 Candidate 并审核新版本。不要在未检查替代内容时直接修改 diff --git a/docs/zh/docs/how-to/trace-with-phoenix.md b/docs/zh/docs/how-to/trace-with-phoenix.md index d306a341b..9884e5410 100644 --- a/docs/zh/docs/how-to/trace-with-phoenix.md +++ b/docs/zh/docs/how-to/trace-with-phoenix.md @@ -47,18 +47,18 @@ OpenTelemetry SDK 会在 `OTEL_EXPORTER_OTLP_ENDPOINT` 后追加 `/v1/traces`， ## 触发一次推理请求 -先捕获一个 Source，再把它转成 Memory： +将 `POWERCONTEXT_SCOPE_ID` 设置为 `create_scope` 返回的已有 ID，先捕获一个 Source，再把它转成 Memory： ```bash curl -X POST http://localhost:8000/v1/sources/content \ -H 'content-type: application/json' \ - -d '{"scope_id":"project:demo","source_id":"task-1","content":"I always book aisle seats."}' + -d "{\"scope_id\":\"${POWERCONTEXT_SCOPE_ID}\",\"source_id\":\"task-1\",\"content\":\"I always book aisle seats.\"}" ``` ```bash curl -X POST http://localhost:8000/v1/memory/flush \ -H 'content-type: application/json' \ - -d '{"scope_id":"project:demo"}' + -d "{\"scope_id\":\"${POWERCONTEXT_SCOPE_ID}\"}" ``` Memory extraction 发生在 flush 阶段，而不是捕获阶段。 diff --git a/docs/zh/docs/reference/http-api.md b/docs/zh/docs/reference/http-api.md index 232491a77..33e2edc17 100644 --- a/docs/zh/docs/reference/http-api.md +++ b/docs/zh/docs/reference/http-api.md @@ -50,7 +50,8 @@ curl --fail \ ## 保存并搜索一条 Memory -为项目或租户选择稳定的 `scope_id`，并在不同会话中复用。会话 ID 不是持久的项目身份。 +将 `POWERCONTEXT_SCOPE_ID` 设置为 `create_scope` 返回的已有 ID，并在不同会话中复用。会话 ID 不是持久的 +项目身份。 保存一条已经整理好的 Memory： @@ -59,11 +60,11 @@ curl --fail \ --request POST \ --header 'Content-Type: application/json' \ --header "$POWERCONTEXT_AUTH_HEADER" \ - --data '{ - "scope_id": "project:example", - "kind": "decision", - "text": "公开 API 保持异步。" - }' \ + --data "{ + \"scope_id\": \"${POWERCONTEXT_SCOPE_ID}\", + \"kind\": \"decision\", + \"text\": \"公开 API 保持异步。\" + }" \ "$POWERCONTEXT_URL/v1/memory/remember" ``` @@ -76,11 +77,11 @@ curl --fail \ --request POST \ --header 'Content-Type: application/json' \ --header "$POWERCONTEXT_AUTH_HEADER" \ - --data '{ - "scope_id": "project:example", - "query": "公开 API", - "limit": 5 - }' \ + --data "{ + \"scope_id\": \"${POWERCONTEXT_SCOPE_ID}\", + \"query\": \"公开 API\", + \"limit\": 5 + }" \ "$POWERCONTEXT_URL/v1/memory/search" ``` diff --git a/docs/zh/docs/reference/interfaces.md b/docs/zh/docs/reference/interfaces.md index 7ff1611e8..af96e4a2c 100644 --- a/docs/zh/docs/reference/interfaces.md +++ b/docs/zh/docs/reference/interfaces.md @@ -114,6 +114,8 @@ Pi transcript。召回、采集和边界 flush 都会正常降级；显式持久 ## CLI +运行带 Scope 的内容命令前，将 `POWERCONTEXT_SCOPE_ID` 设置为 `create_scope` 返回的已有 ID。 + ```text powercontext setup <host> --source oceanbase/powercontext --ref master powercontext setup select --host codex --host dsh --source oceanbase/powercontext --ref master @@ -127,16 +129,16 @@ powercontext server run powercontext server run --env-file .env powercontext ready powercontext capabilities -powercontext experience generate --scope-id project:example --source-ref content/SOURCE_ID -powercontext skill generate --scope-id project:example --origin experience \ +powercontext experience generate --scope-id "$POWERCONTEXT_SCOPE_ID" --source-ref content/SOURCE_ID +powercontext skill generate --scope-id "$POWERCONTEXT_SCOPE_ID" --origin experience \ --artifact-ref experience/EXPERIENCE_ID@REVISION -powercontext skill show --scope-id project:example --revision 1 SKILL_ID -powercontext skill export --target codex --scope-id project:example --revision 1 \ +powercontext skill show --scope-id "$POWERCONTEXT_SCOPE_ID" --revision 1 SKILL_ID +powercontext skill export --target codex --scope-id "$POWERCONTEXT_SCOPE_ID" --revision 1 \ --destination .agents/skills/example-skill SKILL_ID -powercontext external-skill scan --scope-id project:example -powercontext external-skill list --scope-id project:example -powercontext external-skill resolve --scope-id project:example --fingerprint SHA256 EXTERNAL_SKILL_ID -powercontext external-skill import --scope-id project:example --fingerprint SHA256 \ +powercontext external-skill scan --scope-id "$POWERCONTEXT_SCOPE_ID" +powercontext external-skill list --scope-id "$POWERCONTEXT_SCOPE_ID" +powercontext external-skill resolve --scope-id "$POWERCONTEXT_SCOPE_ID" --fingerprint SHA256 EXTERNAL_SKILL_ID +powercontext external-skill import --scope-id "$POWERCONTEXT_SCOPE_ID" --fingerprint SHA256 \ --mode import EXTERNAL_SKILL_ID ``` diff --git a/docs/zh/docs/tutorials/api-quickstart.md b/docs/zh/docs/tutorials/api-quickstart.md index f179d4a00..8916cdccb 100644 --- a/docs/zh/docs/tutorials/api-quickstart.md +++ b/docs/zh/docs/tutorials/api-quickstart.md @@ -39,11 +39,17 @@ curl --fail --silent --show-error http://127.0.0.1:8000/health/live ## 2. 确定应用边界 -为一个项目或租户设置稳定的 scope： +为一个项目或租户创建稳定 Scope，并保留 Server 返回的 ID： ```bash export POWERCONTEXT_URL=http://127.0.0.1:8000 -export POWERCONTEXT_SCOPE=project:billing-assistant +export POWERCONTEXT_SCOPE="$( + curl --fail --silent --show-error \ + --header 'Content-Type: application/json' \ + --data '{"title":"Billing assistant","summary":"Billing application context","idempotency_key":"billing-assistant"}' \ + "$POWERCONTEXT_URL/v1/scopes" \ + | python -c 'import json, sys; print(json.load(sys.stdin)["scope_id"])' +)" ``` 必须由可信应用或 Gateway 选择并授权 `scope_id`。它是数据分区键，不是访问控制检查。不要允许模型输出选择其他 @@ -72,7 +78,7 @@ from urllib.request import Request, urlopen BASE_URL = os.environ.get("POWERCONTEXT_URL", "http://127.0.0.1:8000").rstrip("/") -SCOPE_ID = os.environ.get("POWERCONTEXT_SCOPE", "project:billing-assistant") +SCOPE_ID = os.environ["POWERCONTEXT_SCOPE"] TOKEN = os.environ.get("POWERCONTEXT_TOKEN") diff --git a/integrations/bub/README.md b/integrations/bub/README.md index 5fd6f0376..d88788dfa 100644 --- a/integrations/bub/README.md +++ b/integrations/bub/README.md @@ -20,7 +20,6 @@ configuration file: ```yaml powercontext: base_url: http://127.0.0.1:8000 - scope_id: project:example capture_events: true capture_checkpoint_every: 5 ``` diff --git a/integrations/codex/plugins/powercontext/README.md b/integrations/codex/plugins/powercontext/README.md index 9bce5d501..787f2a6c5 100644 --- a/integrations/codex/plugins/powercontext/README.md +++ b/integrations/codex/plugins/powercontext/README.md @@ -23,14 +23,15 @@ Acknowledgements and historical authorization notes never grant Codex new execution authority, and the prompt hook does not infer completion from Stop or SessionEnd. -Managed Skills use a separate, explicit handoff. A reviewer approves the exact +Managed Skills use a separate, explicit handoff. Set `POWERCONTEXT_SCOPE_ID` to the existing Scope ID that owns the +approved Revision. A reviewer approves the exact Candidate through HTTP or the Client CLI, then the user exports that immutable Skill Revision into a Codex Skill directory: ```bash powercontext skill export \ --target codex \ - --scope-id project:example \ + --scope-id "$POWERCONTEXT_SCOPE_ID" \ --revision 1 \ --destination .agents/skills/example-skill \ SKILL_ID