Skip to content

refactor(assistant): finalize unified governance storage#449

Merged
kaizhou-lab merged 20 commits into
mainfrom
feat/assistant-governance-data-unification
Jun 12, 2026
Merged

refactor(assistant): finalize unified governance storage#449
kaizhou-lab merged 20 commits into
mainfrom
feat/assistant-governance-data-unification

Conversation

@kaizhou-lab

@kaizhou-lab kaizhou-lab commented Jun 10, 2026

Copy link
Copy Markdown
Contributor

Background

This backend PR is not just adding a few new assistant fields. It restructures assistant data into a unified governance model that can support the phase-1 frontend, conversation creation, runtime restoration, and downgrade compatibility.

Before this change, assistant-related data was split across:

  • assistants
  • assistant_overrides
  • builtin assets (assistants.json / rules / avatars)
  • conversation extra

That fragmentation caused several problems:

  • builtin and custom assistants behaved differently
  • remembered values and fixed defaults were mixed together
  • conversation restoration still depended on extra
  • the phase-1 governance UI and Guid could not rely on one assistant model

What This PR Changes

1. Introduces unified assistant governance storage

This PR formalizes three core storage layers:

  • assistant_definitions
    • canonical assistant definition
    • stores stable identity, profile, rules, recommended prompts, and default model / permission / skills / MCP
  • assistant_overlays
    • user-side overlay state
    • stores enabled state, sort order, last used time, and main-agent override
  • assistant_preferences
    • remembered values for auto mode

Key points:

  • builtin and user assistants are both materialized into assistant_definitions
  • extension assistants are no longer part of the unified assistant catalog
  • the legacy builtin skills/ directory is removed from governance semantics
  • avatars are normalized into avatar_type + avatar_value

2. Moves assistant snapshots out of conversation extra

This PR adds:

  • conversation_assistant_snapshots

This table is used to:

  • freeze assistant-bound conversation values at creation time
  • restore assistant conversations from a conversation-level source of truth
  • persist runtime changes for assistant-bound conversations without depending on extra

This also clarifies runtime ownership:

  • assistant conversation: conversation_assistant_snapshots
  • plain ACP conversation: acp_session
  • plain aionrs conversation: existing conversations.model-based runtime path

3. Clarifies default semantics as auto | fixed

Default mode handling is reduced to two supported semantics:

  • auto
  • fixed

The service behavior is now:

  • auto -> fixed
    • the request must carry the fixed value
    • the service also seeds that value into assistant_preferences
  • fixed -> auto
    • the service clears the remembered value for that item from assistant_preferences
  • fixed values are no longer treated as remembered values
  • only auto participates in preference replay semantics

4. Aligns assistant conversation creation and runtime updates

  • assistant conversation creation now uses an explicit top-level assistant request object
  • only assistant governance fields introduced on this branch were moved out of extra
  • existing main conversation extra fields remain untouched
  • creating an assistant conversation now:
    • writes conversation_assistant_snapshots
    • writes assistant_preferences only for auto
  • runtime updates inside assistant conversations now:
    • update snapshots
    • additionally update preferences for auto
  • plain agent conversations keep their original runtime behavior and are not polluted by assistant governance defaults

5. Preserves downgrade compatibility

  • builtin assets remain the authoring source, but runtime reads come from unified storage
  • assistants / assistant_overrides are retained as downgrade mirrors
  • builtin assistants are no longer mirrored back into legacy assistants, preventing duplication on old versions
  • branch-only repair logic used during local development was removed from the final code path; the final branch keeps the normal migration path only

Design Impact

This PR resolves four core design issues:

  1. assistant definition, per-user overlay, and remembered values are stored as separate concepts
  2. assistant conversations and plain agent conversations use different runtime truth sources
  3. assistant snapshots are no longer mixed into conversation.extra
  4. the phase-1 governance UI and Guid can consume one consistent assistant model

Verification

  • just push
  • cargo nextest run --workspace
  • assistant / conversation / migration / app e2e coverage is included in branch verification

@kaizhou-lab kaizhou-lab enabled auto-merge (squash) June 12, 2026 10:09
@kaizhou-lab kaizhou-lab merged commit aba2d2a into main Jun 12, 2026
6 checks passed
@kaizhou-lab kaizhou-lab deleted the feat/assistant-governance-data-unification branch June 12, 2026 10:17
piorpua pushed a commit that referenced this pull request Jun 12, 2026
🤖 I have created a release *beep* *boop*
---


##
[0.1.29](v0.1.28...v0.1.29)
(2026-06-12)


### Features

* converge team mode runtime architecture
([#464](#464))
([abeb9a1](abeb9a1))
* **stt:** streaming transcription proxy over websocket
([#455](#455))
([1c19a8b](1c19a8b))


### Bug Fixes

* **agent:** validate managed ACP platform binaries
([#462](#462))
([651c79f](651c79f))
* **cron:** retry busy jobs from runtime state
([#459](#459))
([9918058](9918058))
* isolate ACP cancel turn completion
([#461](#461))
([ea01ee6](ea01ee6))
* **office:** probe star-office preferred_url host as given
([#456](#456))
([3c2149c](3c2149c))


### Code Refactoring

* **assistant:** finalize unified governance storage
([#449](#449))
([aba2d2a](aba2d2a))


### Documentation

* clarify production logging guidance
([#460](#460))
([118ed03](118ed03))

---
This PR was generated with [Release
Please](https://github.com/googleapis/release-please). See
[documentation](https://github.com/googleapis/release-please#release-please).

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant