From d4b2aaea29271de64a6dbcabf2f46444e5906ab2 Mon Sep 17 00:00:00 2001 From: qyq316 <19606363088@163.com> Date: Mon, 12 Oct 2026 11:53:13 +0800 Subject: [PATCH 01/11] docs(rfc): define source-backed working notes --- .../rfcs/1790_source_backed_working_notes.md | 60 +++++++++++++++++++ .../rfcs/1790_source_backed_working_notes.md | 53 ++++++++++++++++ 2 files changed, 113 insertions(+) create mode 100644 docs/en/rfcs/1790_source_backed_working_notes.md create mode 100644 docs/zh/rfcs/1790_source_backed_working_notes.md diff --git a/docs/en/rfcs/1790_source_backed_working_notes.md b/docs/en/rfcs/1790_source_backed_working_notes.md new file mode 100644 index 0000000000..2488d9b7e1 --- /dev/null +++ b/docs/en/rfcs/1790_source_backed_working_notes.md @@ -0,0 +1,60 @@ +# Source-backed Working Notes + +- Proposal Name: `source_backed_working_notes` +- Tracking Issue: [oceanbase/powercontext#1790](https://github.com/oceanbase/powercontext/issues/1790) +- Status: implementation decision + +## Decision + +PowerContext uses a Source-kind-only design for short-lived working notes. It does not add a durable `notes` Artifact +family. A working note is captured as a `ContentSource` marked by a server-owned field, with descriptive kind and +session metadata. The Source remains addressable by its exact `(scope_id, source_type, source_id)` identity. + +This is distinct from a Memory entry whose `kind` is also `working_note`: the latter is an explicit Memory write and is +eligible for Memory lifecycle and retrieval. A captured Working Note is evidence only until a caller explicitly uses it +in a domain operation. + +Hosts capture one through `POST /v1/sources/working-notes`, the generated Python Client's `capture_working_note`, or the +same MCP tool when exposed. The request requires a caller-stable `source_id`, host `session_id`, content, and one of +`inspection`, `abandoned_approach`, `validation`, `unresolved`, or `host_context`. Replaying an identity with different +content remains a Source conflict. A caller may also set a timezone-aware `expires_at` in the future. An exact replay +of an accepted capture returns its original receipt even after expiry; expiry does not weaken capture idempotency. + +Working Note classification is a server-owned `ContentSource` field. The `metadata.kind=working_note` value is retained +as descriptive metadata but is not authoritative by itself. Generic content capture rejects that reserved kind and +cannot set the server-owned field. Existing Sources that only happen to carry this metadata value remain ordinary +Sources after upgrade and retain their previous generation behavior. + +## Processing boundary + +Working Notes are excluded from automatic Source-window generation. They must not be promoted into Memory, Topic Memory, +Experience, or another generated artifact merely because they were captured. Explicit consumers may opt in to the exact +Source reference. Handoff evidence resolution opts in because a cited Working Note is still inspectable evidence. + +The content is untrusted historical material. It is not an instruction, Skill, prompt policy, or executable tool input. + +## Retention and access + +Working Notes inherit Scope Source authorization. `session_id` identifies the originating host/session for grouping and +future cleanup; it is not an additional authorization boundary. When `expires_at` is omitted, the note remains active +until a future explicit lifecycle action. After the timestamp, new consumers, including Handoff evidence resolution, +must treat the note as unavailable. + +Expiry is logical: it does not delete or rewrite the immutable Source, which remains readable through the supported +Source audit path. Physical purge, session-end cleanup, legal hold, and cross-scope export are separate lifecycle work +and are not implemented by this decision. + +An exact Source reference remains the evidence identity when a Handoff cites a note. A later cleanup operation must not +silently resolve that citation to different content. + +## Promotion + +Promotion is disabled in the initial implementation. A future explicit promotion operation must submit the exact +Source reference and pass the owning domain's normal validation. No extractor may infer a durable `fact`, `decision`, +or `constraint` solely from the note's presence. + +## Alternatives rejected + +- A new Notes Artifact family duplicates Handoff and Source revision/lineage machinery before the use case is proven. +- Storing notes directly in Memory pollutes durable retrieval with session progress. +- Keeping notes only in host transcripts prevents cross-host evidence resolution. diff --git a/docs/zh/rfcs/1790_source_backed_working_notes.md b/docs/zh/rfcs/1790_source_backed_working_notes.md new file mode 100644 index 0000000000..649a787f6b --- /dev/null +++ b/docs/zh/rfcs/1790_source_backed_working_notes.md @@ -0,0 +1,53 @@ +# 基于 Source 的 Working Note + +- 提案名称：`source_backed_working_notes` +- 跟踪 Issue：[oceanbase/powercontext#1790](https://github.com/oceanbase/powercontext/issues/1790) +- 状态：实现决策 + +## 决策 + +PowerContext 对短期工作记录采用仅增加 Source kind 的方案，不新增持久化的 `notes` Artifact family。Working Note +保存为由服务端字段标记的 `ContentSource`，并携带描述性的 session 和 note kind 元数据。它仍然通过完整的 +`(scope_id, source_type, source_id)` 身份寻址。 + +这与 Memory 中 `kind=working_note` 的 Entry 不同：后者是显式 Memory 写入，会进入 Memory 生命周期和检索；捕获的 +Working Note 只是 evidence，除非调用方显式把它用于领域操作。 + +宿主可以通过 `POST /v1/sources/working-notes`、生成的 Python Client `capture_working_note`，或启用时的同名 MCP tool +完成捕获。请求必须包含调用方稳定的 `source_id`、宿主 `session_id`、正文，以及 `inspection`、 +`abandoned_approach`、`validation`、`unresolved` 或 `host_context` 之一。使用相同 identity 重放不同内容仍然属于 +Source conflict。调用方也可以设置一个带时区且晚于当前时间的 `expires_at`。已接受捕获的完全相同重放即使发生在 +过期后，也会返回原 receipt；过期不会削弱捕获幂等性。 + +Working Note 分类由服务端拥有的 `ContentSource` 字段决定。`metadata.kind=working_note` 仍作为描述性元数据保留， +但它本身不是权威标记。通用 content capture 会拒绝这个保留 kind，也无法设置服务端字段。升级前仅碰巧携带该 +metadata 值的 Source 仍按普通 Source 处理，并保持原有 generation 行为。 + +## 处理边界 + +Working Note 不进入自动 Source-window generation。仅仅捕获它不能触发 Memory、Topic Memory、Experience 或其他 +生成 Artifact。显式消费者可以选择精确的 Source 引用；Handoff evidence resolution 会显式允许这一用途。 + +Working Note 内容是不可信的历史材料，不是指令、Skill、prompt policy 或可执行工具输入。 + +## 保留与访问 + +Working Note 继承 Scope Source 的授权。`session_id` 只用于按宿主/session 分组和未来清理，不构成额外授权边界。 +未设置 `expires_at` 时，Note 会保持有效，直到未来显式生命周期操作改变它；时间到期后，包括 Handoff evidence +resolution 在内的新消费者必须将其视为不可用。 + +这里的过期是逻辑过期：它不会删除或改写不可变 Source，Source 仍可通过受支持的审计读取路径访问。物理清理、 +session 结束时清理、legal hold 和跨 Scope 导出属于独立的后续生命周期工作，不在本决策的实现范围内。 + +Handoff 引用记录的始终是精确 Source identity。后续清理不得把该引用静默解析为另一份内容。 + +## 晋升 + +首期实现关闭晋升。未来的显式晋升操作必须提交精确 Source 引用，并通过所属领域的现有校验。不能仅因为 Note 存在， +就自动推断出 durable `fact`、`decision` 或 `constraint`。 + +## 不采用的替代方案 + +- 立即新增 Notes Artifact family：在场景验证前复制 Handoff 和 Source 的 revision/lineage 机制。 +- 直接写入 Memory：会把 session 进度污染到持久检索表面。 +- 只保存在宿主 transcript：无法跨宿主进行 evidence 解析。 From 0bab4edd68803af5f6c9d4b74ab85f20672d9d74 Mon Sep 17 00:00:00 2001 From: qyq316 <19606363088@163.com> Date: Mon, 12 Oct 2026 11:53:45 +0800 Subject: [PATCH 02/11] feat(runtime): add source-backed working notes --- src/powercontext/builtin/context.py | 13 +- .../builtin/persistence/generation_sources.py | 13 +- .../builtin/persistence/handoff.py | 21 ++- .../builtin/persistence/records.py | 5 +- src/powercontext/builtin/records.py | 1 + src/powercontext/builtin/runtime/__init__.py | 4 + .../builtin/runtime/application.py | 60 +++++++- src/powercontext/builtin/runtime/models.py | 22 +++ .../builtin/runtime/relational.py | 8 + .../builtin/source_eligibility.py | 19 ++- src/powercontext/builtin/sources/__init__.py | 2 + src/powercontext/builtin/sources/content.py | 27 ++++ src/powercontext/builtin/sources/journal.py | 2 + .../persistence/test_generation_sources.py | 137 ++++++++++++++++++ tests/e2e/test_builtin_runtime.py | 93 +++++++++++- tests/e2e/test_handoff_runtime.py | 73 ++++++++++ 16 files changed, 491 insertions(+), 9 deletions(-) diff --git a/src/powercontext/builtin/context.py b/src/powercontext/builtin/context.py index 007b3f75db..c43bdef36e 100644 --- a/src/powercontext/builtin/context.py +++ b/src/powercontext/builtin/context.py @@ -32,13 +32,22 @@ class BuiltinSources(Sources): journal: SourceJournal - async def capture(self, value: ContentCapture, /, *, handoff_receipt: bool = False) -> tuple[ContentSource, int]: + async def capture( + self, + value: ContentCapture, + /, + *, + handoff_receipt: bool = False, + working_note: bool = False, + ) -> tuple[ContentSource, int]: """Resolve and persist one Content Source, returning its journal position.""" resolved = await self.resolve(value) if type(resolved) is not ContentSource: raise TypeError("Content Source adapter returned an unexpected Source type") # noqa: TRY003 - source = await self.add(resolved.model_copy(update={"handoff_receipt": handoff_receipt})) + source = await self.add( + resolved.model_copy(update={"handoff_receipt": handoff_receipt, "working_note": working_note}) + ) if type(source) is not ContentSource: raise TypeError("Content Source adapter returned an unexpected Source type") # noqa: TRY003 return source, await self.journal.position(source) diff --git a/src/powercontext/builtin/persistence/generation_sources.py b/src/powercontext/builtin/persistence/generation_sources.py index 11548a56a5..4fb4c2657b 100644 --- a/src/powercontext/builtin/persistence/generation_sources.py +++ b/src/powercontext/builtin/persistence/generation_sources.py @@ -21,7 +21,12 @@ from sqlalchemy.ext.asyncio import AsyncConnection from powercontext.builtin.persistence.sources import SourceRepository, StoredSource -from powercontext.builtin.source_eligibility import is_generation_eligible, require_source_eligible +from powercontext.builtin.source_eligibility import ( + WorkingNoteUnavailableError, + is_generation_eligible, + require_source_eligible, +) +from powercontext.builtin.sources import ContentSource from powercontext.sources import SourceRef @@ -37,11 +42,17 @@ async def require_for_generation( scope_id: str, refs: Sequence[SourceRef], /, + *, + allow_working_notes: bool = False, ) -> tuple[StoredSource, ...]: """Resolve explicit references, rejecting the whole request if any is ineligible.""" rows = await self._repository.get_many(connection, scope_id, refs) for row in rows: + if allow_working_notes and isinstance(row.value, ContentSource) and row.value.is_working_note: + if row.value.is_working_note_active(): + continue + raise WorkingNoteUnavailableError(row.ref) require_source_eligible(row.ref, row.value) return rows diff --git a/src/powercontext/builtin/persistence/handoff.py b/src/powercontext/builtin/persistence/handoff.py index 5688f59dda..9b6104d05b 100644 --- a/src/powercontext/builtin/persistence/handoff.py +++ b/src/powercontext/builtin/persistence/handoff.py @@ -37,6 +37,7 @@ from powercontext.builtin.persistence.database import AsyncDatabase from powercontext.builtin.persistence.errors import RepositoryNotFoundError from powercontext.builtin.persistence.generation_sources import GenerationSourceAccess +from powercontext.builtin.source_eligibility import WorkingNoteUnavailableError from powercontext.errors import ArtifactNotFoundError @@ -146,11 +147,19 @@ async def resolve_many( ) try: async with self._database.connection(self._bound_connection) as connection: - sources = await self._sources.require_for_generation(connection, self._scope_id, source_refs) + sources = await self._sources.require_for_generation( + connection, + self._scope_id, + source_refs, + allow_working_notes=True, + ) artifacts = await self._artifacts.get_many(connection, self._scope_id, artifact_refs) except RepositoryNotFoundError as error: unavailable = _missing_citation(requested, error) raise HandoffEvidenceUnavailableError(unavailable) from error + except WorkingNoteUnavailableError as error: + unavailable = _ineligible_source_citation(requested, error) + raise HandoffEvidenceUnavailableError(unavailable) from error source_values = {(row.ref.source_type, row.ref.source_id): row.value for row in sources} artifact_values = { @@ -193,4 +202,14 @@ def _missing_citation( raise error +def _ineligible_source_citation( + citations: tuple[HandoffCitation, ...], + error: WorkingNoteUnavailableError, +) -> HandoffSourceCitation: + for citation in citations: + if isinstance(citation, HandoffSourceCitation) and citation.source_ref == error.source: + return citation + raise error + + __all__ = ["RelationalHandoffBackend", "RelationalHandoffEvidenceResolver"] diff --git a/src/powercontext/builtin/persistence/records.py b/src/powercontext/builtin/persistence/records.py index e5e547981a..fa02b453de 100644 --- a/src/powercontext/builtin/persistence/records.py +++ b/src/powercontext/builtin/persistence/records.py @@ -188,6 +188,7 @@ async def capture_source( /, *, handoff_receipt: bool = False, + working_note: bool = False, ) -> SourceRecord: """Preserve the caller-stable identity used by the existing capture API.""" @@ -202,7 +203,9 @@ async def capture_source( return await self._store_source( scope_id, source_type, - (await CONTENT_SOURCE_ADAPTER.resolve(capture)).model_copy(update={"handoff_receipt": handoff_receipt}), + (await CONTENT_SOURCE_ADAPTER.resolve(capture)).model_copy( + update={"handoff_receipt": handoff_receipt, "working_note": working_note} + ), ) async def _store_source( diff --git a/src/powercontext/builtin/records.py b/src/powercontext/builtin/records.py index 56f8df85af..b5a078369e 100644 --- a/src/powercontext/builtin/records.py +++ b/src/powercontext/builtin/records.py @@ -261,6 +261,7 @@ async def capture_source( /, *, handoff_receipt: bool = False, + working_note: bool = False, ) -> SourceRecord: ... async def get_source(self, scope_id: str, source_type: str, source_id: str, /) -> SourceRecord: ... diff --git a/src/powercontext/builtin/runtime/__init__.py b/src/powercontext/builtin/runtime/__init__.py index 3cf2bc71d2..1fc8f30bdb 100644 --- a/src/powercontext/builtin/runtime/__init__.py +++ b/src/powercontext/builtin/runtime/__init__.py @@ -138,6 +138,7 @@ from powercontext.builtin.runtime.models import ( ApproveArtifactCandidateRequest, CaptureSource, + CaptureWorkingNote, CommitConnectorCheckpoint, ConnectorCheckpointState, ContextAssembly, @@ -181,6 +182,7 @@ SourceReceipt, SubmitSourceObservation, TopicMemoryFlushResult, + WorkingNoteKind, ) from powercontext.builtin.runtime.protocols import PowerContextProvider, RemoteIngestion from powercontext.builtin.runtime.readiness import ( @@ -243,6 +245,7 @@ "CandidateFamilyCount", "CandidateInventoryStatistics", "CaptureSource", + "CaptureWorkingNote", "CommitConnectorCheckpoint", "ConnectorCheckpointState", "ContextAssembly", @@ -399,6 +402,7 @@ "UsageStatistics", "WorkApplication", "assess_decision_result", + "WorkingNoteKind", "build_memory_write_gate", "dependency_readiness_probe", "open_builtin_contexts", diff --git a/src/powercontext/builtin/runtime/application.py b/src/powercontext/builtin/runtime/application.py index 8dbe0cfa0d..d32ee5813d 100644 --- a/src/powercontext/builtin/runtime/application.py +++ b/src/powercontext/builtin/runtime/application.py @@ -171,6 +171,7 @@ from powercontext.builtin.runtime.models import ( ApproveArtifactCandidateRequest, CaptureSource, + CaptureWorkingNote, CommitConnectorCheckpoint, ConnectorCheckpointState, ExperienceCandidate, @@ -246,7 +247,9 @@ from powercontext.builtin.scope import ScopeApplication, ScopeDescriptor, ScopeSelection from powercontext.builtin.scope.subject_sources import SubjectSourceService from powercontext.builtin.sources import ( + CONTENT_SOURCE_ADAPTER, CONTENT_SOURCE_NAME, + WORKING_NOTE_SOURCE_KIND, ContentCapture, ContentSource, ExternalSkillImportMode, @@ -327,6 +330,7 @@ def __call__( _MEMORY_CAPTURE_STAGE = "memory.capture" _MEMORY_CAPTURE_SOURCE_COUNT = "powercontext.memory.capture.source_count" +_WORKING_NOTE_RESERVED_METADATA = frozenset({"kind", "session_id", "note_kind", "expires_at"}) _MEMORY_SEARCH_STAGE = "memory.search" _MEMORY_SEARCH_REQUESTED_MODE = "powercontext.memory.search.requested_mode" _MEMORY_SEARCH_LIMIT = "powercontext.memory.search.limit" @@ -467,9 +471,61 @@ def __init__(self, runtime: BuiltinRuntime, scope_id: str) -> None: self.scope_id = validate_scope_id(scope_id) async def capture(self, value: CaptureSource, /) -> SourceReceipt: + if value.metadata.get("kind") == WORKING_NOTE_SOURCE_KIND: + raise InvalidRuntimeRequestError("working-note-dedicated-api") return await self._capture(value) - async def _capture(self, value: CaptureSource, /, *, handoff_receipt: bool = False) -> SourceReceipt: + async def capture_working_note(self, value: CaptureWorkingNote, /) -> SourceReceipt: + """Capture explicit session-local work state without Memory promotion.""" + + if _WORKING_NOTE_RESERVED_METADATA.intersection(value.metadata): + raise InvalidRuntimeRequestError("working-note-metadata") + if not value.session_id.strip(): + raise ValueError("session_id must not be blank") # noqa: TRY003 + if not value.note_kind.strip(): + raise ValueError("note_kind must not be blank") # noqa: TRY003 + if value.expires_at is not None and (value.expires_at.tzinfo is None or value.expires_at.utcoffset() is None): + raise InvalidRuntimeRequestError("working-note-expiry") + metadata = dict(value.metadata) + metadata.update({ + "kind": WORKING_NOTE_SOURCE_KIND, + "session_id": value.session_id, + "note_kind": value.note_kind, + }) + if value.expires_at is not None: + metadata["expires_at"] = value.expires_at.astimezone(UTC).isoformat() + capture = CaptureSource(source_id=value.source_id, content=value.content, metadata=metadata) + if value.expires_at is not None and value.expires_at <= datetime.now(UTC): + replay = await self._replay_working_note(capture) + if replay is not None: + return replay + raise InvalidRuntimeRequestError("working-note-expiry") + return await self._capture(capture, working_note=True) + + async def _replay_working_note(self, value: CaptureSource, /) -> SourceReceipt | None: + capture = ContentCapture( + source_id=value.source_id, + content=value.content, + metadata=value.model_dump(mode="json")["metadata"], + ) + proposed = (await CONTENT_SOURCE_ADAPTER.resolve(capture)).model_copy(update={"working_note": True}) + ref = SourceRef(source_type=CONTENT_SOURCE_NAME, source_id=value.source_id) + async with self._runtime._context(self.scope_id) as context, self._runtime._locked(self.scope_id): + existing = await context.sources.journal.entry(ref) + if existing is None: + return None + if existing.source != proposed: + raise SourceConflictError("identity", (self.scope_id, ref)) + return SourceReceipt(source_ref=ref, sequence=existing.position) + + async def _capture( + self, + value: CaptureSource, + /, + *, + handoff_receipt: bool = False, + working_note: bool = False, + ) -> SourceReceipt: if self._runtime._record_service is not None: try: async with self._runtime._scope_operation(self.scope_id), self._runtime._locked(self.scope_id): @@ -481,6 +537,7 @@ async def _capture(self, value: CaptureSource, /, *, handoff_receipt: bool = Fal value.content, value.metadata, handoff_receipt=handoff_receipt, + working_note=working_note, ) if span is not None: span.set_attributes({_MEMORY_CAPTURE_SOURCE_COUNT: 1}) @@ -499,6 +556,7 @@ async def _capture(self, value: CaptureSource, /, *, handoff_receipt: bool = Fal metadata=value.model_dump(mode="json")["metadata"], ), handoff_receipt=handoff_receipt, + working_note=working_note, ) if span is not None: span.set_attributes({_MEMORY_CAPTURE_SOURCE_COUNT: 1}) diff --git a/src/powercontext/builtin/runtime/models.py b/src/powercontext/builtin/runtime/models.py index e55a4109c5..52251574a8 100644 --- a/src/powercontext/builtin/runtime/models.py +++ b/src/powercontext/builtin/runtime/models.py @@ -18,6 +18,7 @@ from collections.abc import Mapping from datetime import datetime +from enum import StrEnum from typing import Annotated, Any, Literal, TypeAlias from pydantic import BaseModel, ConfigDict, Field, JsonValue, field_validator, model_validator @@ -71,6 +72,27 @@ class CaptureSource(BaseModel): metadata: Mapping[str, JsonValue] +class WorkingNoteKind(StrEnum): + """Classify one bounded kind of session-local work state.""" + + INSPECTION = "inspection" + ABANDONED_APPROACH = "abandoned_approach" + VALIDATION = "validation" + UNRESOLVED = "unresolved" + HOST_CONTEXT = "host_context" + + +class CaptureWorkingNote(BaseModel): + """Explicitly capture short-lived, non-Memory work state.""" + + source_id: str + content: str + session_id: str + note_kind: WorkingNoteKind + expires_at: datetime | None = None + metadata: Mapping[str, JsonValue] = Field(default_factory=dict) + + class SourceReceipt(BaseModel): """A canonical captured Source and its stable journal position.""" diff --git a/src/powercontext/builtin/runtime/relational.py b/src/powercontext/builtin/runtime/relational.py index 6e0ab08457..73ee6f36d0 100644 --- a/src/powercontext/builtin/runtime/relational.py +++ b/src/powercontext/builtin/runtime/relational.py @@ -1535,6 +1535,14 @@ async def position(self, source: Source, /) -> int: except RepositoryNotFoundError: raise SourceNotFoundError(source) from None + async def entry(self, ref: SourceRef, /) -> SourceJournalEntry | None: + try: + async with self._database.connection(self._bound_connection) as connection: + row = await self._repository.get(connection, self._scope_id, ref) + except RepositoryNotFoundError: + return None + return SourceJournalEntry(source_ref=row.ref, source=row.value, position=row.journal_position) + async def entries(self) -> tuple[SourceJournalEntry, ...]: async with self._database.connection(self._bound_connection) as connection: rows = await self._repository.list(connection, self._scope_id) diff --git a/src/powercontext/builtin/source_eligibility.py b/src/powercontext/builtin/source_eligibility.py index 1371634dc9..975c6c5d27 100644 --- a/src/powercontext/builtin/source_eligibility.py +++ b/src/powercontext/builtin/source_eligibility.py @@ -40,10 +40,21 @@ def __init__(self, source: SourceRef) -> None: super().__init__("source_not_eligible") +class WorkingNoteUnavailableError(SourceNotEligibleError): + """Report a Working Note that is expired or has invalid expiry metadata.""" + + def is_generation_eligible(source: Source, /) -> bool: """Return whether a hydrated Source may enter a model or Candidate.""" - return not isinstance(source, ContentSource) or source.internal is None + if not isinstance(source, ContentSource): + return True + if source.internal is not None: + return False + # Working Notes are durable evidence, but must not be promoted by the + # ordinary Source-window processors. Explicit consumers (for example a + # Handoff citation) still resolve them through require_source_eligible. + return not source.is_working_note def require_source_eligible( @@ -55,7 +66,11 @@ def require_source_eligible( ) -> None: """Allow ordinary evidence, or a lineage-only Source at its exact bound target.""" - if not isinstance(source, ContentSource) or source.internal is None: + if not isinstance(source, ContentSource): + return + if source.is_working_note: + raise SourceNotEligibleError(source_ref) + if source.internal is None: return bound = source.internal.target if target is not None and ( diff --git a/src/powercontext/builtin/sources/__init__.py b/src/powercontext/builtin/sources/__init__.py index 1019276a9e..6a72300146 100644 --- a/src/powercontext/builtin/sources/__init__.py +++ b/src/powercontext/builtin/sources/__init__.py @@ -18,6 +18,7 @@ CONTENT_SOURCE_ADAPTER, CONTENT_SOURCE_DEFINITION, CONTENT_SOURCE_NAME, + WORKING_NOTE_SOURCE_KIND, ContentCapture, ContentSource, ContentSourceAdapter, @@ -83,6 +84,7 @@ "SKILL_USAGE_SOURCE_DEFINITION", "SKILL_USAGE_SOURCE_NAME", "TEXT_EVIDENCE_PROJECTION_KEY", + "WORKING_NOTE_SOURCE_KIND", "ContentCapture", "ContentSource", "ContentSourceAdapter", diff --git a/src/powercontext/builtin/sources/content.py b/src/powercontext/builtin/sources/content.py index b8ccc4000c..c9d40a380c 100644 --- a/src/powercontext/builtin/sources/content.py +++ b/src/powercontext/builtin/sources/content.py @@ -16,6 +16,7 @@ from __future__ import annotations +from datetime import UTC, datetime from typing import Annotated, Literal from pydantic import BaseModel, ConfigDict, Field, JsonValue, field_validator @@ -26,6 +27,7 @@ from powercontext.sources.models import Source, SourceMaterialization CONTENT_SOURCE_NAME = "content" +WORKING_NOTE_SOURCE_KIND = "working_note" NonEmptyText = Annotated[str, Field(min_length=1)] @@ -96,12 +98,37 @@ class ContentSource(Source): content: str metadata: dict[str, JsonValue] = Field(default_factory=dict) + working_note: bool = False wire_content: JsonValue | None = None wire_content_present: bool = False internal: ContentSourceInternal | None = None # Set only by the Work acknowledgement writer, never from capture metadata. handoff_receipt: bool = False + @property + def is_working_note(self) -> bool: + """Whether this captured Source is explicitly session-local work state.""" + + return self.working_note + + def is_working_note_active(self, *, now: datetime | None = None) -> bool: + """Whether a Working Note remains eligible for an explicit consumer.""" + + if not self.is_working_note: + return False + expires_at = self.metadata.get("expires_at") + if expires_at is None: + return True + if not isinstance(expires_at, str): + return False + try: + expiry = datetime.fromisoformat(expires_at) + except ValueError: + return False + if expiry.tzinfo is None or expiry.utcoffset() is None: + return False + return expiry > (datetime.now(UTC) if now is None else now) + class ContentSourceAdapter: """Resolve and read the runtime's built-in captured-text Source.""" diff --git a/src/powercontext/builtin/sources/journal.py b/src/powercontext/builtin/sources/journal.py index 82f42383c9..1c93b90091 100644 --- a/src/powercontext/builtin/sources/journal.py +++ b/src/powercontext/builtin/sources/journal.py @@ -54,6 +54,8 @@ class SourceJournalEntry: class SourceJournal(Protocol): """Read stable positions from one scoped Source catalog.""" + async def entry(self, ref: SourceRef, /) -> SourceJournalEntry | None: ... + async def position(self, source: Source, /) -> int: ... async def entries(self) -> tuple[SourceJournalEntry, ...]: ... diff --git a/tests/builtin/persistence/test_generation_sources.py b/tests/builtin/persistence/test_generation_sources.py index 32809b9834..b0912317a5 100644 --- a/tests/builtin/persistence/test_generation_sources.py +++ b/tests/builtin/persistence/test_generation_sources.py @@ -17,6 +17,7 @@ import asyncio import pytest +import rfc8785 from sqlalchemy import update from powercontext.builtin.persistence import InvalidStoredPayloadError @@ -57,6 +58,19 @@ def _content_source(name: str, *, lineage_only: bool = False) -> ContentSource: ) +def _working_note(name: str, *, expires_at: str | int | None = None) -> ContentSource: + metadata = {"kind": "working_note", "session_id": "session-1", "note_kind": "validation"} + if expires_at is not None: + metadata["expires_at"] = expires_at + return ContentSource( + name=name, + materialization=SourceMaterialization.CAPTURED, + content=name, + metadata=metadata, + working_note=True, + ) + + def test_generation_source_access_rejects_explicit_refs_but_skips_window_entries() -> None: async def scenario() -> None: repository = SourceRepository((CONTENT_SOURCE_ADAPTER,)) @@ -85,6 +99,129 @@ async def scenario() -> None: asyncio.run(scenario()) +def test_legacy_metadata_only_working_note_marker_remains_ordinary_source() -> None: + async def scenario() -> None: + repository = SourceRepository((CONTENT_SOURCE_ADAPTER,)) + access = GenerationSourceAccess(repository) + legacy = ContentSource( + name="legacy", + materialization=SourceMaterialization.CAPTURED, + content="Historical ordinary content.", + metadata={"kind": "working_note"}, + ) + async with repository_profile() as (profile, _repositories): + async with profile.database.transaction() as connection: + stored = await repository.add(connection, "scope-a", legacy) + legacy_value = legacy.model_dump(mode="json", by_alias=True) + legacy_value.pop("working_note") + await connection.execute( + update(SOURCES_TABLE) + .where( + SOURCES_TABLE.c.scope_id == "scope-a", + SOURCES_TABLE.c.source_type == stored.ref.source_type, + SOURCES_TABLE.c.source_id == stored.ref.source_id, + ) + .values( + payload=rfc8785.dumps({ + "encoding": "powercontext-source-v1", + "representation": "native", + "value": legacy_value, + }) + ) + ) + window = await access.list_window_for_generation( + connection, + "scope-a", + after=0, + through=stored.journal_position, + ) + + assert window == (stored,) + + asyncio.run(scenario()) + + +@pytest.mark.parametrize("expires_at", ["2000-01-01T00:00:00+00:00", "not-a-timestamp", 1]) +def test_expired_or_malformed_working_notes_are_not_explicit_generation_evidence( + expires_at: str | int, +) -> None: + async def scenario() -> None: + repository = SourceRepository((CONTENT_SOURCE_ADAPTER,)) + access = GenerationSourceAccess(repository) + async with repository_profile() as (profile, _repositories): + async with profile.database.transaction() as connection: + note = await repository.add( + connection, + "scope-a", + _working_note("unavailable-note", expires_at=expires_at), + ) + + with pytest.raises(SourceNotEligibleError) as error: + await access.require_for_generation( + connection, + "scope-a", + (note.ref,), + allow_working_notes=True, + ) + + assert error.value.source == note.ref + + asyncio.run(scenario()) + + +def test_unexpired_working_note_remains_explicit_generation_evidence() -> None: + async def scenario() -> None: + repository = SourceRepository((CONTENT_SOURCE_ADAPTER,)) + access = GenerationSourceAccess(repository) + async with repository_profile() as (profile, _repositories): + async with profile.database.transaction() as connection: + note = await repository.add( + connection, + "scope-a", + _working_note("active-note", expires_at="9999-01-01T00:00:00+00:00"), + ) + + resolved = await access.require_for_generation( + connection, + "scope-a", + (note.ref,), + allow_working_notes=True, + ) + + assert resolved == (note,) + + asyncio.run(scenario()) + + +def test_working_notes_are_skipped_by_automatic_generation_but_remain_explicit_evidence() -> None: + async def scenario() -> None: + repository = SourceRepository((CONTENT_SOURCE_ADAPTER,)) + access = GenerationSourceAccess(repository) + async with repository_profile() as (profile, _repositories): + async with profile.database.transaction() as connection: + note = await repository.add(connection, "scope-a", _working_note("note")) + + window = await access.list_window_for_generation( + connection, + "scope-a", + after=0, + through=note.journal_position, + ) + with pytest.raises(SourceNotEligibleError): + await access.require_for_generation(connection, "scope-a", (note.ref,)) + explicit = await access.require_for_generation( + connection, + "scope-a", + (note.ref,), + allow_working_notes=True, + ) + + assert window == () + assert explicit == (note,) + + asyncio.run(scenario()) + + def test_generation_window_fails_closed_on_a_malformed_source_payload() -> None: async def scenario() -> None: repository = SourceRepository((CONTENT_SOURCE_ADAPTER,)) diff --git a/tests/e2e/test_builtin_runtime.py b/tests/e2e/test_builtin_runtime.py index 1f531fadf1..8581c868c6 100644 --- a/tests/e2e/test_builtin_runtime.py +++ b/tests/e2e/test_builtin_runtime.py @@ -16,8 +16,10 @@ import asyncio import json +from datetime import UTC, datetime, timedelta, timezone import pytest +import time_machine from powercontext.builtin.artifacts.atomic_memory import AtomicMemoryContent from powercontext.builtin.artifacts.atomic_memory.extraction import ( @@ -32,14 +34,18 @@ from powercontext.builtin.runtime import ( BuiltinConfig, CaptureSource, + CaptureWorkingNote, CommitConnectorCheckpoint, + InvalidRuntimeRequestError, PrepareContextRequest, SubmitSourceObservation, + WorkingNoteKind, open_builtin_contexts, open_builtin_runtime, ) from powercontext.builtin.scope import ScopeDraft, ScopeMutation, ScopeNotFoundError -from powercontext.builtin.sources import CONTENT_SOURCE_DEFINITION, ContentCapture +from powercontext.builtin.sources import CONTENT_SOURCE_DEFINITION, ContentCapture, ContentSource +from powercontext.errors import SourceConflictError from powercontext.sources import ConnectorBinding, SourceDefinitionRegistry, project_source_for_transport from tests.e2e.dream_support import atomic_memory_pipeline, memory_source_text @@ -168,6 +174,91 @@ async def scenario() -> None: asyncio.run(scenario()) +def test_working_note_capture_does_not_promote_into_memory() -> None: + async def scenario() -> None: + async with open_builtin_runtime( + BuiltinConfig(database=SQLiteConfig()), + candidate_pipeline=_ContentCandidatePipeline(), + ) as runtime: + assert runtime.scopes is not None + scope = await runtime.scopes.create( + ScopeDraft(title="Project", summary="Working note boundary", idempotency_key="working-note") + ) + for field, field_value in ( + ("kind", "working_note"), + ("session_id", "metadata-session"), + ("note_kind", "validation"), + ("expires_at", "2000-01-01T00:00:00+00:00"), + ): + with pytest.raises(InvalidRuntimeRequestError): + await runtime.sources.for_scope(scope.scope_id).capture_working_note( + CaptureWorkingNote( + source_id=f"reserved-{field}", + content="Caller metadata cannot set server-owned Working Note fields.", + session_id="session-1", + note_kind=WorkingNoteKind.VALIDATION, + metadata={field: field_value}, + ) + ) + captured = await runtime.sources.for_scope(scope.scope_id).capture_working_note( + CaptureWorkingNote( + source_id="note-1", + content="The rejected approach depended on an unavailable API.", + session_id="session-1", + note_kind=WorkingNoteKind.ABANDONED_APPROACH, + expires_at=datetime(2099, 1, 1, tzinfo=timezone(-timedelta(hours=8))), + ) + ) + replayed = await runtime.sources.for_scope(scope.scope_id).capture_working_note( + CaptureWorkingNote( + source_id="note-1", + content="The rejected approach depended on an unavailable API.", + session_id="session-1", + note_kind=WorkingNoteKind.ABANDONED_APPROACH, + expires_at=datetime(2099, 1, 1, 8, tzinfo=UTC), + ) + ) + with time_machine.travel(datetime(2100, 1, 1, tzinfo=UTC)): + expired_replay = await runtime.sources.for_scope(scope.scope_id).capture_working_note( + CaptureWorkingNote( + source_id="note-1", + content="The rejected approach depended on an unavailable API.", + session_id="session-1", + note_kind=WorkingNoteKind.ABANDONED_APPROACH, + expires_at=datetime(2099, 1, 1, 8, tzinfo=UTC), + ) + ) + with pytest.raises(SourceConflictError): + await runtime.sources.for_scope(scope.scope_id).capture_working_note( + CaptureWorkingNote( + source_id="note-1", + content="Different content cannot reuse the identity.", + session_id="session-1", + note_kind=WorkingNoteKind.ABANDONED_APPROACH, + expires_at=datetime(2099, 1, 1, 8, tzinfo=UTC), + ) + ) + with pytest.raises(InvalidRuntimeRequestError): + await runtime.sources.for_scope(scope.scope_id).capture_working_note( + CaptureWorkingNote( + source_id="never-accepted", + content="A new expired note is invalid.", + session_id="session-1", + note_kind=WorkingNoteKind.ABANDONED_APPROACH, + expires_at=datetime(2099, 1, 1, 8, tzinfo=UTC), + ) + ) + + flushed = await runtime.memory.for_scope(scope.scope_id).flush() + + assert replayed == captured + assert expired_replay == captured + assert flushed.current_cursor == captured.sequence + assert flushed.memory_ref is 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: diff --git a/tests/e2e/test_handoff_runtime.py b/tests/e2e/test_handoff_runtime.py index b6c5a0f2ca..0ff3037a0c 100644 --- a/tests/e2e/test_handoff_runtime.py +++ b/tests/e2e/test_handoff_runtime.py @@ -16,9 +16,11 @@ import asyncio import json +from datetime import UTC, datetime from pathlib import Path import pytest +import time_machine from powercontext.artifacts import ArtifactRef from powercontext.builtin.artifacts.atomic_memory import AtomicMemoryContent @@ -35,6 +37,7 @@ ActivateHandoff, BuiltinConfig, CaptureSource, + CaptureWorkingNote, HandoffArtifactCitation, HandoffDraft, HandoffOmission, @@ -42,6 +45,8 @@ HandoffStatement, InferenceConfig, PreparedHandoff, + RememberMemoryRequest, + WorkingNoteKind, open_builtin_runtime, ) from powercontext.builtin.runtime.relational import RelationalContexts @@ -71,6 +76,74 @@ async def generate(self, request, /) -> HandoffDraft: ) +def test_handoff_can_use_an_explicit_working_note_citation() -> None: + async def scenario() -> None: + async with open_builtin_runtime( + BuiltinConfig(database=SQLiteConfig()), + handoff_pipeline=_EchoHandoffPipeline(), + ) as runtime: + assert runtime.scopes is not None + scope = await runtime.scopes.create( + ScopeDraft(title="Working note", summary="Handoff evidence", idempotency_key="working-note-handoff") + ) + note = await runtime.sources.for_scope(scope.scope_id).capture_working_note( + CaptureWorkingNote( + source_id="note-1", + content="The malformed-input regression passed locally.", + session_id="session-1", + note_kind=WorkingNoteKind.VALIDATION, + ) + ) + citation = HandoffSourceCitation(source_ref=note.source_ref) + + draft = await runtime.handoff.for_scope(scope.scope_id).prepare( + PrepareHandoff(objective="Continue parser validation.", evidence=(citation,)) + ) + + assert draft.state[0].citations == (citation,) + assert draft.next_action is not None + assert draft.next_action.citations == (citation,) + + asyncio.run(scenario()) + + +def test_handoff_rejects_an_expired_working_note_citation() -> None: + async def scenario() -> None: + async with open_builtin_runtime( + BuiltinConfig(database=SQLiteConfig()), + handoff_pipeline=_EchoHandoffPipeline(), + ) as runtime: + assert runtime.scopes is not None + scope = await runtime.scopes.create( + ScopeDraft(title="Expired note", summary="Handoff evidence", idempotency_key="expired-note-handoff") + ) + with time_machine.travel(datetime(2030, 1, 1, tzinfo=UTC)): + note = await runtime.sources.for_scope(scope.scope_id).capture_working_note( + CaptureWorkingNote( + source_id="expired-note", + content="This validation result is no longer current.", + session_id="session-1", + note_kind=WorkingNoteKind.VALIDATION, + expires_at=datetime(2030, 1, 2, tzinfo=UTC), + ) + ) + citation = HandoffSourceCitation(source_ref=note.source_ref) + + with ( + time_machine.travel(datetime(2030, 1, 3, tzinfo=UTC)), + pytest.raises(HandoffEvidenceUnavailableError) as error, + ): + await runtime.handoff.for_scope(scope.scope_id).prepare( + PrepareHandoff(objective="Continue parser validation.", evidence=(citation,)) + ) + + assert error.value.citation == citation + stored = await runtime.records.for_scope(scope.scope_id).get_source("content", "expired-note") + assert stored.content == "This validation result is no longer current." + + asyncio.run(scenario()) + + @pytest.mark.parametrize("family", ["unregistered-family", "experience"]) def test_handoff_batch_error_identifies_missing_artifact_after_valid_source(family) -> None: async def scenario() -> None: From 60e7b5fecdcbe930a8707acd0e99a40cfcec2c1f Mon Sep 17 00:00:00 2001 From: qyq316 <19606363088@163.com> Date: Mon, 12 Oct 2026 11:54:38 +0800 Subject: [PATCH 03/11] feat(api): expose working note capture --- integrations/capabilities.toml | 3 + .../plugins/powercontext/hooks/bind_tools.py | 1 + .../powercontext/src/operations.generated.ts | 1 + .../powercontext/src/operations.generated.ts | 1 + .../powercontext/src/operations.generated.ts | 1 + openapi/powercontext.yaml | 83 +++++++++++ src/powercontext/cli/system.py | 1 + src/powercontext/client/client.py | 7 + src/powercontext/http/__init__.py | 4 + src/powercontext/http/_generated/models.py | 40 +++++- .../http/_generated/operations.py | 30 ++++ src/powercontext/http/_generated/schema.py | 136 +++++++++++++++++- src/powercontext/server/app.py | 18 +++ src/powercontext/server/mapping.py | 15 ++ src/powercontext/server/mcp.py | 4 + tests/e2e/test_mcp_transport.py | 1 + tests/e2e/test_runtime_server.py | 84 +++++++++++ tests/test_api_contract.py | 5 + tests/test_mcp.py | 1 + 19 files changed, 434 insertions(+), 2 deletions(-) diff --git a/integrations/capabilities.toml b/integrations/capabilities.toml index 44f7f5fb07..216c5a2051 100644 --- a/integrations/capabilities.toml +++ b/integrations/capabilities.toml @@ -100,6 +100,9 @@ capabilities = ["memory_write"] id = "capture_content_source" capabilities = ["source_capture"] [[toolsets.tools]] +id = "capture_working_note" +capabilities = ["source_capture"] +[[toolsets.tools]] id = "create_work_contract" capabilities = ["work_contract"] [[toolsets.tools]] diff --git a/integrations/codex/plugins/powercontext/hooks/bind_tools.py b/integrations/codex/plugins/powercontext/hooks/bind_tools.py index f1f7b2f317..ed64465b5e 100644 --- a/integrations/codex/plugins/powercontext/hooks/bind_tools.py +++ b/integrations/codex/plugins/powercontext/hooks/bind_tools.py @@ -46,6 +46,7 @@ "approve_artifact_candidate", "capture_content_source", "change_atomic_memory_lifecycle", + "capture_working_note", "commit_handoff", "continue_handoff", "create_remote_skill_target", diff --git a/integrations/dsh/plugins/powercontext/src/operations.generated.ts b/integrations/dsh/plugins/powercontext/src/operations.generated.ts index 34c0b7dd54..4abd04a716 100644 --- a/integrations/dsh/plugins/powercontext/src/operations.generated.ts +++ b/integrations/dsh/plugins/powercontext/src/operations.generated.ts @@ -44,6 +44,7 @@ export const OPERATIONS = { set_scope_binding: { method: 'PUT', path: '/v1/scope-bindings', location: "body", scopeMode: 'none', pathParameters: [], queryParams: [], headerParams: [], successStatuses: [200], emptyStatuses: [] }, clear_scope_binding: { method: 'POST', path: '/v1/scope-bindings/clear', location: "body", scopeMode: 'none', pathParameters: [], queryParams: [], headerParams: [], successStatuses: [200], emptyStatuses: [] }, capture_content_source: { method: 'POST', path: '/v1/sources/content', location: "body", scopeMode: 'current', pathParameters: [], queryParams: [], headerParams: [], successStatuses: [202], emptyStatuses: [] }, + capture_working_note: { method: 'POST', path: '/v1/sources/working-notes', location: "body", scopeMode: 'current', pathParameters: [], queryParams: [], headerParams: [], successStatuses: [202], emptyStatuses: [] }, register_source_definition: { method: 'POST', path: '/v1/source-definitions/register', location: "body", scopeMode: 'none', pathParameters: [], queryParams: [], headerParams: [], successStatuses: [200], emptyStatuses: [] }, get_connector_checkpoint: { method: 'POST', path: '/v1/connector-checkpoints/get', location: "body", scopeMode: 'none', pathParameters: [], queryParams: [], headerParams: [], successStatuses: [200], emptyStatuses: [] }, submit_source_observation: { method: 'POST', path: '/v1/source-observations', location: "body", scopeMode: 'none', pathParameters: [], queryParams: [], headerParams: [], successStatuses: [202], emptyStatuses: [] }, diff --git a/integrations/opencode/plugins/powercontext/src/operations.generated.ts b/integrations/opencode/plugins/powercontext/src/operations.generated.ts index 34c0b7dd54..4abd04a716 100644 --- a/integrations/opencode/plugins/powercontext/src/operations.generated.ts +++ b/integrations/opencode/plugins/powercontext/src/operations.generated.ts @@ -44,6 +44,7 @@ export const OPERATIONS = { set_scope_binding: { method: 'PUT', path: '/v1/scope-bindings', location: "body", scopeMode: 'none', pathParameters: [], queryParams: [], headerParams: [], successStatuses: [200], emptyStatuses: [] }, clear_scope_binding: { method: 'POST', path: '/v1/scope-bindings/clear', location: "body", scopeMode: 'none', pathParameters: [], queryParams: [], headerParams: [], successStatuses: [200], emptyStatuses: [] }, capture_content_source: { method: 'POST', path: '/v1/sources/content', location: "body", scopeMode: 'current', pathParameters: [], queryParams: [], headerParams: [], successStatuses: [202], emptyStatuses: [] }, + capture_working_note: { method: 'POST', path: '/v1/sources/working-notes', location: "body", scopeMode: 'current', pathParameters: [], queryParams: [], headerParams: [], successStatuses: [202], emptyStatuses: [] }, register_source_definition: { method: 'POST', path: '/v1/source-definitions/register', location: "body", scopeMode: 'none', pathParameters: [], queryParams: [], headerParams: [], successStatuses: [200], emptyStatuses: [] }, get_connector_checkpoint: { method: 'POST', path: '/v1/connector-checkpoints/get', location: "body", scopeMode: 'none', pathParameters: [], queryParams: [], headerParams: [], successStatuses: [200], emptyStatuses: [] }, submit_source_observation: { method: 'POST', path: '/v1/source-observations', location: "body", scopeMode: 'none', pathParameters: [], queryParams: [], headerParams: [], successStatuses: [202], emptyStatuses: [] }, diff --git a/integrations/pi/plugins/powercontext/src/operations.generated.ts b/integrations/pi/plugins/powercontext/src/operations.generated.ts index 34c0b7dd54..4abd04a716 100644 --- a/integrations/pi/plugins/powercontext/src/operations.generated.ts +++ b/integrations/pi/plugins/powercontext/src/operations.generated.ts @@ -44,6 +44,7 @@ export const OPERATIONS = { set_scope_binding: { method: 'PUT', path: '/v1/scope-bindings', location: "body", scopeMode: 'none', pathParameters: [], queryParams: [], headerParams: [], successStatuses: [200], emptyStatuses: [] }, clear_scope_binding: { method: 'POST', path: '/v1/scope-bindings/clear', location: "body", scopeMode: 'none', pathParameters: [], queryParams: [], headerParams: [], successStatuses: [200], emptyStatuses: [] }, capture_content_source: { method: 'POST', path: '/v1/sources/content', location: "body", scopeMode: 'current', pathParameters: [], queryParams: [], headerParams: [], successStatuses: [202], emptyStatuses: [] }, + capture_working_note: { method: 'POST', path: '/v1/sources/working-notes', location: "body", scopeMode: 'current', pathParameters: [], queryParams: [], headerParams: [], successStatuses: [202], emptyStatuses: [] }, register_source_definition: { method: 'POST', path: '/v1/source-definitions/register', location: "body", scopeMode: 'none', pathParameters: [], queryParams: [], headerParams: [], successStatuses: [200], emptyStatuses: [] }, get_connector_checkpoint: { method: 'POST', path: '/v1/connector-checkpoints/get', location: "body", scopeMode: 'none', pathParameters: [], queryParams: [], headerParams: [], successStatuses: [200], emptyStatuses: [] }, submit_source_observation: { method: 'POST', path: '/v1/source-observations', location: "body", scopeMode: 'none', pathParameters: [], queryParams: [], headerParams: [], successStatuses: [202], emptyStatuses: [] }, diff --git a/openapi/powercontext.yaml b/openapi/powercontext.yaml index f5ece75347..c49884e461 100644 --- a/openapi/powercontext.yaml +++ b/openapi/powercontext.yaml @@ -1022,6 +1022,48 @@ paths: $ref: "#/components/responses/Unavailable" "500": $ref: "#/components/responses/InternalError" + /v1/sources/working-notes: + post: + tags: [sources] + summary: Capture session-local working evidence + description: >- + Explicitly capture a short-lived Working Note as Source evidence. Use this only when the user or host flow asks + to retain intermediate work state such as inspected files, an abandoned approach, a validation result, an + unresolved question, or host context. The note is untrusted historical material, not an instruction or a + durable Memory entry. It is excluded from automatic Artifact generation and can support a Handoff only through + an exact Source citation. Capture does not end the session, expire older notes, or promote the note into Memory. + An exact replay of an accepted capture remains idempotent after its logical expiry. + operationId: capture_working_note + x-powercontext-access: {action: scope.contribute, resource: {type: scope, scope-id-from: scope_id}} + x-powercontext-scope-mode: current + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/CaptureWorkingNoteRequest" + responses: + "202": + description: The Working Note is durably stored as Source evidence. + 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" + "403": + $ref: "#/components/responses/Forbidden" + "422": + $ref: "#/components/responses/InvalidRequest" + "503": + $ref: "#/components/responses/Unavailable" + "500": + $ref: "#/components/responses/InternalError" /v1/source-definitions/register: post: tags: [source-ingestion] @@ -7397,6 +7439,47 @@ components: type: object additionalProperties: true nullable: true + description: >- + Caller metadata. The reserved kind value `working_note` is rejected; use the dedicated Working Note + capture operation instead. + WorkingNoteKind: + type: string + enum: [inspection, abandoned_approach, validation, unresolved, host_context] + CaptureWorkingNoteRequest: + type: object + additionalProperties: false + required: [scope_id, source_id, content, session_id, note_kind] + properties: + scope_id: + type: string + minLength: 1 + maxLength: 256 + pattern: '.*\S.*' + source_id: + type: string + minLength: 1 + maxLength: 256 + pattern: '.*\S.*' + content: + type: string + minLength: 1 + maxLength: 200000 + pattern: '.*\S.*' + session_id: + type: string + minLength: 1 + maxLength: 256 + pattern: '.*\S.*' + description: Host/session correlation only; it is not an authorization boundary. + note_kind: + $ref: "#/components/schemas/WorkingNoteKind" + expires_at: + type: string + format: date-time + nullable: true + description: >- + Optional logical expiry. It must be in the future when captured. Expiry makes the note unavailable to new + Handoff evidence resolution but does not physically delete or rewrite the Source. CaptureContentSourceResponse: type: object additionalProperties: false diff --git a/src/powercontext/cli/system.py b/src/powercontext/cli/system.py index 871c60b687..3d02608aaa 100644 --- a/src/powercontext/cli/system.py +++ b/src/powercontext/cli/system.py @@ -65,6 +65,7 @@ "activate_handoff", "capture_content_source", "change_atomic_memory_lifecycle", + "capture_working_note", "clear_scope_binding", "commit_handoff", "continue_handoff", diff --git a/src/powercontext/client/client.py b/src/powercontext/client/client.py index 0f2fa8b5ab..a3b327e615 100644 --- a/src/powercontext/client/client.py +++ b/src/powercontext/client/client.py @@ -52,6 +52,7 @@ Capabilities, CaptureContentSourceRequest, CaptureContentSourceResponse, + CaptureWorkingNoteRequest, ClearScopeBindingRequest, ClearScopeBindingResponse, CodeQueryRequest, @@ -212,6 +213,7 @@ ACTIVATE_HANDOFF, APPROVE_ARTIFACT_CANDIDATE, CAPTURE_CONTENT_SOURCE, + CAPTURE_WORKING_NOTE, CHECK_ACCESS, CLEAR_SCOPE_BINDING, COMMIT_CONNECTOR_CHECKPOINT, @@ -561,6 +563,11 @@ async def capture_content_source(self, request: CaptureContentSourceRequest) -> return await self._request(CAPTURE_CONTENT_SOURCE, request) + async def capture_working_note(self, request: CaptureWorkingNoteRequest) -> CaptureContentSourceResponse: + """Capture explicit session-local work state as Source evidence.""" + + return await self._request(CAPTURE_WORKING_NOTE, request) + async def get_access_principal(self) -> AccessMeResponse: """Return the authenticated Principal and enforceable Access capabilities.""" diff --git a/src/powercontext/http/__init__.py b/src/powercontext/http/__init__.py index 11a64d8793..aed1733a5e 100644 --- a/src/powercontext/http/__init__.py +++ b/src/powercontext/http/__init__.py @@ -95,6 +95,7 @@ CaptureContentSourceRequest, CaptureContentSourceResponse, CaptureStatus, + CaptureWorkingNoteRequest, ClearScopeBindingRequest, ClearScopeBindingResponse, CodeQueryRequest, @@ -439,6 +440,7 @@ WorkClaim, WorkClaimBasis, WorkContract, + WorkingNoteKind, WorkSourceKind, WorkSourceReceipt, ) @@ -524,6 +526,7 @@ "CaptureContentSourceRequest", "CaptureContentSourceResponse", "CaptureStatus", + "CaptureWorkingNoteRequest", "ClearScopeBindingRequest", "ClearScopeBindingResponse", "CodeQueryRequest", @@ -870,4 +873,5 @@ "WorkContract", "WorkSourceKind", "WorkSourceReceipt", + "WorkingNoteKind", ] diff --git a/src/powercontext/http/_generated/models.py b/src/powercontext/http/_generated/models.py index 503de9b187..bce6735e71 100644 --- a/src/powercontext/http/_generated/models.py +++ b/src/powercontext/http/_generated/models.py @@ -921,7 +921,45 @@ class CaptureContentSourceRequest(BaseModel): min_length=1, ), ] - metadata: dict[str, Any] | None = None + metadata: Annotated[ + dict[str, Any] | None, + Field( + description="Caller metadata. The reserved kind value `working_note` is rejected; use the dedicated Working Note capture operation instead." + ), + ] = None + + +class WorkingNoteKind(StrEnum): + INSPECTION = "inspection" + ABANDONED_APPROACH = "abandoned_approach" + VALIDATION = "validation" + UNRESOLVED = "unresolved" + HOST_CONTEXT = "host_context" + + +class CaptureWorkingNoteRequest(BaseModel): + model_config = ConfigDict( + extra="forbid", + ) + scope_id: Annotated[StrictStr, Field(max_length=256, min_length=1, pattern=".*\\S.*")] + source_id: Annotated[StrictStr, Field(max_length=256, min_length=1, pattern=".*\\S.*")] + content: Annotated[StrictStr, Field(max_length=200000, min_length=1, pattern=".*\\S.*")] + session_id: Annotated[ + StrictStr, + Field( + description="Host/session correlation only; it is not an authorization boundary.", + max_length=256, + min_length=1, + pattern=".*\\S.*", + ), + ] + note_kind: WorkingNoteKind + expires_at: Annotated[ + AwareDatetime | None, + Field( + description="Optional logical expiry. It must be in the future when captured. Expiry makes the note unavailable to new Handoff evidence resolution but does not physically delete or rewrite the Source." + ), + ] = None class SourceProjectionKey(BaseModel): diff --git a/src/powercontext/http/_generated/operations.py b/src/powercontext/http/_generated/operations.py index f095d0849c..f37f67db6b 100644 --- a/src/powercontext/http/_generated/operations.py +++ b/src/powercontext/http/_generated/operations.py @@ -38,6 +38,7 @@ Capabilities, CaptureContentSourceRequest, CaptureContentSourceResponse, + CaptureWorkingNoteRequest, ClearScopeBindingRequest, ClearScopeBindingResponse, CodeQueryRequest, @@ -917,6 +918,35 @@ class AccessRequirement(BaseModel): ), ) +CAPTURE_WORKING_NOTE = Operation[CaptureWorkingNoteRequest, CaptureContentSourceResponse]( + method="POST", + path="/v1/sources/working-notes", + operation_id="capture_working_note", + request_type=CaptureWorkingNoteRequest, + request_location="body", + path_parameters=(), + response_type=CaptureContentSourceResponse, + success_status=202, + summary="Capture session-local working evidence", + tags=("sources",), + scope_mode="current", + responses={ + 202: { + "description": "The Working Note is durably stored as Source evidence.", + "headers": {"X-PowerContext-Request-ID": {"$ref": "#/components/headers/RequestId"}}, + }, + 409: {"$ref": "#/components/responses/Conflict"}, + 401: {"$ref": "#/components/responses/Unauthorized"}, + 403: {"$ref": "#/components/responses/Forbidden"}, + 422: {"$ref": "#/components/responses/InvalidRequest"}, + 503: {"$ref": "#/components/responses/Unavailable"}, + 500: {"$ref": "#/components/responses/InternalError"}, + }, + access=AccessRequirement( + action="scope.contribute", resource="scope", scope_id_field="scope_id", resolver="request" + ), +) + REGISTER_SOURCE_DEFINITION = Operation[RegisterSourceDefinitionRequest, SourceDefinitionManifest]( method="POST", path="/v1/source-definitions/register", diff --git a/src/powercontext/http/_generated/schema.py b/src/powercontext/http/_generated/schema.py index 8976d14280..cadcba3106 100644 --- a/src/powercontext/http/_generated/schema.py +++ b/src/powercontext/http/_generated/schema.py @@ -958,6 +958,62 @@ "x-powercontext-scope-mode": "current", } }, + "/v1/sources/working-notes": { + "post": { + "tags": ["sources"], + "summary": "Capture session-local working evidence", + "description": "Explicitly capture a short-lived " + "Working Note as Source evidence. " + "Use this only when the user or " + "host flow asks to retain " + "intermediate work state such as " + "inspected files, an abandoned " + "approach, a validation result, " + "an unresolved question, or host " + "context. The note is untrusted " + "historical material, not an " + "instruction or a durable Memory " + "entry. It is excluded from " + "automatic Artifact generation " + "and can support a Handoff only " + "through an exact Source " + "citation. Capture does not end " + "the session, expire older notes, " + "or promote the note into Memory. " + "An exact replay of an accepted " + "capture remains idempotent after " + "its logical expiry.", + "operationId": "capture_working_note", + "requestBody": { + "content": { + "application/json": {"schema": {"$ref": "#/components/schemas/CaptureWorkingNoteRequest"}} + }, + "required": True, + }, + "responses": { + "202": { + "description": "The Working Note is durably stored as Source evidence.", + "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"}, + "403": {"$ref": "#/components/responses/Forbidden"}, + "422": {"$ref": "#/components/responses/InvalidRequest"}, + "503": {"$ref": "#/components/responses/Unavailable"}, + "500": {"$ref": "#/components/responses/InternalError"}, + }, + "x-powercontext-access": { + "action": "scope.contribute", + "resource": {"type": "scope", "scope-id-from": "scope_id"}, + }, + "x-powercontext-scope-mode": "current", + } + }, "/v1/source-definitions/register": { "post": { "tags": ["source-ingestion"], @@ -7164,12 +7220,90 @@ "dedicated " "workflow.", }, - "metadata": {"additionalProperties": True, "type": "object", "nullable": True}, + "metadata": { + "additionalProperties": True, + "type": "object", + "description": "Caller " + "metadata. " + "The " + "reserved " + "kind " + "value " + "`working_note` " + "is " + "rejected; " + "use " + "the " + "dedicated " + "Working " + "Note " + "capture " + "operation " + "instead.", + "nullable": True, + }, }, "additionalProperties": False, "type": "object", "required": ["scope_id", "source_id", "content"], }, + "WorkingNoteKind": { + "type": "string", + "enum": ["inspection", "abandoned_approach", "validation", "unresolved", "host_context"], + }, + "CaptureWorkingNoteRequest": { + "properties": { + "scope_id": {"type": "string", "maxLength": 256, "minLength": 1, "pattern": ".*\\S.*"}, + "source_id": {"type": "string", "maxLength": 256, "minLength": 1, "pattern": ".*\\S.*"}, + "content": {"type": "string", "maxLength": 200000, "minLength": 1, "pattern": ".*\\S.*"}, + "session_id": { + "type": "string", + "maxLength": 256, + "minLength": 1, + "pattern": ".*\\S.*", + "description": "Host/session correlation only; it is not an authorization boundary.", + }, + "note_kind": {"$ref": "#/components/schemas/WorkingNoteKind"}, + "expires_at": { + "type": "string", + "format": "date-time", + "description": "Optional " + "logical " + "expiry. " + "It " + "must " + "be " + "in " + "the " + "future " + "when " + "captured. " + "Expiry " + "makes " + "the " + "note " + "unavailable " + "to " + "new " + "Handoff " + "evidence " + "resolution " + "but " + "does " + "not " + "physically " + "delete " + "or " + "rewrite " + "the " + "Source.", + "nullable": True, + }, + }, + "additionalProperties": False, + "type": "object", + "required": ["scope_id", "source_id", "content", "session_id", "note_kind"], + }, "CaptureContentSourceResponse": { "properties": { "status": {"$ref": "#/components/schemas/CaptureStatus"}, diff --git a/src/powercontext/server/app.py b/src/powercontext/server/app.py index 7bb45d97be..edaacfa0c2 100644 --- a/src/powercontext/server/app.py +++ b/src/powercontext/server/app.py @@ -240,6 +240,9 @@ from powercontext.builtin.runtime import ( ApproveArtifactCandidateRequest as RuntimeApproveArtifactCandidateRequest, ) +from powercontext.builtin.runtime import ( + CaptureWorkingNote as RuntimeCaptureWorkingNote, +) from powercontext.builtin.runtime import ( CommitConnectorCheckpoint as RuntimeCommitConnectorCheckpoint, ) @@ -406,6 +409,7 @@ Capabilities, CaptureContentSourceRequest, CaptureContentSourceResponse, + CaptureWorkingNoteRequest, ClearScopeBindingRequest, ClearScopeBindingResponse, CodeQueryRequest, @@ -648,6 +652,7 @@ API_VERSION, APPROVE_ARTIFACT_CANDIDATE, CAPTURE_CONTENT_SOURCE, + CAPTURE_WORKING_NOTE, CHECK_ACCESS, CLEAR_SCOPE_BINDING, COMMIT_CONNECTOR_CHECKPOINT, @@ -834,6 +839,8 @@ class _ScopedSourceApplication(Protocol): async def capture(self, value: CaptureSource, /) -> SourceReceipt: ... + async def capture_working_note(self, value: RuntimeCaptureWorkingNote, /) -> SourceReceipt: ... + class _SourceApplication(Protocol): def for_scope(self, scope_id: str, /) -> _ScopedSourceApplication: ... @@ -1402,6 +1409,7 @@ async def unexpected_error(request: Request, error: Exception) -> JSONResponse: _add_route(app, GET_PROMPT_CONFIGURATION, get_prompt_configuration) _add_route(app, REPLACE_ARTIFACT, replace_artifact) _add_route(app, CAPTURE_CONTENT_SOURCE, capture_content_source) + _add_route(app, CAPTURE_WORKING_NOTE, capture_working_note) add_atomic_memory_routes( app, application_dependency=_require_application, @@ -2840,6 +2848,16 @@ async def capture_content_source( return mapping.capture_response(result) +async def capture_working_note( + request: CaptureWorkingNoteRequest, + application: Annotated[ServerApplication, Depends(_require_application)], +) -> CaptureContentSourceResponse: + result = await application.sources.for_scope(request.scope_id).capture_working_note( + mapping.working_note_capture_request(request) + ) + return mapping.capture_response(result) + + async def register_source_definition( request: RegisterSourceDefinitionRequest, application: Annotated[ServerApplication, Depends(_require_application)], diff --git a/src/powercontext/server/mapping.py b/src/powercontext/server/mapping.py index 803e6dec9b..636de687df 100644 --- a/src/powercontext/server/mapping.py +++ b/src/powercontext/server/mapping.py @@ -84,6 +84,9 @@ from powercontext.builtin.runtime import ( ApproveArtifactCandidateRequest as RuntimeApproveArtifactCandidateRequest, ) +from powercontext.builtin.runtime import ( + CaptureWorkingNote as RuntimeCaptureWorkingNote, +) from powercontext.builtin.runtime import ( CommitConnectorCheckpoint as RuntimeCommitConnectorCheckpoint, ) @@ -130,6 +133,7 @@ SubmitSourceObservation as RuntimeSubmitSourceObservation, ) from powercontext.builtin.runtime.atomic_memory import AtomicMemoryPage, AtomicMemorySearchPage +from powercontext.builtin.runtime import WorkingNoteKind as RuntimeWorkingNoteKind from powercontext.builtin.sources import ExternalSkillImportMode as RuntimeExternalSkillImportMode from powercontext.builtin.work import ( AcknowledgeHandoff as RuntimeAcknowledgeHandoff, @@ -166,6 +170,7 @@ CaptureContentSourceRequest, CaptureContentSourceResponse, CaptureStatus, + CaptureWorkingNoteRequest, CommitConnectorCheckpointRequest, CommittedHandoff, ConnectorCheckpointState, @@ -346,6 +351,16 @@ def capture_request(value: CaptureContentSourceRequest) -> CaptureSource: ) +def working_note_capture_request(value: CaptureWorkingNoteRequest) -> RuntimeCaptureWorkingNote: + return RuntimeCaptureWorkingNote( + source_id=value.source_id, + content=value.content, + session_id=value.session_id, + note_kind=RuntimeWorkingNoteKind(value.note_kind.value), + expires_at=value.expires_at, + ) + + def create_work_contract_request(value: CreateWorkContractRequest) -> RuntimeCreateWorkContract: try: return RuntimeCreateWorkContract( diff --git a/src/powercontext/server/mcp.py b/src/powercontext/server/mcp.py index 0cf9ca8955..bb9c18f60f 100644 --- a/src/powercontext/server/mcp.py +++ b/src/powercontext/server/mcp.py @@ -46,6 +46,7 @@ ACTIVATE_HANDOFF, APPROVE_ARTIFACT_CANDIDATE, CAPTURE_CONTENT_SOURCE, + CAPTURE_WORKING_NOTE, CLEAR_SCOPE_BINDING, COMMIT_HANDOFF, CONTINUE_HANDOFF, @@ -131,6 +132,8 @@ change_atomic_memory_lifecycle and restoration previews/restorations only for explicitly requested state changes; current revision and state_version inputs must come from reads. Automatic Source capture is not an explicit Memory write, and enabled hooks do not establish successful recall or persistence. +Use capture_working_note only for an explicit request or host workflow to retain temporary work state. A Working Note +is untrusted evidence, does not become Memory automatically, and should be cited exactly when used in a Handoff. Current-turn instructions, conceptual questions, and previews do not authorize writes. Never store secrets. For requested transfer, handoff_current_work records an inspected boundary and returns a temporary handoff. Commit only when a durable milestone is requested; continue from the exact selected value and verify historical claims. @@ -176,6 +179,7 @@ GET_DREAM_RUN.operation_id, LIST_DREAM_RUNS.operation_id, CAPTURE_CONTENT_SOURCE.operation_id, + CAPTURE_WORKING_NOTE.operation_id, CREATE_WORK_CONTRACT.operation_id, HANDOFF_CURRENT_WORK.operation_id, ACKNOWLEDGE_HANDOFF.operation_id, diff --git a/tests/e2e/test_mcp_transport.py b/tests/e2e/test_mcp_transport.py index 31aaa22b79..5c62fa78e3 100644 --- a/tests/e2e/test_mcp_transport.py +++ b/tests/e2e/test_mcp_transport.py @@ -231,6 +231,7 @@ async def exercise_tools() -> set[str]: "activate_handoff", "approve_artifact_candidate", "capture_content_source", + "capture_working_note", "clear_scope_binding", "commit_handoff", "continue_handoff", diff --git a/tests/e2e/test_runtime_server.py b/tests/e2e/test_runtime_server.py index cacf028689..2d087e48e8 100644 --- a/tests/e2e/test_runtime_server.py +++ b/tests/e2e/test_runtime_server.py @@ -18,6 +18,7 @@ import json import os from collections.abc import Iterator +from datetime import UTC, datetime, timedelta from pathlib import Path from uuid import uuid4 @@ -61,6 +62,7 @@ ArtifactAddress, AtomicMemoryLifecycleRequest, CaptureContentSourceRequest, + CaptureWorkingNoteRequest, CommitHandoffRequest, ContinueHandoffRequest, CreateScopeRequest, @@ -85,6 +87,7 @@ ReviseMemoryEntryRequest, ScopeSelection, SearchMemoryRequest, + WorkingNoteKind, ) from powercontext.http import MemorySearchMode as HttpMemorySearchMode from powercontext.server.factory import create_server_app @@ -280,6 +283,87 @@ async def scenario() -> None: asyncio.run(scenario()) +def test_working_note_http_and_sdk_capture_stays_out_of_memory(tmp_path: Path) -> None: + app = create_server_app( + settings=_server_settings(tmp_path / "working-note.db"), + candidate_pipeline=ContentCandidatePipeline(), + ) + + async def scenario() -> None: + async with ( + app.router.lifespan_context(app), + httpx.AsyncClient( + transport=httpx.ASGITransport(app=app), + base_url="http://testserver", + ) as transport, + ): + client = PowerContextClient("http://testserver", http_client=transport, trust_transport_security=True) + scope = await client.create_scope( + CreateScopeRequest( + title="Working note", + summary="Session-local evidence", + idempotency_key="working-note-http", + ) + ) + with pytest.raises(ServerResponseError) as reserved_metadata: + await client.capture_content_source( + CaptureContentSourceRequest( + scope_id=scope.scope_id, + source_id="spoofed-note", + content="Generic capture cannot assign a server-owned Source kind.", + metadata={"kind": "working_note"}, + ) + ) + working_note_metadata = await transport.post( + "/v1/sources/working-notes", + json={ + "scope_id": scope.scope_id, + "source_id": "metadata-expiry", + "content": "The public contract does not expose Working Note metadata.", + "session_id": "session-1", + "note_kind": "validation", + "metadata": {"expires_at": "2000-01-01T00:00:00+00:00"}, + }, + ) + captured = await client.capture_working_note( + CaptureWorkingNoteRequest( + scope_id=scope.scope_id, + source_id="note-1", + content="The database migration probe passed locally.", + session_id="session-1", + note_kind=WorkingNoteKind.VALIDATION, + expires_at=datetime.now(UTC) + timedelta(days=1), + ) + ) + with pytest.raises(ServerResponseError) as expired: + await client.capture_working_note( + CaptureWorkingNoteRequest( + scope_id=scope.scope_id, + source_id="note-expired", + content="This note is already stale.", + session_id="session-1", + note_kind=WorkingNoteKind.VALIDATION, + expires_at=datetime.now(UTC) - timedelta(days=1), + ) + ) + flushed = await client.flush_memory(FlushMemoryRequest(scope_id=scope.scope_id)) + entries = await client.list_memory_entries(ListMemoryEntriesRequest(scope_id=scope.scope_id)) + + assert captured.source.name == "content" + assert reserved_metadata.value.status_code == 422 + assert reserved_metadata.value.code == "invalid_request" + assert working_note_metadata.status_code == 422 + assert working_note_metadata.json()["error"]["code"] == "invalid_request" + assert captured.position == 1 + assert captured.position == flushed.current_cursor + assert expired.value.status_code == 422 + assert expired.value.code == "invalid_request" + assert flushed.memory is None + assert entries.entries == [] + + asyncio.run(scenario()) + + @pytest.mark.parametrize("database_kind", ["sqlite", "oceanbase"]) def test_server_databases_keep_case_and_accent_variant_identities_distinct( database: SQLiteConfig | OceanBaseConfig, diff --git a/tests/test_api_contract.py b/tests/test_api_contract.py index 73e0983053..08128a085d 100644 --- a/tests/test_api_contract.py +++ b/tests/test_api_contract.py @@ -31,6 +31,7 @@ ArtifactRevision, CaptureContentSourceRequest, CaptureContentSourceResponse, + CaptureWorkingNoteRequest, CommitHandoffRequest, CommittedHandoff, ContinueHandoffRequest, @@ -92,6 +93,7 @@ ACTIVATE_HANDOFF, APPROVE_ARTIFACT_CANDIDATE, CAPTURE_CONTENT_SOURCE, + CAPTURE_WORKING_NOTE, COMMIT_HANDOFF, CONTINUE_HANDOFF, CREATE_ARTIFACT, @@ -340,6 +342,9 @@ def test_capture_operation_declares_its_typed_accepted_exchange() -> None: assert CAPTURE_CONTENT_SOURCE.request_type is CaptureContentSourceRequest assert CAPTURE_CONTENT_SOURCE.response_type is CaptureContentSourceResponse assert CAPTURE_CONTENT_SOURCE.success_status == 202 + assert CAPTURE_WORKING_NOTE.request_type is CaptureWorkingNoteRequest + assert CAPTURE_WORKING_NOTE.response_type is CaptureContentSourceResponse + assert CAPTURE_WORKING_NOTE.success_status == 202 def test_topic_memory_operations_use_strict_public_shapes_without_retrieval_controls() -> None: diff --git a/tests/test_mcp.py b/tests/test_mcp.py index d21641ba0f..102f956c41 100644 --- a/tests/test_mcp.py +++ b/tests/test_mcp.py @@ -97,6 +97,7 @@ async def inspect_components() -> tuple[list[str], int, int]: "acknowledge_handoff", "approve_artifact_candidate", "capture_content_source", + "capture_working_note", "clear_scope_binding", "commit_handoff", "continue_handoff", From e05850f70a27aea970fdae7edf6ff7d1115b277d Mon Sep 17 00:00:00 2001 From: qyq316 <19606363088@163.com> Date: Mon, 12 Oct 2026 12:01:35 +0800 Subject: [PATCH 04/11] chore: adapt working notes to current master --- src/powercontext/builtin/runtime/__init__.py | 2 +- src/powercontext/server/mapping.py | 2 +- tests/e2e/test_builtin_runtime.py | 7 ++++--- tests/e2e/test_handoff_runtime.py | 1 - tests/e2e/test_runtime_server.py | 2 +- 5 files changed, 7 insertions(+), 7 deletions(-) diff --git a/src/powercontext/builtin/runtime/__init__.py b/src/powercontext/builtin/runtime/__init__.py index 1fc8f30bdb..415521c047 100644 --- a/src/powercontext/builtin/runtime/__init__.py +++ b/src/powercontext/builtin/runtime/__init__.py @@ -401,8 +401,8 @@ "TopicMemoryProcessingUnavailableError", "UsageStatistics", "WorkApplication", - "assess_decision_result", "WorkingNoteKind", + "assess_decision_result", "build_memory_write_gate", "dependency_readiness_probe", "open_builtin_contexts", diff --git a/src/powercontext/server/mapping.py b/src/powercontext/server/mapping.py index 636de687df..70cb612aef 100644 --- a/src/powercontext/server/mapping.py +++ b/src/powercontext/server/mapping.py @@ -132,8 +132,8 @@ from powercontext.builtin.runtime import ( SubmitSourceObservation as RuntimeSubmitSourceObservation, ) -from powercontext.builtin.runtime.atomic_memory import AtomicMemoryPage, AtomicMemorySearchPage from powercontext.builtin.runtime import WorkingNoteKind as RuntimeWorkingNoteKind +from powercontext.builtin.runtime.atomic_memory import AtomicMemoryPage, AtomicMemorySearchPage from powercontext.builtin.sources import ExternalSkillImportMode as RuntimeExternalSkillImportMode from powercontext.builtin.work import ( AcknowledgeHandoff as RuntimeAcknowledgeHandoff, diff --git a/tests/e2e/test_builtin_runtime.py b/tests/e2e/test_builtin_runtime.py index 8581c868c6..a5a6c7f373 100644 --- a/tests/e2e/test_builtin_runtime.py +++ b/tests/e2e/test_builtin_runtime.py @@ -44,7 +44,7 @@ open_builtin_runtime, ) from powercontext.builtin.scope import ScopeDraft, ScopeMutation, ScopeNotFoundError -from powercontext.builtin.sources import CONTENT_SOURCE_DEFINITION, ContentCapture, ContentSource +from powercontext.builtin.sources import CONTENT_SOURCE_DEFINITION, ContentCapture from powercontext.errors import SourceConflictError from powercontext.sources import ConnectorBinding, SourceDefinitionRegistry, project_source_for_transport from tests.e2e.dream_support import atomic_memory_pipeline, memory_source_text @@ -178,7 +178,7 @@ def test_working_note_capture_does_not_promote_into_memory() -> None: async def scenario() -> None: async with open_builtin_runtime( BuiltinConfig(database=SQLiteConfig()), - candidate_pipeline=_ContentCandidatePipeline(), + candidate_pipeline=atomic_memory_pipeline(_ContentCandidatePipeline()), ) as runtime: assert runtime.scopes is not None scope = await runtime.scopes.create( @@ -249,7 +249,8 @@ async def scenario() -> None: ) ) - flushed = await runtime.memory.for_scope(scope.scope_id).flush() + assert runtime.atomic_memory is not None + flushed = await runtime.atomic_memory.for_scope(scope.scope_id).flush() assert replayed == captured assert expired_replay == captured diff --git a/tests/e2e/test_handoff_runtime.py b/tests/e2e/test_handoff_runtime.py index 0ff3037a0c..318d3b15da 100644 --- a/tests/e2e/test_handoff_runtime.py +++ b/tests/e2e/test_handoff_runtime.py @@ -45,7 +45,6 @@ HandoffStatement, InferenceConfig, PreparedHandoff, - RememberMemoryRequest, WorkingNoteKind, open_builtin_runtime, ) diff --git a/tests/e2e/test_runtime_server.py b/tests/e2e/test_runtime_server.py index 2d087e48e8..3c81f86687 100644 --- a/tests/e2e/test_runtime_server.py +++ b/tests/e2e/test_runtime_server.py @@ -286,7 +286,7 @@ async def scenario() -> None: def test_working_note_http_and_sdk_capture_stays_out_of_memory(tmp_path: Path) -> None: app = create_server_app( settings=_server_settings(tmp_path / "working-note.db"), - candidate_pipeline=ContentCandidatePipeline(), + candidate_pipeline=atomic_memory_pipeline(ContentCandidatePipeline()), ) async def scenario() -> None: From 0d84457061c0900ee03148da25858792d9eead49 Mon Sep 17 00:00:00 2001 From: qyq316 <19606363088@163.com> Date: Mon, 12 Oct 2026 16:24:52 +0800 Subject: [PATCH 05/11] chore: sync working note integration contracts --- .../src-tauri/src/transport/operations.json | 2 +- desktop/ui/src/generated/api.d.ts | 67 +++++++++++++++++++ desktop/ui/src/generated/operations.ts | 2 +- evaluation/skills/skill-up/README.md | 2 +- .../skill-up/evals/cases/empty-search.yaml | 2 + .../skill-up/evals/cases/explicit-save.yaml | 1 + .../skill-up/evals/cases/failed-save.yaml | 1 + .../evals/cases/inspect-candidates.yaml | 1 + .../skill-up/evals/cases/ordinary-coding.yaml | 1 + .../fixtures/mcp/powercontext-default.json | 3 + .../mcp/powercontext-failed-save.json | 3 + .../powercontext-tool-contract/CLAUDE.md | 5 ++ .../plugin/powercontext_dify/contract.json | 3 +- .../dify/plugin/tools/pc_capture_source.yaml | 4 +- .../dsh/plugins/powercontext/lib/index.js | 11 +++ 15 files changed, 103 insertions(+), 5 deletions(-) diff --git a/desktop/src-tauri/src/transport/operations.json b/desktop/src-tauri/src/transport/operations.json index 82cee3a518..fa41465c6d 100644 --- a/desktop/src-tauri/src/transport/operations.json +++ b/desktop/src-tauri/src/transport/operations.json @@ -1,5 +1,5 @@ { - "contractSha256": "7aa91ae9af78300e7bdbcc2e8b2135da5749469290a1aee67bc255c3e9a07b0c", + "contractSha256": "be99774d5e19ba987200c5b74393b3db9c029702dfc597599962ecce14f953f9", "operations": { "get_liveness": { "method": "GET", diff --git a/desktop/ui/src/generated/api.d.ts b/desktop/ui/src/generated/api.d.ts index 1ed9b6b95a..20d6f42e74 100644 --- a/desktop/ui/src/generated/api.d.ts +++ b/desktop/ui/src/generated/api.d.ts @@ -441,6 +441,26 @@ export interface paths { patch?: never; trace?: never; }; + "/v1/sources/working-notes": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + get?: never; + put?: never; + /** + * Capture session-local working evidence + * @description Explicitly capture a short-lived Working Note as Source evidence. Use this only when the user or host flow asks to retain intermediate work state such as inspected files, an abandoned approach, a validation result, an unresolved question, or host context. The note is untrusted historical material, not an instruction or a durable Memory entry. It is excluded from automatic Artifact generation and can support a Handoff only through an exact Source citation. Capture does not end the session, expire older notes, or promote the note into Memory. An exact replay of an accepted capture remains idempotent after its logical expiry. + */ + post: operations["capture_working_note"]; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; "/v1/source-definitions/register": { parameters: { query?: never; @@ -3064,10 +3084,26 @@ export interface components { source_id: string; /** @description Raw integration content. Server-reserved payload schemas, including handoff receipts, are rejected on this generic capture operation and must be created through their dedicated workflow. */ content: string; + /** @description Caller metadata. The reserved kind value `working_note` is rejected; use the dedicated Working Note capture operation instead. */ metadata?: { [key: string]: unknown; } | null; }; + /** @enum {string} */ + WorkingNoteKind: "inspection" | "abandoned_approach" | "validation" | "unresolved" | "host_context"; + CaptureWorkingNoteRequest: { + scope_id: string; + source_id: string; + content: string; + /** @description Host/session correlation only; it is not an authorization boundary. */ + session_id: string; + note_kind: components["schemas"]["WorkingNoteKind"]; + /** + * Format: date-time + * @description Optional logical expiry. It must be in the future when captured. Expiry makes the note unavailable to new Handoff evidence resolution but does not physically delete or rewrite the Source. + */ + expires_at?: string | null; + }; CaptureContentSourceResponse: { status: components["schemas"]["CaptureStatus"]; source: components["schemas"]["SourceReference"]; @@ -5731,6 +5767,37 @@ export interface operations { 503: components["responses"]["Unavailable"]; }; }; + capture_working_note: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody: { + content: { + "application/json": components["schemas"]["CaptureWorkingNoteRequest"]; + }; + }; + responses: { + /** @description The Working Note is durably stored as Source evidence. */ + 202: { + headers: { + "X-PowerContext-Request-ID": components["headers"]["RequestId"]; + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["CaptureContentSourceResponse"]; + }; + }; + 401: components["responses"]["Unauthorized"]; + 403: components["responses"]["Forbidden"]; + 409: components["responses"]["Conflict"]; + 422: components["responses"]["InvalidRequest"]; + 500: components["responses"]["InternalError"]; + 503: components["responses"]["Unavailable"]; + }; + }; register_source_definition: { parameters: { query?: never; diff --git a/desktop/ui/src/generated/operations.ts b/desktop/ui/src/generated/operations.ts index ea299aa267..5f6adef532 100644 --- a/desktop/ui/src/generated/operations.ts +++ b/desktop/ui/src/generated/operations.ts @@ -15,7 +15,7 @@ */ // Generated from openapi/powercontext.yaml. Do not edit. -export const contractSha256 = "7aa91ae9af78300e7bdbcc2e8b2135da5749469290a1aee67bc255c3e9a07b0c"; +export const contractSha256 = "be99774d5e19ba987200c5b74393b3db9c029702dfc597599962ecce14f953f9"; export const operations = { "get_liveness": { "method": "GET", diff --git a/evaluation/skills/skill-up/README.md b/evaluation/skills/skill-up/README.md index 84c61d868e..5c49182140 100644 --- a/evaluation/skills/skill-up/README.md +++ b/evaluation/skills/skill-up/README.md @@ -101,7 +101,7 @@ All relative config paths start at this project root, not at `evals/`. Both arms receive the same `evals/fixtures/repos/powercontext-tool-contract/CLAUDE.md`: required/optional top-level argument names, types and defaults derived from OpenAPI and its MCP specialization, including content CAS headers. -The mock catalog contains the Server's complete declared MCP tool subset (54 operations), verified against +The mock catalog contains the Server's complete declared MCP tool subset (55 operations), verified against `src/powercontext/server/mcp.py` and the generated operation IDs. The successful save reply contains Atomic `records`; empty search returns the current `text` mode and an empty `hits` list. This fills the generic mock schemas' parameter information gap diff --git a/evaluation/skills/skill-up/evals/cases/empty-search.yaml b/evaluation/skills/skill-up/evals/cases/empty-search.yaml index d7c6753bd4..81f8550bdd 100644 --- a/evaluation/skills/skill-up/evals/cases/empty-search.yaml +++ b/evaluation/skills/skill-up/evals/cases/empty-search.yaml @@ -51,6 +51,7 @@ judge: - tool_not_called_in_turn: {turn: 1, name: mcp__powercontext__activate_handoff} - tool_not_called_in_turn: {turn: 1, name: mcp__powercontext__approve_artifact_candidate} - tool_not_called_in_turn: {turn: 1, name: mcp__powercontext__capture_content_source} + - tool_not_called_in_turn: {turn: 1, name: mcp__powercontext__capture_working_note} - tool_not_called_in_turn: {turn: 1, name: mcp__powercontext__clear_scope_binding} - tool_not_called_in_turn: {turn: 1, name: mcp__powercontext__commit_handoff} - tool_not_called_in_turn: {turn: 1, name: mcp__powercontext__continue_handoff} @@ -80,6 +81,7 @@ judge: - tool_not_called_in_turn: {turn: 2, name: mcp__powercontext__activate_handoff} - tool_not_called_in_turn: {turn: 2, name: mcp__powercontext__approve_artifact_candidate} - tool_not_called_in_turn: {turn: 2, name: mcp__powercontext__capture_content_source} + - tool_not_called_in_turn: {turn: 2, name: mcp__powercontext__capture_working_note} - tool_not_called_in_turn: {turn: 2, name: mcp__powercontext__clear_scope_binding} - tool_not_called_in_turn: {turn: 2, name: mcp__powercontext__commit_handoff} - tool_not_called_in_turn: {turn: 2, name: mcp__powercontext__continue_handoff} diff --git a/evaluation/skills/skill-up/evals/cases/explicit-save.yaml b/evaluation/skills/skill-up/evals/cases/explicit-save.yaml index 8e9cf90aab..8ab19978d2 100644 --- a/evaluation/skills/skill-up/evals/cases/explicit-save.yaml +++ b/evaluation/skills/skill-up/evals/cases/explicit-save.yaml @@ -44,6 +44,7 @@ judge: - tool_not_called_in_turn: {turn: 1, name: mcp__powercontext__activate_handoff} - tool_not_called_in_turn: {turn: 1, name: mcp__powercontext__approve_artifact_candidate} - tool_not_called_in_turn: {turn: 1, name: mcp__powercontext__capture_content_source} + - tool_not_called_in_turn: {turn: 1, name: mcp__powercontext__capture_working_note} - tool_not_called_in_turn: {turn: 1, name: mcp__powercontext__clear_scope_binding} - tool_not_called_in_turn: {turn: 1, name: mcp__powercontext__commit_handoff} - tool_not_called_in_turn: {turn: 1, name: mcp__powercontext__continue_handoff} diff --git a/evaluation/skills/skill-up/evals/cases/failed-save.yaml b/evaluation/skills/skill-up/evals/cases/failed-save.yaml index c6a121d9db..a957365ebe 100644 --- a/evaluation/skills/skill-up/evals/cases/failed-save.yaml +++ b/evaluation/skills/skill-up/evals/cases/failed-save.yaml @@ -60,6 +60,7 @@ judge: - tool_not_called_in_turn: {turn: 1, name: mcp__powercontext__activate_handoff} - tool_not_called_in_turn: {turn: 1, name: mcp__powercontext__approve_artifact_candidate} - tool_not_called_in_turn: {turn: 1, name: mcp__powercontext__capture_content_source} + - tool_not_called_in_turn: {turn: 1, name: mcp__powercontext__capture_working_note} - tool_not_called_in_turn: {turn: 1, name: mcp__powercontext__clear_scope_binding} - tool_not_called_in_turn: {turn: 1, name: mcp__powercontext__commit_handoff} - tool_not_called_in_turn: {turn: 1, name: mcp__powercontext__continue_handoff} diff --git a/evaluation/skills/skill-up/evals/cases/inspect-candidates.yaml b/evaluation/skills/skill-up/evals/cases/inspect-candidates.yaml index 5b1e0d2fca..0da5e03d5d 100644 --- a/evaluation/skills/skill-up/evals/cases/inspect-candidates.yaml +++ b/evaluation/skills/skill-up/evals/cases/inspect-candidates.yaml @@ -48,6 +48,7 @@ judge: - tool_not_called_in_turn: {turn: 1, name: mcp__powercontext__activate_handoff} - tool_not_called_in_turn: {turn: 1, name: mcp__powercontext__approve_artifact_candidate} - tool_not_called_in_turn: {turn: 1, name: mcp__powercontext__capture_content_source} + - tool_not_called_in_turn: {turn: 1, name: mcp__powercontext__capture_working_note} - tool_not_called_in_turn: {turn: 1, name: mcp__powercontext__clear_scope_binding} - tool_not_called_in_turn: {turn: 1, name: mcp__powercontext__commit_handoff} - tool_not_called_in_turn: {turn: 1, name: mcp__powercontext__continue_handoff} diff --git a/evaluation/skills/skill-up/evals/cases/ordinary-coding.yaml b/evaluation/skills/skill-up/evals/cases/ordinary-coding.yaml index 26b8ca4f1a..f4b1146f63 100644 --- a/evaluation/skills/skill-up/evals/cases/ordinary-coding.yaml +++ b/evaluation/skills/skill-up/evals/cases/ordinary-coding.yaml @@ -35,6 +35,7 @@ judge: - tool_not_called_in_turn: {turn: 1, name: mcp__powercontext__activate_handoff} - tool_not_called_in_turn: {turn: 1, name: mcp__powercontext__approve_artifact_candidate} - tool_not_called_in_turn: {turn: 1, name: mcp__powercontext__capture_content_source} + - tool_not_called_in_turn: {turn: 1, name: mcp__powercontext__capture_working_note} - tool_not_called_in_turn: {turn: 1, name: mcp__powercontext__clear_scope_binding} - tool_not_called_in_turn: {turn: 1, name: mcp__powercontext__commit_handoff} - tool_not_called_in_turn: {turn: 1, name: mcp__powercontext__continue_handoff} diff --git a/evaluation/skills/skill-up/evals/fixtures/mcp/powercontext-default.json b/evaluation/skills/skill-up/evals/fixtures/mcp/powercontext-default.json index a2695ac5b3..32af29378e 100644 --- a/evaluation/skills/skill-up/evals/fixtures/mcp/powercontext-default.json +++ b/evaluation/skills/skill-up/evals/fixtures/mcp/powercontext-default.json @@ -12,6 +12,9 @@ "capture_content_source": { "error": "unexpected" }, + "capture_working_note": { + "error": "unexpected" + }, "change_atomic_memory_lifecycle": { "error": "unexpected" }, diff --git a/evaluation/skills/skill-up/evals/fixtures/mcp/powercontext-failed-save.json b/evaluation/skills/skill-up/evals/fixtures/mcp/powercontext-failed-save.json index b5cbbc182b..824cd25ac2 100644 --- a/evaluation/skills/skill-up/evals/fixtures/mcp/powercontext-failed-save.json +++ b/evaluation/skills/skill-up/evals/fixtures/mcp/powercontext-failed-save.json @@ -12,6 +12,9 @@ "capture_content_source": { "error": "unexpected" }, + "capture_working_note": { + "error": "unexpected" + }, "change_atomic_memory_lifecycle": { "error": "unexpected" }, diff --git a/evaluation/skills/skill-up/evals/fixtures/repos/powercontext-tool-contract/CLAUDE.md b/evaluation/skills/skill-up/evals/fixtures/repos/powercontext-tool-contract/CLAUDE.md index 2f518c1ca6..2c081c6dca 100644 --- a/evaluation/skills/skill-up/evals/fixtures/repos/powercontext-tool-contract/CLAUDE.md +++ b/evaluation/skills/skill-up/evals/fixtures/repos/powercontext-tool-contract/CLAUDE.md @@ -30,6 +30,11 @@ not replace those schemas or enforce their constraints. It contains no scenario - Required: `content: string`, `scope_id: string`, `source_id: string`. - Optional: `metadata: object | null`. +## mcp__powercontext__capture_working_note + +- Required: `content: string`, `note_kind: "inspection" | "abandoned_approach" | "validation" | "unresolved" | "host_context"`, `scope_id: string`, `session_id: string`, `source_id: string`. +- Optional: `expires_at: string | null`. + ## mcp__powercontext__change_atomic_memory_lifecycle - Required: `scope_id: string`, `state: "forgotten"`, `target: AtomicMemoryInput`. diff --git a/integrations/dify/plugin/powercontext_dify/contract.json b/integrations/dify/plugin/powercontext_dify/contract.json index 6ff7a30035..91324fc997 100644 --- a/integrations/dify/plugin/powercontext_dify/contract.json +++ b/integrations/dify/plugin/powercontext_dify/contract.json @@ -1388,7 +1388,8 @@ "anyOf": [ { "type": "object", - "additionalProperties": true + "additionalProperties": true, + "description": "Caller metadata. The reserved kind value `working_note` is rejected; use the dedicated Working Note capture operation instead." }, { "type": "null" diff --git a/integrations/dify/plugin/tools/pc_capture_source.yaml b/integrations/dify/plugin/tools/pc_capture_source.yaml index 1b9e2ae300..3eaa48b9aa 100644 --- a/integrations/dify/plugin/tools/pc_capture_source.yaml +++ b/integrations/dify/plugin/tools/pc_capture_source.yaml @@ -67,7 +67,9 @@ parameters: to dify. Pass one JSON-encoded value as text, never a native object/array/null. Encode strings with JSON quotes; use the text null for null; omit optional inputs when unused. Decode exactly once and preserve every field. Decoded JSON Schema: - {"anyOf":[{"type":"object","additionalProperties":true},{"type":"null"}]}' + {"anyOf":[{"type":"object","additionalProperties":true,"description":"Caller metadata. + The reserved kind value `working_note` is rejected; use the dedicated Working + Note capture operation instead."},{"type":"null"}]}' output_schema: type: object properties: diff --git a/integrations/dsh/plugins/powercontext/lib/index.js b/integrations/dsh/plugins/powercontext/lib/index.js index 5c527a7a21..ba23dabcd6 100644 --- a/integrations/dsh/plugins/powercontext/lib/index.js +++ b/integrations/dsh/plugins/powercontext/lib/index.js @@ -465,6 +465,17 @@ const OPERATIONS$1 = { successStatuses: [202], emptyStatuses: [] }, + capture_working_note: { + method: "POST", + path: "/v1/sources/working-notes", + location: "body", + scopeMode: "current", + pathParameters: [], + queryParams: [], + headerParams: [], + successStatuses: [202], + emptyStatuses: [] + }, register_source_definition: { method: "POST", path: "/v1/source-definitions/register", From 1dbacfddcf89c32572bd9836043bcd01cc5b4c01 Mon Sep 17 00:00:00 2001 From: qyq316 <19606363088@163.com> Date: Tue, 13 Oct 2026 10:58:21 +0800 Subject: [PATCH 06/11] fix(handoff): allow exact working note lineage --- .../builtin/persistence/artifacts.py | 32 +++++++++++++++++-- .../builtin/persistence/generation_sources.py | 13 ++------ .../builtin/persistence/handoff.py | 2 ++ .../builtin/source_eligibility.py | 5 +++ tests/e2e/test_handoff_runtime.py | 8 +++++ 5 files changed, 46 insertions(+), 14 deletions(-) diff --git a/src/powercontext/builtin/persistence/artifacts.py b/src/powercontext/builtin/persistence/artifacts.py index 8e16a20afa..ac052f62b7 100644 --- a/src/powercontext/builtin/persistence/artifacts.py +++ b/src/powercontext/builtin/persistence/artifacts.py @@ -105,6 +105,8 @@ async def create( artifact_id: str, draft: ArtifactDraft[Any] | RepositoryArtifactDraft, /, + *, + allow_working_notes: bool = False, ) -> Artifact[Any]: """Create revision one, rejecting an already existing lifecycle.""" @@ -112,7 +114,13 @@ async def create( artifact_type = self._artifact_type(draft.family) self._require_content(draft.family, draft.content) ref = ArtifactRef(family=draft.family, artifact_id=artifact_id, revision=1) - await self._validate_lineage_sources(connection, scope_id, ref, draft.sources) + await self._validate_lineage_sources( + connection, + scope_id, + ref, + draft.sources, + allow_working_notes=allow_working_notes, + ) conflict = await self._head_conflict(connection, scope_id, ref, draft) if conflict is not None: raise conflict @@ -249,10 +257,18 @@ async def revise( artifact: Artifact[Any], draft: ArtifactDraft[Any] | RepositoryArtifactDraft, /, + *, + allow_working_notes: bool = False, ) -> Artifact[Any]: """Commit a next revision only when ``artifact`` remains the head.""" - return await self._revise(connection, scope_id, artifact, draft) + return await self._revise( + connection, + scope_id, + artifact, + draft, + allow_working_notes=allow_working_notes, + ) async def revise_for_restoration( self, @@ -281,6 +297,7 @@ async def _revise( draft: ArtifactDraft[Any] | RepositoryArtifactDraft, *, restoration: ArtifactGovernance | None = None, + allow_working_notes: bool = False, ) -> Artifact[Any]: _require_scope(scope_id) artifact_type = self._artifact_type(artifact.family) @@ -292,7 +309,13 @@ async def _revise( artifact_id=artifact.artifact_id, revision=artifact.revision + 1, ) - await self._validate_lineage_sources(connection, scope_id, target, draft.sources) + await self._validate_lineage_sources( + connection, + scope_id, + target, + draft.sources, + allow_working_notes=allow_working_notes, + ) locked = await connection.execute( update(ARTIFACT_HEADS_TABLE) @@ -917,6 +940,8 @@ async def _validate_lineage_sources( scope_id: str, target: ArtifactRef, sources: tuple[SourceRef, ...], + *, + allow_working_notes: bool = False, ) -> None: if self._sources is None: return @@ -931,6 +956,7 @@ async def _validate_lineage_sources( artifact_id=target.artifact_id, revision=target.revision, ), + allow_working_notes=allow_working_notes, ) diff --git a/src/powercontext/builtin/persistence/generation_sources.py b/src/powercontext/builtin/persistence/generation_sources.py index 4fb4c2657b..66c2fabb1d 100644 --- a/src/powercontext/builtin/persistence/generation_sources.py +++ b/src/powercontext/builtin/persistence/generation_sources.py @@ -21,12 +21,7 @@ from sqlalchemy.ext.asyncio import AsyncConnection from powercontext.builtin.persistence.sources import SourceRepository, StoredSource -from powercontext.builtin.source_eligibility import ( - WorkingNoteUnavailableError, - is_generation_eligible, - require_source_eligible, -) -from powercontext.builtin.sources import ContentSource +from powercontext.builtin.source_eligibility import is_generation_eligible, require_source_eligible from powercontext.sources import SourceRef @@ -49,11 +44,7 @@ async def require_for_generation( rows = await self._repository.get_many(connection, scope_id, refs) for row in rows: - if allow_working_notes and isinstance(row.value, ContentSource) and row.value.is_working_note: - if row.value.is_working_note_active(): - continue - raise WorkingNoteUnavailableError(row.ref) - require_source_eligible(row.ref, row.value) + require_source_eligible(row.ref, row.value, allow_working_notes=allow_working_notes) return rows async def list_window_for_generation( diff --git a/src/powercontext/builtin/persistence/handoff.py b/src/powercontext/builtin/persistence/handoff.py index 9b6104d05b..e0332f52f2 100644 --- a/src/powercontext/builtin/persistence/handoff.py +++ b/src/powercontext/builtin/persistence/handoff.py @@ -64,6 +64,7 @@ async def create(self, artifact_id: str, draft: HandoffArtifactDraft, /) -> Hand self._scope_id, artifact_id, draft, + allow_working_notes=True, ) return cast(Handoff, artifact) @@ -74,6 +75,7 @@ async def revise(self, base: Handoff, draft: HandoffArtifactDraft, /) -> Handoff self._scope_id, base, draft, + allow_working_notes=True, ) return cast(Handoff, artifact) diff --git a/src/powercontext/builtin/source_eligibility.py b/src/powercontext/builtin/source_eligibility.py index 975c6c5d27..1c505306e2 100644 --- a/src/powercontext/builtin/source_eligibility.py +++ b/src/powercontext/builtin/source_eligibility.py @@ -63,12 +63,17 @@ def require_source_eligible( /, *, target: ArtifactLineageTarget | None = None, + allow_working_notes: bool = False, ) -> None: """Allow ordinary evidence, or a lineage-only Source at its exact bound target.""" if not isinstance(source, ContentSource): return if source.is_working_note: + if allow_working_notes: + if source.is_working_note_active(): + return + raise WorkingNoteUnavailableError(source_ref) raise SourceNotEligibleError(source_ref) if source.internal is None: return diff --git a/tests/e2e/test_handoff_runtime.py b/tests/e2e/test_handoff_runtime.py index 318d3b15da..82ffb67f3b 100644 --- a/tests/e2e/test_handoff_runtime.py +++ b/tests/e2e/test_handoff_runtime.py @@ -103,6 +103,14 @@ async def scenario() -> None: assert draft.next_action is not None assert draft.next_action.citations == (citation,) + handoffs = runtime.handoff.for_scope(scope.scope_id) + prepared = await handoffs.finalize(draft) + committed = await handoffs.commit(prepared) + + assert committed.content == prepared.content + assert committed.lineage.sources == (note.source_ref,) + assert await handoffs.latest() == committed + asyncio.run(scenario()) From 761b6a759584676179753e9219d03766da343a3f Mon Sep 17 00:00:00 2001 From: qyq316 <19606363088@163.com> Date: Tue, 13 Oct 2026 11:03:54 +0800 Subject: [PATCH 07/11] feat(hosts): expose working note capture tools --- .../dsh/plugins/powercontext/lib/index.js | 123 +++++++++++++----- .../dsh/plugins/powercontext/src/invoke.ts | 1 + .../dsh/plugins/powercontext/src/tools.ts | 25 ++++ .../plugins/powercontext/tests/tools.spec.ts | 53 ++++++++ .../plugins/powercontext/lib/index.js | 48 +++++++ .../opencode/plugins/powercontext/lib/tui.js | 23 ++++ .../plugins/powercontext/src/index.ts | 23 ++++ .../plugins/powercontext/src/invoke.ts | 1 + .../plugins/powercontext/tests/plugin.spec.ts | 46 +++++++ .../pi/plugins/powercontext/src/invoke.ts | 1 + .../pi/plugins/powercontext/src/tools.ts | 33 +++++ .../plugins/powercontext/tests/tools.spec.ts | 47 +++++++ 12 files changed, 388 insertions(+), 36 deletions(-) diff --git a/integrations/dsh/plugins/powercontext/lib/index.js b/integrations/dsh/plugins/powercontext/lib/index.js index ba23dabcd6..5fbbb4c6f7 100644 --- a/integrations/dsh/plugins/powercontext/lib/index.js +++ b/integrations/dsh/plugins/powercontext/lib/index.js @@ -2547,6 +2547,7 @@ function containsSecret(text) { const WRITE_OPS = new Set([ "remember_memory", "capture_content_source", + "capture_working_note", "revise_memory_entry", "replace_artifact", "change_atomic_memory_lifecycle" @@ -3739,6 +3740,13 @@ const MEMORY_KINDS = [ "next-step", "agent-note" ]; +const WORKING_NOTE_KINDS = [ + "inspection", + "abandoned_approach", + "validation", + "unresolved", + "host_context" +]; const SEARCH_MODES = [ "auto", "fts", @@ -3750,6 +3758,7 @@ const MUTATING_TOOL_NAMES = new Set([ "pc_memory_revise", "pc_memory_retire", "pc_capture_source", + "pc_capture_working_note", "pc_handoff_activate", "pc_handoff_commit", "pc_experience_generate", @@ -3978,47 +3987,89 @@ function memoryTools(runtime, defineTool) { ]; } function contextTools(runtime, defineTool) { - return [pcTool(defineTool, { - name: "pc_prepare_context", - description: "Retrieve bounded, query-specific PowerContext when additional assembled context is needed. Automatic recall already attempts this on supported lifecycle events; do not repeat it routinely or to satisfy an explicit save. A returned context value is not proof of host injection. Empty context is normal; use only the evidence actually returned.", - kind: "search", - parameters: { query: { - type: "string", - required: true, - description: "Question to retrieve context for." - } }, - execute: (args, exec) => run(runtime, exec, "prepare_context", { - query: args.query, - max_bytes: runtime.config.maxBytes, - ...runtime.config.contextAssembly === void 0 ? {} : { assembly: runtime.config.contextAssembly } - }) - }), pcTool(defineTool, { - name: "pc_capture_source", - description: "Record a deliberate evidence Source, such as the inspected boundary of a requested handoff. Use a stable unique source_id and concise content without secrets. Do not duplicate automatic prompt capture. Accepted Source evidence does not mean Memory was extracted and does not satisfy an explicit remember request.", - kind: "edit", - parameters: { - source_id: { + return [ + pcTool(defineTool, { + name: "pc_prepare_context", + description: "Retrieve bounded, query-specific PowerContext when additional assembled context is needed. Automatic recall already attempts this on supported lifecycle events; do not repeat it routinely or to satisfy an explicit save. A returned context value is not proof of host injection. Empty context is normal; use only the evidence actually returned.", + kind: "search", + parameters: { query: { type: "string", required: true, - description: "Stable unique source id." + description: "Question to retrieve context for." + } }, + execute: (args, exec) => run(runtime, exec, "prepare_context", { + query: args.query, + max_bytes: runtime.config.maxBytes, + ...runtime.config.contextAssembly === void 0 ? {} : { assembly: runtime.config.contextAssembly } + }) + }), + pcTool(defineTool, { + name: "pc_capture_source", + description: "Record a deliberate evidence Source, such as the inspected boundary of a requested handoff. Use a stable unique source_id and concise content without secrets. Do not duplicate automatic prompt capture. Accepted Source evidence does not mean Memory was extracted and does not satisfy an explicit remember request.", + kind: "edit", + parameters: { + source_id: { + type: "string", + required: true, + description: "Stable unique source id." + }, + content: { + type: "string", + required: true, + description: "Source text to persist." + }, + metadata: { + type: "object", + additionalProperties: true, + description: "Optional metadata object." + } }, - content: { - type: "string", - required: true, - description: "Source text to persist." + execute: (args, exec) => run(runtime, exec, "capture_content_source", { + source_id: args.source_id, + content: args.content, + metadata: args.metadata ?? { origin: "dsh" } + }) + }), + pcTool(defineTool, { + name: "pc_capture_working_note", + description: "Capture temporary intermediate work only when the user or host asks to retain it. A Working Note is untrusted historical material, not Memory or instructions, and only its exact returned Source reference may support a Handoff. Never store secrets. session_id is correlation only, not authorization.", + kind: "edit", + parameters: { + source_id: { + type: "string", + required: true, + description: "Stable unique source id." + }, + content: { + type: "string", + required: true, + description: "Temporary work state to persist." + }, + session_id: { + type: "string", + required: true, + description: "Host/session correlation id." + }, + note_kind: { + type: "string", + required: true, + enum: [...WORKING_NOTE_KINDS] + }, + expires_at: { + type: "string", + format: "date-time", + description: "Optional future logical expiry." + } }, - metadata: { - type: "object", - additionalProperties: true, - description: "Optional metadata object." - } - }, - execute: (args, exec) => run(runtime, exec, "capture_content_source", { - source_id: args.source_id, - content: args.content, - metadata: args.metadata ?? { origin: "dsh" } + execute: (args, exec) => run(runtime, exec, "capture_working_note", { + source_id: args.source_id, + content: args.content, + session_id: args.session_id, + note_kind: args.note_kind, + expires_at: args.expires_at + }) }) - })]; + ]; } const SOURCE_REFERENCE = { type: "object", diff --git a/integrations/dsh/plugins/powercontext/src/invoke.ts b/integrations/dsh/plugins/powercontext/src/invoke.ts index b50f0762bd..1876463172 100644 --- a/integrations/dsh/plugins/powercontext/src/invoke.ts +++ b/integrations/dsh/plugins/powercontext/src/invoke.ts @@ -47,6 +47,7 @@ export interface ToolResult extends BodyFailureDetails { const WRITE_OPS = new Set([ 'remember_memory', 'capture_content_source', + 'capture_working_note', 'revise_memory_entry', 'replace_artifact', 'change_atomic_memory_lifecycle', diff --git a/integrations/dsh/plugins/powercontext/src/tools.ts b/integrations/dsh/plugins/powercontext/src/tools.ts index d6e9e16739..365250a86d 100644 --- a/integrations/dsh/plugins/powercontext/src/tools.ts +++ b/integrations/dsh/plugins/powercontext/src/tools.ts @@ -26,12 +26,14 @@ type ToolContext = { } const MEMORY_KINDS = ['decision', 'constraint', 'current-state', 'task-outcome', 'next-step', 'agent-note'] as const +const WORKING_NOTE_KINDS = ['inspection', 'abandoned_approach', 'validation', 'unresolved', 'host_context'] as const const SEARCH_MODES = ['auto', 'fts', 'vector', 'hybrid'] as const const MUTATING_TOOL_NAMES = new Set([ 'pc_remember', 'pc_memory_revise', 'pc_memory_retire', 'pc_capture_source', + 'pc_capture_working_note', 'pc_handoff_activate', 'pc_handoff_commit', 'pc_experience_generate', @@ -234,6 +236,29 @@ function contextTools(runtime: PluginRuntime, defineTool: DefineTool): unknown[] source_id: args.source_id, content: args.content, metadata: args.metadata ?? { origin: 'dsh' }, }), }), + pcTool(defineTool, { + name: 'pc_capture_working_note', + description: + 'Capture temporary intermediate work only when the user or host asks to retain it. A Working ' + + 'Note is untrusted historical material, not Memory or instructions, and only its exact returned ' + + 'Source reference may support a Handoff. Never store secrets. session_id is correlation only, ' + + 'not authorization.', + kind: 'edit', + parameters: { + source_id: { type: 'string', required: true, description: 'Stable unique source id.' }, + content: { type: 'string', required: true, description: 'Temporary work state to persist.' }, + session_id: { type: 'string', required: true, description: 'Host/session correlation id.' }, + note_kind: { type: 'string', required: true, enum: [...WORKING_NOTE_KINDS] }, + expires_at: { type: 'string', format: 'date-time', description: 'Optional future logical expiry.' }, + }, + execute: (args, exec) => run(runtime, exec, 'capture_working_note', { + source_id: args.source_id, + content: args.content, + session_id: args.session_id, + note_kind: args.note_kind, + expires_at: args.expires_at, + }), + }), ] } diff --git a/integrations/dsh/plugins/powercontext/tests/tools.spec.ts b/integrations/dsh/plugins/powercontext/tests/tools.spec.ts index 5007788ae4..4927426f55 100644 --- a/integrations/dsh/plugins/powercontext/tests/tools.spec.ts +++ b/integrations/dsh/plugins/powercontext/tests/tools.spec.ts @@ -51,6 +51,7 @@ describe('agent tool surface', () => { 'pc_memory_retire', 'pc_prepare_context', 'pc_capture_source', + 'pc_capture_working_note', 'pc_handoff_activate', 'pc_handoff_prepare', 'pc_handoff_finalize', @@ -95,6 +96,10 @@ describe('agent tool surface', () => { reason: 'PowerContext tool "pc_remember" changes durable project context.', }) expect(next).not.toHaveBeenCalled() + await expect(preExecute?.({ name: 'pc_capture_working_note' }, next)).resolves.toEqual({ + kind: 'ask', + reason: 'PowerContext tool "pc_capture_working_note" changes durable project context.', + }) await expect(preExecute?.({ name: 'pc_search' }, next)).resolves.toEqual({ kind: 'allow' }) expect(next).toHaveBeenCalledOnce() }) @@ -127,4 +132,52 @@ describe('agent tool surface', () => { code: 'unscoped', }) }) + + it('routes Working Note capture through the scoped operation', async () => { + const registered: Array<{ + name: string + execute: (args: Record, exec: unknown) => Promise + }> = [] + const request = vi.fn(async () => ({ + kind: 'json' as const, + value: { status: 'accepted', source: { name: 'content', source_id: 'note-1' }, position: 1 }, + status: 202, + requestId: undefined, + })) + registerTools( + { + tools: { register: (tool) => registered.push(tool as never) }, + on: () => undefined, + }, + { + client: { request } as never, + config: { maxBytes: 8000 }, + resolveScope: vi.fn(async () => 'project:demo'), + log: vi.fn(), + } as unknown as PluginRuntime, + (definition) => definition, + ) + + const capture = registered.find((tool) => tool.name === 'pc_capture_working_note') + const result = await capture?.execute({ + source_id: 'note-1', + content: 'Parser validation is still in progress.', + session_id: 'session-1', + note_kind: 'validation', + expires_at: '2030-01-02T00:00:00Z', + }, { + signal: AbortSignal.timeout(1000), + agent: { session: { header: { cwd: '/workspace/repo' } } }, + }) + + expect(result).toMatchObject({ ok: true, status: 202 }) + expect(request).toHaveBeenCalledWith('capture_working_note', { + source_id: 'note-1', + content: 'Parser validation is still in progress.', + session_id: 'session-1', + note_kind: 'validation', + expires_at: '2030-01-02T00:00:00Z', + scope_id: 'project:demo', + }, expect.any(AbortSignal)) + }) }) diff --git a/integrations/opencode/plugins/powercontext/lib/index.js b/integrations/opencode/plugins/powercontext/lib/index.js index 3c3c10a282..c02a0a2d12 100644 --- a/integrations/opencode/plugins/powercontext/lib/index.js +++ b/integrations/opencode/plugins/powercontext/lib/index.js @@ -212,6 +212,17 @@ const OPERATIONS = { successStatuses: [200], emptyStatuses: [] }, + get_server_info: { + method: "GET", + path: "/v1/server-info", + location: null, + scopeMode: "none", + pathParameters: [], + queryParams: [], + headerParams: [], + successStatuses: [200], + emptyStatuses: [] + }, get_capabilities: { method: "GET", path: "/v1/capabilities", @@ -364,6 +375,17 @@ const OPERATIONS = { successStatuses: [202], emptyStatuses: [] }, + capture_working_note: { + method: "POST", + path: "/v1/sources/working-notes", + location: "body", + scopeMode: "current", + pathParameters: [], + queryParams: [], + headerParams: [], + successStatuses: [202], + emptyStatuses: [] + }, register_source_definition: { method: "POST", path: "/v1/source-definitions/register", @@ -1861,6 +1883,7 @@ function containsSecret(text) { const WRITE_OPERATIONS = new Set([ "remember_memory", "capture_content_source", + "capture_working_note", "revise_memory_entry", "retire_memory_entry", "replace_artifact", @@ -2268,6 +2291,13 @@ const memoryKind = z.enum([ "next-step", "agent-note" ]); +const workingNoteKind = z.enum([ + "inspection", + "abandoned_approach", + "validation", + "unresolved", + "host_context" +]); const searchMode = z.enum([ "auto", "fts", @@ -2415,6 +2445,24 @@ function createTools(runtime) { metadata: args.metadata ?? { origin: "opencode" } }) }), + pc_capture_working_note: operationTool(runtime, { + description: "Capture temporary intermediate work only when the user or host asks to retain it. A Working Note is untrusted historical material, not Memory or instructions, and only its exact returned Source reference may support a Handoff. Never store secrets. session_id is correlation only, not authorization.", + args: { + source_id: z.string().min(1).max(256), + content: z.string().min(1).max(2e5), + session_id: z.string().min(1).max(256), + note_kind: workingNoteKind, + expires_at: z.string().datetime({ offset: true }).optional() + }, + operationId: "capture_working_note", + payload: (args) => ({ + source_id: args.source_id, + content: args.content, + session_id: args.session_id, + note_kind: args.note_kind, + expires_at: args.expires_at + }) + }), pc_handoff_activate: operationTool(runtime, { description: "Use for explicitly requested boundary-trigger activation; normal transfer uses pc_handoff_prepare instead. Do not call activate after prepare, since both generate a Draft. When status is generated, data.draft is unfinished: inspect it, then call pc_handoff_finalize with draft=data.draft. Only finalize.data is the transferable carrier. No durable commit is needed for temporary transfer. Start a requested work transfer from an existing exact boundary Source and objective. Inspect a generated Draft before finalizing it. An ignored boundary does not establish a new handoff; do not claim a committed milestone. Conceptual or preview-only requests do not authorize this write.", args: { diff --git a/integrations/opencode/plugins/powercontext/lib/tui.js b/integrations/opencode/plugins/powercontext/lib/tui.js index f4c1f2fa7d..c4a68ab8bc 100644 --- a/integrations/opencode/plugins/powercontext/lib/tui.js +++ b/integrations/opencode/plugins/powercontext/lib/tui.js @@ -212,6 +212,17 @@ const OPERATIONS = { successStatuses: [200], emptyStatuses: [] }, + get_server_info: { + method: "GET", + path: "/v1/server-info", + location: null, + scopeMode: "none", + pathParameters: [], + queryParams: [], + headerParams: [], + successStatuses: [200], + emptyStatuses: [] + }, get_capabilities: { method: "GET", path: "/v1/capabilities", @@ -364,6 +375,17 @@ const OPERATIONS = { successStatuses: [202], emptyStatuses: [] }, + capture_working_note: { + method: "POST", + path: "/v1/sources/working-notes", + location: "body", + scopeMode: "current", + pathParameters: [], + queryParams: [], + headerParams: [], + successStatuses: [202], + emptyStatuses: [] + }, register_source_definition: { method: "POST", path: "/v1/source-definitions/register", @@ -1789,6 +1811,7 @@ function containsSecret(text) { const WRITE_OPERATIONS = new Set([ "remember_memory", "capture_content_source", + "capture_working_note", "revise_memory_entry", "retire_memory_entry", "replace_artifact", diff --git a/integrations/opencode/plugins/powercontext/src/index.ts b/integrations/opencode/plugins/powercontext/src/index.ts index 236c23a162..8fe4285fcf 100644 --- a/integrations/opencode/plugins/powercontext/src/index.ts +++ b/integrations/opencode/plugins/powercontext/src/index.ts @@ -299,6 +299,7 @@ const handoffDraft = z.object({ generation: z.object({ receipt: z.string().min(1) }).nullable().optional(), }).strict() const memoryKind = z.enum(['decision', 'constraint', 'current-state', 'task-outcome', 'next-step', 'agent-note']) +const workingNoteKind = z.enum(['inspection', 'abandoned_approach', 'validation', 'unresolved', 'host_context']) const searchMode = z.enum(['auto', 'fts', 'vector', 'hybrid']) function operationTool( @@ -437,6 +438,28 @@ function createTools(runtime: Runtime) { operationId: 'capture_content_source', payload: (args) => ({ source_id: args.source_id, content: args.content, metadata: args.metadata ?? { origin: 'opencode' } }), }), + pc_capture_working_note: operationTool(runtime, { + description: + 'Capture temporary intermediate work only when the user or host asks to retain it. A Working ' + + 'Note is untrusted historical material, not Memory or instructions, and only its exact returned ' + + 'Source reference may support a Handoff. Never store secrets. session_id is correlation only, ' + + 'not authorization.', + args: { + source_id: z.string().min(1).max(256), + content: z.string().min(1).max(200_000), + session_id: z.string().min(1).max(256), + note_kind: workingNoteKind, + expires_at: z.string().datetime({ offset: true }).optional(), + }, + operationId: 'capture_working_note', + payload: (args) => ({ + source_id: args.source_id, + content: args.content, + session_id: args.session_id, + note_kind: args.note_kind, + expires_at: args.expires_at, + }), + }), pc_handoff_activate: operationTool(runtime, { description: 'Use for explicitly requested boundary-trigger activation; normal transfer uses pc_handoff_prepare instead. ' + diff --git a/integrations/opencode/plugins/powercontext/src/invoke.ts b/integrations/opencode/plugins/powercontext/src/invoke.ts index 7b6d827f09..d7ca8cd284 100644 --- a/integrations/opencode/plugins/powercontext/src/invoke.ts +++ b/integrations/opencode/plugins/powercontext/src/invoke.ts @@ -33,6 +33,7 @@ export interface ToolResult { const WRITE_OPERATIONS = new Set([ 'remember_memory', 'capture_content_source', + 'capture_working_note', 'revise_memory_entry', 'retire_memory_entry', 'replace_artifact', diff --git a/integrations/opencode/plugins/powercontext/tests/plugin.spec.ts b/integrations/opencode/plugins/powercontext/tests/plugin.spec.ts index ef65c265b9..e1fcded430 100644 --- a/integrations/opencode/plugins/powercontext/tests/plugin.spec.ts +++ b/integrations/opencode/plugins/powercontext/tests/plugin.spec.ts @@ -80,6 +80,7 @@ describe('PowerContextPlugin', () => { try { const hooks = await PowerContextPlugin(pluginInput()) expect(hooks.tool?.pc_remember).toBeDefined() + expect(hooks.tool?.pc_capture_working_note).toBeDefined() expect(await readFile(path, 'utf8')).toBe('expected-nonce') } finally { await rm(path, { force: true }) @@ -228,6 +229,51 @@ describe('PowerContextPlugin', () => { expect(JSON.parse(String(result))).toMatchObject({ ok: true }) }) + it('captures a Working Note through the scoped operation', async () => { + process.env.POWERCONTEXT_OPENCODE_SCOPE_ID = 'project:test' + const calls: Array<{ url: string; body: any }> = [] + vi.stubGlobal('fetch', vi.fn(async (url: string, init: RequestInit) => { + const body = init.body ? JSON.parse(String(init.body)) : undefined + calls.push({ url, body }) + return bindingResponse(url, body) ?? Response.json({ status: 'accepted', source: { name: 'content', source_id: 'note-1' }, position: 1 }, { status: 202 }) + })) + const hooks = await PowerContextPlugin(pluginInput()) + const ask = vi.fn(async () => undefined) + + const result = await hooks.tool?.pc_capture_working_note?.execute( + { + source_id: 'note-1', + content: 'Parser validation is still in progress.', + session_id: 'session-1', + note_kind: 'validation', + expires_at: '2030-01-02T00:00:00Z', + }, + { + sessionID: 'session-1', + messageID: 'msg-1', + agent: 'build', + directory: '/tmp/project', + worktree: '/tmp/project', + abort: new AbortController().signal, + metadata: vi.fn(), + ask, + }, + ) + + expect(ask).toHaveBeenCalledWith(expect.objectContaining({ + permission: 'powercontext', patterns: ['capture_working_note'], + })) + expect(calls.find((call) => call.url.endsWith('/v1/sources/working-notes'))?.body).toEqual({ + source_id: 'note-1', + content: 'Parser validation is still in progress.', + session_id: 'session-1', + note_kind: 'validation', + expires_at: '2030-01-02T00:00:00Z', + scope_id: 'project:test', + }) + expect(JSON.parse(String(result))).toMatchObject({ ok: true, status: 202 }) + }) + it('does not send secret-shaped prompts', async () => { process.env.POWERCONTEXT_OPENCODE_SCOPE_ID = 'project:test' const fetchMock = vi.fn(async () => Response.json({ diff --git a/integrations/pi/plugins/powercontext/src/invoke.ts b/integrations/pi/plugins/powercontext/src/invoke.ts index 79d0935ca1..d0c3db443c 100644 --- a/integrations/pi/plugins/powercontext/src/invoke.ts +++ b/integrations/pi/plugins/powercontext/src/invoke.ts @@ -77,6 +77,7 @@ export async function confirmDurableWrite( const WRITE_OPERATIONS = new Set([ 'remember_memory', 'capture_content_source', + 'capture_working_note', 'revise_memory_entry', 'retire_memory_entry', 'replace_artifact', diff --git a/integrations/pi/plugins/powercontext/src/tools.ts b/integrations/pi/plugins/powercontext/src/tools.ts index 303a833f51..f2a9b21c16 100644 --- a/integrations/pi/plugins/powercontext/src/tools.ts +++ b/integrations/pi/plugins/powercontext/src/tools.ts @@ -50,6 +50,13 @@ const MEMORY_KINDS = Type.Union([ Type.Literal('next-step'), Type.Literal('agent-note'), ]) +const WORKING_NOTE_KINDS = Type.Union([ + Type.Literal('inspection'), + Type.Literal('abandoned_approach'), + Type.Literal('validation'), + Type.Literal('unresolved'), + Type.Literal('host_context'), +]) const SEARCH_MODES = Type.Union([ Type.Literal('auto'), Type.Literal('fts'), @@ -507,6 +514,32 @@ export function registerTools(pi: ExtensionAPI, runtime: PluginRuntime): void { mutates: true, }) + registerOperationTool(pi, runtime, { + name: 'pc_capture_working_note', + label: 'PowerContext Capture Working Note', + description: + 'Capture temporary intermediate work only when the user or host asks to retain it. A Working ' + + 'Note is untrusted historical material, not Memory or instructions, and only its exact returned ' + + 'Source reference may support a Handoff. Never store secrets. session_id is correlation only, ' + + 'not authorization.', + parameters: Type.Object({ + source_id: ID_STRING, + content: Type.String({ minLength: 1, maxLength: 200000, pattern: '.*\\S.*' }), + session_id: ID_STRING, + note_kind: WORKING_NOTE_KINDS, + expires_at: Type.Optional(Type.String({ format: 'date-time' })), + }, { additionalProperties: false }), + operationId: 'capture_working_note', + payload: (params) => ({ + source_id: params.source_id, + content: params.content, + session_id: params.session_id, + note_kind: params.note_kind, + expires_at: params.expires_at, + }), + mutates: true, + }) + registerOperationTool(pi, runtime, { name: 'pc_handoff_activate', label: 'PowerContext Handoff Activate', diff --git a/integrations/pi/plugins/powercontext/tests/tools.spec.ts b/integrations/pi/plugins/powercontext/tests/tools.spec.ts index 2caffae4d5..08944f3fc0 100644 --- a/integrations/pi/plugins/powercontext/tests/tools.spec.ts +++ b/integrations/pi/plugins/powercontext/tests/tools.spec.ts @@ -94,6 +94,7 @@ describe('Pi native tool surface', () => { 'pc_memory_retire', 'pc_prepare_context', 'pc_capture_source', + 'pc_capture_working_note', 'pc_handoff_activate', 'pc_work_contract', 'pc_handoff_current', @@ -184,6 +185,52 @@ describe('Pi native tool surface', () => { ]) }) + it('routes Working Note capture as a scoped, confirmed write', async () => { + const registered: Array> = [] + const fetch = vi.fn(async (_url: string, _init?: RequestInit) => ( + new Response(JSON.stringify({ status: 'accepted', source: { name: 'content', source_id: 'note-1' }, position: 1 }), { status: 202 }) + )) + registerTools( + { registerTool: (tool: Record) => registered.push(tool) } as never, + createRuntime(fetch), + ) + const confirm = vi.fn(async () => true) + + const result = await registeredTool<{ + source_id: string + content: string + session_id: string + note_kind: string + expires_at?: string + }>(registered, 'pc_capture_working_note').execute( + 'call-note', + { + source_id: 'note-1', + content: 'Parser validation is still in progress.', + session_id: 'session-1', + note_kind: 'validation', + expires_at: '2030-01-02T00:00:00Z', + }, + new AbortController().signal, + () => undefined, + { cwd: '/workspace/repo', hasUI: true, ui: { confirm } }, + ) + + expect(result.details).toMatchObject({ ok: true }) + expect(confirm).toHaveBeenCalled() + expect(fetch.mock.calls.map(([url, init]) => [url, JSON.parse(String(init?.body))])).toEqual([[ + 'http://127.0.0.1:8000/v1/sources/working-notes', + { + source_id: 'note-1', + content: 'Parser validation is still in progress.', + session_id: 'session-1', + note_kind: 'validation', + expires_at: '2030-01-02T00:00:00Z', + scope_id: 'project:demo', + }, + ]]) + }) + it('keeps the read-only tool schemas within the API contract', () => { const registered: Array> = [] registerTools({ registerTool: (tool: Record) => registered.push(tool) } as never, createRuntime(vi.fn())) From 298ce3ea92dab7c62ca775d54d9207c5647095d8 Mon Sep 17 00:00:00 2001 From: qyq316 <19606363088@163.com> Date: Tue, 13 Oct 2026 11:07:43 +0800 Subject: [PATCH 08/11] chore(integrations): register working note tools --- integrations/capabilities.toml | 9 +++++++++ tests/test_integration_manifest.py | 7 +++++-- 2 files changed, 14 insertions(+), 2 deletions(-) diff --git a/integrations/capabilities.toml b/integrations/capabilities.toml index 216c5a2051..df9b526aee 100644 --- a/integrations/capabilities.toml +++ b/integrations/capabilities.toml @@ -282,6 +282,9 @@ capabilities = ["context_injection"] id = "pc_capture_source:capture_content_source" capabilities = ["source_capture"] [[toolsets.tools]] +id = "pc_capture_working_note:capture_working_note" +capabilities = ["source_capture"] +[[toolsets.tools]] id = "pc_handoff_activate:activate_handoff" capabilities = ["handoff"] [[toolsets.tools]] @@ -553,6 +556,9 @@ capabilities = ["context_injection"] id = "pc_capture_source:capture_content_source" capabilities = ["source_capture"] [[toolsets.tools]] +id = "pc_capture_working_note:capture_working_note" +capabilities = ["source_capture"] +[[toolsets.tools]] id = "pc_handoff_activate:activate_handoff" capabilities = ["handoff"] [[toolsets.tools]] @@ -620,6 +626,9 @@ capabilities = ["context_injection"] id = "pc_capture_source:capture_content_source" capabilities = ["source_capture"] [[toolsets.tools]] +id = "pc_capture_working_note:capture_working_note" +capabilities = ["source_capture"] +[[toolsets.tools]] id = "pc_handoff_activate:activate_handoff" capabilities = ["handoff"] [[toolsets.tools]] diff --git a/tests/test_integration_manifest.py b/tests/test_integration_manifest.py index 696ed20747..1dee56a3b7 100644 --- a/tests/test_integration_manifest.py +++ b/tests/test_integration_manifest.py @@ -106,10 +106,13 @@ def test_tool_surface_probe_handles_long_descriptions_without_borrowing_operatio assert errors == () -def test_dify_declares_the_dsh_tool_surface_without_host_lifecycle_claims() -> None: +def test_dify_declares_the_dsh_tool_surface_except_working_notes_without_host_lifecycle_claims() -> None: manifest = load_integration_manifest() toolsets = {item.id: item for item in manifest.toolsets} - assert {tool.id for tool in toolsets["dify-tools"].tools} == {tool.id for tool in toolsets["dsh-tools"].tools} + dify_tools = {tool.id for tool in toolsets["dify-tools"].tools} + dsh_tools = {tool.id for tool in toolsets["dsh-tools"].tools} + assert dsh_tools - dify_tools == {"pc_capture_working_note:capture_working_note"} + assert dify_tools - dsh_tools == set() dify = next(item for item in manifest.integrations if item.id == "dify") assert dify.availability is IntegrationAvailability.EXPERIMENTAL assert dify.profiles == () From 5f8c4b7b06c9a4c382295c6f152c1ed496ae4af7 Mon Sep 17 00:00:00 2001 From: qyq316 <19606363088@163.com> Date: Tue, 13 Oct 2026 11:46:58 +0800 Subject: [PATCH 09/11] fix(ci): refresh zcode guidance pin --- evaluation/zcode_guidance/README.md | 3 ++- evaluation/zcode_guidance/skill-lock.json | 11 ++++++----- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/evaluation/zcode_guidance/README.md b/evaluation/zcode_guidance/README.md index 29dc75a781..a59bf9f27c 100644 --- a/evaluation/zcode_guidance/README.md +++ b/evaluation/zcode_guidance/README.md @@ -52,7 +52,8 @@ the pin check. To evaluate a deliberately updated, committed Skill: uv run --locked python -m evaluation.zcode_guidance.pin --revision ``` -The current Skill pin is `20583250a6bdce5bab8716321ee3911844b6de2d`, using the Atomic Memory contract. +The current Skill pin is `b5bcfe24bcce9c574ee85175d623bb9963970a41`, including the managed guidance metadata +and the Atomic Memory contract. This pin has not been rerun with a live model. Offline validation confirms fixture and grader compatibility; a new paired live run is required before claiming qualification for this Skill and contract. Changing the pin alone grants no qualification. diff --git a/evaluation/zcode_guidance/skill-lock.json b/evaluation/zcode_guidance/skill-lock.json index 44f8f303f5..f5f1552497 100644 --- a/evaluation/zcode_guidance/skill-lock.json +++ b/evaluation/zcode_guidance/skill-lock.json @@ -1,11 +1,12 @@ { "schema_version": 1, "source_path": "integrations/zcode/plugins/powercontext/skills/powercontext-project-context", - "source_commit": "20583250a6bdce5bab8716321ee3911844b6de2d", + "source_commit": "b5bcfe24bcce9c574ee85175d623bb9963970a41", "files": { - "SKILL.md": "88b6eed1a865b395dedc9508ab6cfcb15f2fc800f13bd9d5df02b963234906a1", - "references/review-publication.md": "83f3fa674d83785d06945669cbbe08b6d679665fed7e165d778dbfbcd9d10841", - "references/scope-memory.md": "2863f4ce693408136ede70818e0d7e25d197367e90db14ab6f889488cebc394d", - "references/work-handoff.md": "76dea45b708f2155e395029afe57b31ac112d8b13d614a6ab604aa436e3d2b2e" + ".powercontext-guidance.json": "655cbbb72bd53c08f9e846e315ed64d3a855eb54767e97580b00b88b237f5358", + "SKILL.md": "391cbb19e5dbc6b6b5e65c02753de702f67cead755bde07ba51efa19d01a4b55", + "references/review-publication.md": "844c3b4796d3b4e961bc943785dbe3c71960424644601b661b155fa9a6f8f3fe", + "references/scope-memory.md": "8d389bc708f68fbaadd0bd363980f970e67acdec2f1a97a622f3a8ccacfbb1b9", + "references/work-handoff.md": "248069bc7f69268ba90de38b2537fe9a385d4a220a35c54603d53e16df10988f" } } From 1324ff5005a39c68b6ebf58baf456e31dbc670cb Mon Sep 17 00:00:00 2001 From: qyq316 <19606363088@163.com> Date: Fri, 16 Oct 2026 11:29:09 +0800 Subject: [PATCH 10/11] fix(work): complete working note review fixes --- .../dsh/plugins/powercontext/lib/index.js | 12 ++++++++++++ .../powercontext/src/mcp-operations.generated.ts | 3 +++ src/powercontext/http/__init__.py | 3 +++ src/powercontext/server/mapping.py | 16 ++++++++++++++++ 4 files changed, 34 insertions(+) diff --git a/integrations/dsh/plugins/powercontext/lib/index.js b/integrations/dsh/plugins/powercontext/lib/index.js index e647b16816..84c4c4d30c 100644 --- a/integrations/dsh/plugins/powercontext/lib/index.js +++ b/integrations/dsh/plugins/powercontext/lib/index.js @@ -467,6 +467,17 @@ const OPERATIONS = { successStatuses: [202], emptyStatuses: [] }, + capture_working_note: { + method: "POST", + path: "/v1/sources/working-notes", + location: "body", + scopeMode: "current", + pathParameters: [], + queryParams: [], + headerParams: [], + successStatuses: [202], + emptyStatuses: [] + }, register_source_definition: { method: "POST", path: "/v1/source-definitions/register", @@ -3308,6 +3319,7 @@ const MCP_OPERATIONS = { "activate_handoff": { "readOnly": false }, "approve_candidate": { "readOnly": false }, "capture_content_source": { "readOnly": false }, + "capture_working_note": { "readOnly": false }, "change_atomic_memory_lifecycle": { "readOnly": false }, "clear_scope_binding": { "readOnly": false }, "commit_handoff": { "readOnly": false }, diff --git a/integrations/dsh/plugins/powercontext/src/mcp-operations.generated.ts b/integrations/dsh/plugins/powercontext/src/mcp-operations.generated.ts index 8274c26ebf..7a29a5f8ff 100644 --- a/integrations/dsh/plugins/powercontext/src/mcp-operations.generated.ts +++ b/integrations/dsh/plugins/powercontext/src/mcp-operations.generated.ts @@ -29,6 +29,9 @@ export const MCP_OPERATIONS = { "capture_content_source": { "readOnly": false }, + "capture_working_note": { + "readOnly": false + }, "change_atomic_memory_lifecycle": { "readOnly": false }, diff --git a/src/powercontext/http/__init__.py b/src/powercontext/http/__init__.py index 4f38cc4ebe..ba5ee7ddba 100644 --- a/src/powercontext/http/__init__.py +++ b/src/powercontext/http/__init__.py @@ -464,6 +464,7 @@ WorkClaim, WorkClaimBasis, WorkContract, + WorkingNoteKind, WorkSourceKind, WorkSourceReceipt, ) @@ -566,6 +567,7 @@ "CaptureContentSourceRequest", "CaptureContentSourceResponse", "CaptureStatus", + "CaptureWorkingNoteRequest", "CatalogChangeProposal", "CatalogTagResult", "ClearScopeBindingRequest", @@ -919,4 +921,5 @@ "WorkContract", "WorkSourceKind", "WorkSourceReceipt", + "WorkingNoteKind", ] diff --git a/src/powercontext/server/mapping.py b/src/powercontext/server/mapping.py index 147c7c502c..d074ad8b28 100644 --- a/src/powercontext/server/mapping.py +++ b/src/powercontext/server/mapping.py @@ -72,6 +72,7 @@ from powercontext.builtin.runtime import ( ActivateHandoff, CaptureSource, + CaptureWorkingNote, Handoff, HandoffActivation, HandoffArtifactCitation, @@ -144,6 +145,7 @@ from powercontext.builtin.runtime import ( SubmitSourceObservation as RuntimeSubmitSourceObservation, ) +from powercontext.builtin.runtime import WorkingNoteKind as RuntimeWorkingNoteKind from powercontext.builtin.runtime.atomic_memory import AtomicMemoryPage, AtomicMemorySearchPage from powercontext.builtin.sources import ExternalSkillImportMode as RuntimeExternalSkillImportMode from powercontext.builtin.work import ( @@ -184,6 +186,7 @@ CaptureContentSourceRequest, CaptureContentSourceResponse, CaptureStatus, + CaptureWorkingNoteRequest, CatalogChangeProposal, CommitConnectorCheckpointRequest, CommittedHandoff, @@ -373,6 +376,19 @@ def capture_request(value: CaptureContentSourceRequest) -> CaptureSource: ) +def working_note_capture_request(value: CaptureWorkingNoteRequest) -> CaptureWorkingNote: + try: + return CaptureWorkingNote( + source_id=value.source_id, + content=value.content, + session_id=value.session_id, + note_kind=RuntimeWorkingNoteKind(value.note_kind.value), + expires_at=value.expires_at, + ) + except (TypeError, ValueError, ValidationError) as error: + raise InvalidRuntimeRequestError("working-note") from error + + def create_work_contract_request(value: CreateWorkContractRequest) -> RuntimeCreateWorkContract: try: return RuntimeCreateWorkContract( From b2c2dea315296aeb12c2d7611c75e40c8d5b642e Mon Sep 17 00:00:00 2001 From: qyq316 <19606363088@163.com> Date: Fri, 16 Oct 2026 11:50:06 +0800 Subject: [PATCH 11/11] chore: sync generated integration contracts --- desktop/src-tauri/src/transport/operations.json | 2 +- desktop/ui/src/generated/operations.ts | 2 +- integrations/capabilities.toml | 3 +++ 3 files changed, 5 insertions(+), 2 deletions(-) diff --git a/desktop/src-tauri/src/transport/operations.json b/desktop/src-tauri/src/transport/operations.json index ae7ff593ad..aebc8ce9bc 100644 --- a/desktop/src-tauri/src/transport/operations.json +++ b/desktop/src-tauri/src/transport/operations.json @@ -1,5 +1,5 @@ { - "contractSha256": "ab39e1cc1a407544927c789fcc02b5f58eccb301b8f874349fe59ac2a8c05107", + "contractSha256": "38d9c55e21cb96946901e3516aa07a2fec5e6f8369014f6b5f69f81668c5ebe8", "operations": { "get_liveness": { "method": "GET", diff --git a/desktop/ui/src/generated/operations.ts b/desktop/ui/src/generated/operations.ts index e404655316..8c255c698e 100644 --- a/desktop/ui/src/generated/operations.ts +++ b/desktop/ui/src/generated/operations.ts @@ -15,7 +15,7 @@ */ // Generated from openapi/powercontext.yaml. Do not edit. -export const contractSha256 = "ab39e1cc1a407544927c789fcc02b5f58eccb301b8f874349fe59ac2a8c05107"; +export const contractSha256 = "38d9c55e21cb96946901e3516aa07a2fec5e6f8369014f6b5f69f81668c5ebe8"; export const operations = { "get_liveness": { "method": "GET", diff --git a/integrations/capabilities.toml b/integrations/capabilities.toml index e56e34b075..a5c6a6035d 100644 --- a/integrations/capabilities.toml +++ b/integrations/capabilities.toml @@ -312,6 +312,9 @@ capabilities = ["memory_write"] id = "mcp__powercontext__capture_content_source" capabilities = ["source_capture"] [[toolsets.tools]] +id = "mcp__powercontext__capture_working_note" +capabilities = ["source_capture"] +[[toolsets.tools]] id = "mcp__powercontext__create_work_contract" capabilities = ["work_contract"] [[toolsets.tools]]