You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
No tracking issue is assigned. This PR proposes RFC #1783 and includes the initial compatible Handoff implementation.
Rationale for this change
Long Agent sessions can accumulate stale assumptions, noisy context, and compaction loss. PowerContext already has Handoff as the evidence-backed work-continuity boundary, so this PR treats long-session rollover as a Handoff lifecycle event rather than transcript compaction, a new Notes family, or automatic Memory creation.
The implementation follows the RFC's compatibility constraint: rollover reasons are advisory preparation inputs. They can guide draft generation toward a fresh-session checkpoint, but they do not become committed Handoff content identity, do not authorize commit or execution, and do not change Continue or Memory semantics.
What changes are included in this PR?
Adds the English RFC at docs/en/rfcs/1783-handoff-session-rollover.md.
Adds the synchronized Chinese RFC translation at docs/zh/rfcs/1783-handoff-session-rollover.md.
Defines Rollover Handoff scope, quality requirements, host integration levels, and boundaries with Memory, Source, PreparedContext, and provider-specific context-window behavior.
Adds optional rollover_reasons to Handoff prepare and activation requests.
Propagates rollover reasons through the existing Handoff trigger, service, and generation input path.
Updates Handoff generation instructions so non-empty rollover reasons ask for a fresh-session checkpoint without relying on the old transcript.
Regenerates checked-in HTTP models/schema from openapi/powercontext.yaml.
Adds tests for reason validation, service propagation, generation input exposure, and the fact that reasons are not persisted into Handoff content.
Are there any user-facing changes?
Yes. Handoff prepare and activation HTTP requests now accept optional advisory rollover_reasons values:
user_requested
host_context_budget
host_compaction
context_quality
delegation
manual_checkpoint
Existing requests remain compatible because the field defaults to an empty list.
How was this change tested?
uv run --no-sync pytest tests/builtin/artifacts/handoff/test_models.py tests/builtin/artifacts/handoff/test_generation.py tests/builtin/artifacts/handoff/test_service.py tests/test_api_contract.py -q
make contract-test
uv run --no-sync ruff check <changed Python files>
uv run --no-sync ruff format --check <changed Python files>
uv run --no-sync ty check --python-version 3.11 <changed Python files>
git diff --check
Verified English and Chinese RFC heading counts match: 28 headings each.
AI usage statement
Used OpenAI Codex to draft the bilingual RFC, review it against the existing Handoff implementation, implement the compatible rollover-reason path, and run local validation.
The reason will be displayed to describe this comment to others. Learn more.
I support using Handoff for session rollover. Since RFC 0048 already covers transfer and Continue, I suggest focusing this RFC on the host contract for window replacement and recovery.
Expose rollover_reasons in supported Handoff tool schemas
openapi/powercontext.yaml:4703
Possible capability gap (non-blocking): the supported Pi, OpenCode, DSH, and Hermes Handoff tools still expose fixed prepare/activate argument schemas without rollover_reasons (for example, integrations/pi/plugins/powercontext/src/tools.ts:508-524,607-620 and integrations/hermes/plugins/powercontext/commands.py:731-760). Agents using those advertised Handoff surfaces therefore cannot discover or send this new input, even though the HTTP/MCP contract supports it. Update the adapters or track the missing host support explicitly.
Validate rollover reason constraints in custom prompt demonstrations
HandoffGenerationInput is also the schema used to validate custom prompt demonstrations, but this new field does not carry the six-item or uniqueness constraints from HandoffGenerationRequest. The secondary validation in prompt/validation.py reconstructs PrepareHandoff without forwarding these reasons, so demonstrations containing duplicates or more than six reasons are accepted even though no real generation request can produce them. Mirror the request constraints here or pass this field through the demonstration validator.
Preserve fresh-session checkpoint requirements in custom prompts
Custom handoff.generate prompts replace the default instructions with these invariants plus scope-owned guidance. This line only says that reasons are advisory; it omits the new behavior in HANDOFF_GENERATION_INSTRUCTIONS requiring a self-contained fresh-session checkpoint. Consequently, a supported custom prompt receives rollover_reasons but is never told to avoid old-transcript references or make the first safe action explicit. Keep that conditional requirement in the invariant contract as well.
CI failures on the previous head were cross-branch contract drift: master added the Dify integration, desktop contract checks, and skill-up OpenAPI validation after this branch was cut, and the PR's new rollover_reasons parameter had not been propagated to the derived artifacts.
integrations/dify: registered rollover_reasons in generate_contract.py PARAMETERS and regenerated contract.json and both tool YAMLs (make dify-test generate step passes).
desktop: regenerated ui/src/generated/api.d.ts, ui/src/generated/operations.ts, and src-tauri/src/transport/operations.json with the pinned generator versions (openapi-typescript 7.13.0 / yaml 2.9.0); generate.mjs --check passes.
evaluation/skills/skill-up: refreshed the tool argument reference via validate_suite.py --write-tool-contract; the suite passes.
Preserve fresh-session rollover rules for custom Handoff Prompts and correct Dify Chinese labels.
Constraint: Rollover reasons remain advisory preparation context only.
Scope-risk: Host adapter parity is tracked in oceanbase#1931 rather than included in this RFC PR.
Tested: targeted Python and Dify regression tests; Dify generation; Ruff; ty.
The Auto selection uses only HANDOFF_GENERATION_INSTRUCTIONS (definitions.py:111-112), so it does not receive the advisory-only rule added to the custom-prompt invariants. This leaves the default generator free to present a rollover reason as committed Handoff content, contrary to the RFC compatibility constraint. Include the same advisory/non-content rule in the v2 default instructions.
The reason will be displayed to describe this comment to others. Learn more.
Reviewed commit 1508074 using Open Code Review and a public API reproduction. One reproducible contract violation remains in custom handoff.generate demonstration validation; please address the inline finding before merging.
Deterministic validation for rollover drafts (RFC 1783 quality requirements):
reject generated drafts that omit the next action without disposition
complete, and reject transcript-dependent wording. Rollover reasons stay
preparation context: they never change content identity, so commit
idempotency and CAS semantics are unchanged.
Expose the advisory rollout reasons on Pi, OpenCode, DSH, and Hermes Handoff prepare and activate tools, while omitting the field for existing callers that do not supply it. Regenerate the checked-in OpenCode and DSH package outputs and cover each host boundary.
Constraint: rollover reasons remain optional preparation context and do not change Handoff content identity or commit semantics.
Scope-risk: automatic rollover policy, context-pressure detection, and provider window control remain out of scope.
Tested: pnpm --dir integrations/pi/plugins/powercontext test -- tests/tools.spec.ts; pnpm --dir integrations/opencode/plugins/powercontext test -- tests/plugin.spec.ts; pnpm --dir integrations/dsh/plugins/powercontext test -- tests/tools.spec.ts; uv run --no-sync pytest tests/builtin/artifacts/handoff/test_models.py tests/builtin/artifacts/handoff/test_generation.py tests/builtin/artifacts/handoff/test_service.py tests/builtin/artifacts/prompt/test_prompt_content.py tests/builtin/artifacts/prompt/test_prompt_validation.py tests/test_api_contract.py tests/integrations/test_hermes_provider.py -q; pnpm --dir integrations/pi/plugins/powercontext typecheck; pnpm --dir integrations/opencode/plugins/powercontext typecheck; pnpm --dir integrations/opencode/plugins/powercontext build; pnpm --dir integrations/dsh/plugins/powercontext build; uv run --no-sync ruff check integrations/hermes/plugins/powercontext/commands.py tests/integrations/test_hermes_provider.py; uv run --no-sync ruff format --check integrations/hermes/plugins/powercontext/commands.py tests/integrations/test_hermes_provider.py; uv run --no-sync ty check --python-version 3.11 integrations/hermes/plugins/powercontext/commands.py tests/integrations/test_hermes_provider.py; git diff --check
Remove the maxItems constraint from DSH rollover reason schemas because the host value-schema DSL rejects it during plugin loading. Retain the array and enum constraints in the adapter; the API contract remains authoritative for the six-item limit.
Constraint: rollover reasons remain optional, advisory preparation input; the server continues to enforce its public request limit.
Scope-risk: this only restores DSH runtime compatibility and does not add automatic rollover policy or change Handoff content identity.
Tested: pnpm.cmd --dir integrations/dsh/plugins/powercontext test; pnpm.cmd --dir integrations/dsh/plugins/powercontext build; node --test --test-concurrency=1 --test-name-pattern 'documented setup installs the matched plugin' runtime.test.mjs; git diff --check
Reject rollover drafts whose next action depends on the old session through continue-above wording. This preserves the RFC fresh-session quality floor.
Constraint: rollover reasons remain advisory preparation input and do not change Handoff identity or commit semantics.
Scope-risk: no host rollover policy, session-window control, or durable content behavior changes.
Tested: uv run --no-sync pytest tests/builtin/artifacts/handoff/test_models.py tests/builtin/artifacts/handoff/test_generation.py tests/builtin/artifacts/handoff/test_service.py tests/builtin/artifacts/prompt/test_prompt_content.py tests/builtin/artifacts/prompt/test_prompt_validation.py tests/test_api_contract.py -q (175 passed); uv run --no-sync ruff check src/powercontext/builtin/artifacts/handoff/service.py tests/builtin/artifacts/handoff/test_service.py; uv run --no-sync ruff format --check src/powercontext/builtin/artifacts/handoff/service.py tests/builtin/artifacts/handoff/test_service.py; uv run --no-sync ty check --python-version 3.11 src/powercontext/builtin/artifacts/handoff/service.py tests/builtin/artifacts/handoff/test_service.py; git diff --check
The reason will be displayed to describe this comment to others. Learn more.
Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.
This branch has not been deployed
No deployments
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
PsiACE
left a comment
knqiufan
left a comment
Which issue or RFC does this PR close?
No tracking issue is assigned. This PR proposes RFC #1783 and includes the initial compatible Handoff implementation.
Rationale for this change
Long Agent sessions can accumulate stale assumptions, noisy context, and compaction loss. PowerContext already has Handoff as the evidence-backed work-continuity boundary, so this PR treats long-session rollover as a Handoff lifecycle event rather than transcript compaction, a new Notes family, or automatic Memory creation.
The implementation follows the RFC's compatibility constraint: rollover reasons are advisory preparation inputs. They can guide draft generation toward a fresh-session checkpoint, but they do not become committed Handoff content identity, do not authorize commit or execution, and do not change Continue or Memory semantics.
What changes are included in this PR?
docs/en/rfcs/1783-handoff-session-rollover.md.docs/zh/rfcs/1783-handoff-session-rollover.md.rollover_reasonsto Handoff prepare and activation requests.openapi/powercontext.yaml.Are there any user-facing changes?
Yes. Handoff prepare and activation HTTP requests now accept optional advisory
rollover_reasonsvalues:user_requestedhost_context_budgethost_compactioncontext_qualitydelegationmanual_checkpointExisting requests remain compatible because the field defaults to an empty list.
How was this change tested?
uv run --no-sync pytest tests/builtin/artifacts/handoff/test_models.py tests/builtin/artifacts/handoff/test_generation.py tests/builtin/artifacts/handoff/test_service.py tests/test_api_contract.py -qmake contract-testuv run --no-sync ruff check <changed Python files>uv run --no-sync ruff format --check <changed Python files>uv run --no-sync ty check --python-version 3.11 <changed Python files>git diff --checkAI usage statement
Used OpenAI Codex to draft the bilingual RFC, review it against the existing Handoff implementation, implement the compatible rollover-reason path, and run local validation.