feat(workspace): suggestions — what you can do with this agent, and what is waiting (abilityai/trinity-enterprise#465)

[dolho]

Summary

A platform user who opens an agent in the Workspace now gets a short list of suggestions computed for them and that agent. Each item names the evidence behind it, and each has two verbs:

• Accept puts /playbook in the composer (it never sends, per ent#138), opens the right section, or deep-links to the operator schedules tab. The deep link follows the engine-bay ruling (decision 15, option 1).
• Dismiss holds until the underlying state changes.

Nothing is padded: with nothing to say, the list says so.

📸 Walkthrough (light and dark, local demo stack, seeded data): https://claude.ai/artifact/EHEC68JByxJ8k392CYx2XC

v1 classes

Order is display priority. At most 5 are shown, and the list states the total.

Class	Kind	Emitted when	Who sees it
asks	invoke	a pending ask addressed to me	the addressee
decisions_due	invoke	a decision on my seat is past review_by	the seat
schedule_failing:<id>	configure	the last ≥3 terminal runs failed; skipped and cancelled runs are stepped over	owner or admin
autonomy_held	configure	autonomy is off and enabled schedules or overdue reminders exist. One item, not one per schedule.	owner or admin
schedule_never_fired:<id>	configure	past the cron's first expected fire, never run (autonomy on)	owner or admin
schedule_disabled:<id>	configure	disabled for ≥7 days and it used to run	owner or admin
dormant	invoke	my last message here is ≥14 days old	me
unused_playbook:<name>	invoke	an exposed playbook I haven't run (≤3), excluding ones a schedule already runs	me

Design decisions

Door

• Platform door only. A verified-email portal token gets a uniform 404 on both read and write (the ent#78 auth-path invariant).
• Configure items go only to the owner or an admin, the same audience that may enable a schedule (OwnedAgent).
• PortalPrincipal.is_admin requires role == admin AND a scope in ADMIN_GATE_SCOPES. It exists for this one decision; elsewhere a non-owner admin stays a viewer (ent#358).

Dismissal

• The fingerprint is the identity of the state, never a count: the first failure of a streak, the set of held schedules.
• The feedback POST recomputes and 404s any key not currently emitted, so writes are bounded and the fingerprint is always the server's.

Honesty

• The copy says "haven't run /name", not "never used": only explicit slash invocations are detectable, and that's recorded in the requirement.
• "Capabilities unavailable" is stated, never implied, when the agent doesn't answer.

Cost

• No LLM call.
• At most one bounded briefing fetch per request, cached 60 s and skipped for a stopped agent.
• One windowed runs query over live schedules only.

Deferred (filed and linked under epic ent#78):

• ent#698: a suggestion that consults another agent.
• ent#699: suggestions derived from the conversation.

Changes

• Backend: src/backend/client_portal/suggestions/ (router → service → db), portal_auth.py (is_admin), main.py (router registered).
• DB, both tracks: workspace_suggestion_feedback in schema.py, tables.py and migrations.py, plus Alembic 0073_workspace_suggestion_feedback (single head over 0072). CASCADE entry in agent_cleanup.py.
• Frontend:
  • PortalSuggestions.vue, placed in the Info tab (full) and between the agent identity and "Things you can ask" on an empty chat (compact).
  • The clientPortal store gets its suggestions slice.
  • portalRail.js: Info lights the updated dot with a note ("Info · 8 suggestions"). This amends ent#547's "static tab".
• Docs: requirement core-agent.md §5.39, architecture/workspace.md, feature-flows/workspace-suggestions.md (plus the rail flow amendment), design-system p27 note, and two learnings.md entries.
• Journey: J13 catalog entry, strict-xfail skeleton, JOURNEYS.md regenerated.

Test Plan

• cd tests && pytest unit/test_ent465_suggestions.py: 53 passed. Covers every threshold at its boundary, the SQL on a real SQLite file, the doors, bounded writes, a stopped agent never calling the briefing, and the is_admin wiring (red with the wiring reverted).
• Frontend npm run test:unit: 166 files, 3,575 passed, including the mounted portalSuggestions.spec.js with 13 tests (accept, dismiss, rollback, the two races, states, compact).
• Schema, migration, Alembic, parity, cleanup, models and docs guards: 1,000 passed. check_alembic_heads.py: one head.
• Live on a local stack (SQLite): Alembic and the SQLite migration applied at boot; the API returns the table above for an owner; screenshots in both themes. The walkthrough caught two UI defects the unit tests could not (the empty-chat list scrolled out of view, and a false "capabilities only" note); both are fixed and pinned.
• Full backend unit suite diffed by node id against a clean dev baseline: still running at the time of opening. I'll post the result as a comment.

⚠️ Alembic: #2984 also adds a 0073_* revision off 0072. Whichever lands second re-chains to 0074 and runs check_alembic_heads.py.

Fixes abilityai/trinity-enterprise#465

🤖 Generated with Claude Code

[dolho]

/review report: PR #3000

Branch: feature/ent465-suggestions → dev (merge-base 96795e2)
Files changed: 34 (+2,5xx / −27)
Scope: CLEAN. Every file belongs to the feature.
Plan completion: 15 of the issue's ACs done. 1 changed: the usage per-skill dimension is limited to explicit /name invocations, a decision recorded in §5.39. 4 deferred with issues filed: the 2026-09-21 cross-agent ACs → ent#698. The 2026-09-22 conversation-derived signal → ent#699. ent#178 curated set → fallback ladder, as the AC allows.

Execution coverage

changed symbol	executed by	live consumer	verdict
service.build / shape / failure_streak / first_expected_fire	TestRules, TestShape (boundaries at an injected now)	get_suggestions	✅
suggestions/db.py (runs window, usage, history, feedback upsert and cap)	TestSql on a real SQLite file	_gather, record_feedback	✅
_gather / _compute composition	TestGatherEndToEnd (added in this review)	router	✅ red if schedule ids are dropped, or if has_runs is dropped
record_feedback (recompute, 404, 422, server fingerprint)	TestService	POST route	✅
router._gate (door, roster, limiter)	TestDoors (TestClient)	main.py include	✅
PortalPrincipal.is_admin wiring	test_the_platform_door_stamps_is_admin_on_the_principal	_gate, can_configure	✅ red with the wiring reverted
store slice (load, share, dismiss, rollback, latest wins)	portalSuggestions.spec.js, mounted (14)	PortalSuggestions.vue	✅ the "latest wins" test is red without its guard
portalRail.js note and Info signal	portalRail.spec.js (pure)	PortalRail, PortalRailStrip	✅
Portal.vue infoSignal / watch / openSuggestionSection	none mounted (the view is too heavy)	live walkthrough: dot, compact list	✅ live only

Source-text hit: portalRail.spec.js reads Portal.vue for the railSignals spread. That's a pre-existing guard whose intent is kept, and 🛡 its consumer is the shell.

Critical findings

None.

Informational findings (all fixed in 799fa98 / eb04835 unless noted)

• I1, performance: the streak window ranked chat and API runs (schedule_id='__manual__'). Now restricted to live schedule ids.
• I2 / I3, frontend races:
  • Both placements now share one in-flight load.
  • A dismiss during a reload no longer brings the item back.
  • A failed dismiss restores only its own item.
  • An older load that answers late no longer overwrites a newer one.
• I4, copy: a console-only owner was told "you haven't talked to this agent yet". Attributed runs now count as history.
• I5, bound: the briefing cache is now bounded.
• I6, docs: two passages still called Info a "static" tab. Both amended.
• I7, deferred: "Show decisions" accepted from the empty chat opens Info without scrolling to Decisions. Recorded as a known limit and as debt.
• I8, deferred: under SQLite, concurrent feedback writes can hit SQLITE_BUSY. There is no data loss; the UI restores the item with an inline error. Recorded as a known limit and as debt.

Clean categories

• SQL: all parameterised via SQLAlchemy. Both migration tracks are additive, 0073 is the single head, and CASCADE is registered. ON CONFLICT … accept_count + 1 is valid in both dialects; it's unit-proven on SQLite, and PostgreSQL is UNVERIFIED beyond the Alembic apply.
• Auth:
  • Order is door, then roster, then limiter; a portal token gets a uniform 404 on both GET and POST.
  • Configure items reach only the owner or an admin, where admin means role AND ADMIN_GATE_SCOPES and fails closed.
  • The feedback write can't target a configure key the viewer isn't shown.
  • No route collision across routers.
• Exposure:
  • A schedule's message never leaves the service.
  • Agent-authored names are capped, and nothing uses v-html.
  • The deep link is quoted, and the client follows only /agents/ paths.
• Enterprise docs guard: 0 hits.
• Cron runs: they carry no source_user_email (ExecutionOrigin()), so "history" means runs a person started.

Summary

• Critical: 0.
• Informational: 8, of which 6 fixed and 2 deferred (recorded in the flow doc and DEBT_INBOX).
• Still pending: the full backend suite diffed against a dev baseline. The result will follow in a comment.

[dolho]

Full backend unit suite, diffed by node id against a clean dev baseline (the outstanding Test Plan item):

	passed	failed	skipped
dev @ 96795e2	17,857	55	33
this branch	17,907	55	33

No new failures. The 55 failing node ids are identical on both sides. They're local-environment failures, not caused by this PR: DNS/SSRF resolution, IPv6 origin, git-refresh hooks and objective-join container reads, run on a Python 3.12 venv against 3.13 images. The +50 passed are this PR's new tests.

[vybe]

merge-train (2026-09-24): not on this train — Alembic fork, rides the next one once re-parented.

Validated at lane B+schema: READY (db→service path executed over real SQLite, portal endpoints gated through get_portal_principal with uniform 404, both tracks byte-identical). Held back only because 0073_workspace_suggestion_feedback parents on 0072_agent_capability_grants, shared with #2989 and #3003 which are on this train. Once #3003 lands, please re-parent onto 0074_role_readiness_rollout_seed (rename + revision/down_revision), merge dev, and keep both entries in migrations.py, requirements/core-agent.md and tests/registry.json (rebuild the registry from the stages, don't splice markers). If #2997 lands before you, chain on its revision instead.

[github-actions]

⚠️ Alembic head fork if this PR is merged into dev.

dev has advanced since this PR's checks last ran. GitHub recomputes the merge ref when the base moves but does not re-trigger workflows, so a green schema-parity here can describe a base that no longer exists (#2533).

scripts/ci/check_alembic_heads.py against dev + this PR, merged in memory

alembic-heads: FAIL — src/backend/migrations/versions resolves to 2 heads across 79 revision(s); exactly 1 is required.
  • 0075_workspace_suggestion_feedback  (0075_workspace_suggestion_feedback.py)
  • 0077_execution_chain_depth  (0077_execution_chain_depth.py)

They fork at: 0074_role_readiness_rollout_seed  (0074_role_readiness_rollout_seed.py)

`alembic upgrade head` is singular and resolves its target BEFORE applying anything,
so this graph applies ZERO revisions — every revision since the fork stops arriving,
not only the one that forked. Fix by chaining the newer revision off the real head,
or — if the forked revision may already be applied somewhere — by adding a merge
revision (`alembic merge -m "…" <head-a> <head-b>`), whose tuple `down_revision`
converges the line from any starting state. See Architectural Invariant #3.
alembic-heads: src/backend/enterprise/backend/migrations/versions — version directory absent (submodule not initialised) — skipped.

Evaluated on the version line only — this PR also conflicts with dev in 4 unrelated file(s), which do not change this verdict but must be resolved before merge:

src/backend/client_portal/portal_auth.py
src/backend/db/migrations.py
tests/registry.json
tests/unit/test_2198_portal_batch_sessions.py

Fix: rechain this PR's revision off 0077_execution_chain_depth (the current dev head), or — if the forked revision may already be applied somewhere — add a merge revision (alembic merge -m "…" 0075_workspace_suggestion_feedback 0077_execution_chain_depth), whose tuple down_revision converges the line from any starting state. See Architectural Invariant #3.

Push the fix and schema-parity re-checks it against the merge ref immediately; this comment clears on the next push to dev touching src/backend/migrations/versions/**.

Advisory — this check does not block merge. · head_sha: 721d52601b1e1c4652c16be41605bf2555ba5a54 · run

[github-actions]

⚠️ Nightly unit-suite check skipped — merge conflict against dev.

Resolve by running git merge dev locally and pushing the result. The next nightly run will re-test once the conflict is gone.

[github-actions]

⚠️ Live-instance suite skipped — merge conflict against dev.

Resolve by merging dev locally and pushing the result; the next nightly re-tests.

[vybe]

merge-train (2026-09-27): three commits pushed to this branch, all mechanical. Validated at lane B + schema on 721d52601: READY, no criticals. It merges once the checks on the new head are green.

1. 7a4ce9968 merges dev. The one conflict worth reading is client_portal/portal_auth.py: feat(operator-queue): ask endings — one sink, endings ledger, person-only endings, wake on any ending, self-readback (abilityai/trinity-enterprise#611, PR A of 2) #3023 (now on dev) also added a third field to PortalPrincipal, is_person: bool = True. dev's field stays third, because code on dev already constructs it positionally, and is_admin goes last, as its own comment asks. get_portal_principal now passes both: PortalPrincipal(email, True, is_person_principal(user), _is_admin_principal(user)). The one positional construction that meant is_admin (test_ent465_suggestions.py, PortalPrincipal("a@example.com", True, True)) would have silently set is_person after the merge, so it now names the field. test_2198 keeps your by-field assertion. migrations.py and tests/registry.json are keep-both, dev's entries first, with the registry rebuilt from the merge stages.
2. 8a4e90345 merges dev again after fix(dispatch): refuse agent-to-agent hops past a chain-depth limit (#2806) #2997 landed (keep-both on the MIGRATIONS tail).
3. 8670cd03f renames the revision to 0078_workspace_suggestion_feedback with down_revision = "0077_execution_chain_depth", and updates the docstring in db/migrations.py and the flow doc. check_alembic_heads.py reports one head. The SQLite entry is keyed by name and is unchanged.

1,491 tests pass locally on the merged tree (portal, Workspace, ent#611, #2806, and the migration and Alembic guards).

Follow-ups, not blocking:

• stores/clientPortal.js:578 / :1127: signOut() does not reset the suggestions slice, and sign-out is an SPA push, so a second platform user in the same tab can see the previous user's list for up to 60 s. The decisions and memory slices share this gap.
• The shell wiring (Portal.vue:1133-1150, :1189-1194; PortalAgentDetails.vue:245-248) has only a source-text pin (portalRail.spec.js:869-874), no executing test.
• The two new endpoints are missing from api-endpoints.md and the table from database.md.
• PortalSuggestions.vue:20: the skeleton needs motion-reduce:animate-none.
• Portal.vue:1133: the Info dot stays lit while any undismissed suggestion exists, because Accept never hides an item.
• workspace-suggestions.md lacks the standard flow-doc sections.
• The PR body still names 0073.
• ent#465 is a private-tracker feature shipped ungated as OSS core. I found no recorded decision for that; flagging it for the owner.

[vybe]

Validated at lane B + schema: READY, no criticals. After the merge-train commits (two dev merges, revision re-parented to 0078), all 24 checks are green on 8670cd0, including pytest (head), e2e, pg-migrations, schema-parity and both CodeQL analyses. Follow-ups are in the comment above.