Skip to content

feat(sessions): add human work logs #487

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sudomaggie merged 5 commits into from
Jul 22, 2026
Merged

feat(sessions): add human work logs #487

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
f3af857
feat(sessions): add human work logs
Harry19081 Jul 22, 2026
39bd776
fix(sessions): show context selectors for work logs
Harry19081 Jul 22, 2026
50d80c8
fix(work-items): keep creator agent-only
Harry19081 Jul 22, 2026
13c1d22
fix(sessions): simplify human hover metadata
Harry19081 Jul 22, 2026
a95d90b
test(sessions): include human pagination category
Harry19081 Jul 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
128 changes: 128 additions & 0 deletions docs/architecture-audit-2026-07-22/HumanSessions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,128 @@
# Architecture Audit — Human sessions

**Scope:** Append-only Human-session persistence, optional canonical titles, session-directory integration, shared creator reuse, content routing, and serialized session mentions
**Date:** 2026-07-22
**Auditor:** Codex

## Acceptance criteria

- [x] The user-facing Work log option reuses the regular session creator with an optional title in its upper Work-item-style header row and a single required note while retaining the internal Human-session type.
- [x] A blank title falls back to the existing bounded first-note preview; a nonblank title is trimmed, bounded, and persisted as the canonical session name.
- [x] Creation adds a canonical session row that appears in the Human sidebar group and opens through normal session navigation.
- [x] A Human session is an ordered, append-only note timeline.
- [x] The initial and append composers support session mentions through sidebar drag and `@` selection.
- [x] The reduced API contains only create, get, append, and delete operations.
- [x] Model polish/summarize and dedicated evidence form/storage paths are absent from the implementation.
- [x] Human content never enters agent runtime, transcript, or TUI rendering paths.

## 10-layer audit

### Layer 1 — Compilation correctness

- `pnpm typecheck` and targeted ESLint pass.
- A focused seven-file Vitest run passes 39 tests across the compact launch action, rendered timeline reuse, RPC validation, category placement, sidebar grouping, skill-pill serialization, and session-mention parsing.
- `cargo check -p org2` passes.
- `cargo test -p org2 human --lib` passes all six Human boundary tests, including explicit, blank-fallback, and over-limit title cases.
- `cargo test -p session_persistence init_session_tables_creates_human_session_entry_schema` verifies schema creation and delete cascade.
- Scoped `cargo clippy -p org2 --lib --no-deps -- -D warnings` passes.

### Layer 2 — Dead code and structural deduplication

Production call chains were traced from each entry point:

| Entry point | Forward call chain | Live owner |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| Create | Shared `SessionCreator` title input + composer → `createHumanSession` → `human_session_create` → canonical titled row + first entry → sidebar refresh → normal open | `agent_sessions::human` |
| Append | Human bottom composer → `appendHumanSessionEntry` → one transaction inserts entry and updates canonical `updated_at` → sidebar refresh | `agent_sessions::human` |
| Read/open | Aggregate directory → typed Human category → `SessionContentView` → ordered entry load | session directory + Human feature |
| Mention | Sidebar drag or `@` selection → shared Composer pill → stable serialized session reference | shared composer/DnD pipeline |
| Delete | Sidebar Human branch → `human_session_delete` → canonical delete → entry foreign-key cascade | Human command + session persistence |

There is no parallel Human creator, editable document form, model-assist service, link table, or screenshot storage path. The only Human-specific view code is the append timeline and its composer.

### Layer 3 — Naming consistency

- Rust persistence uses `session_type::HUMAN` and aggregate wire category `human`.
- Frontend routing uses `human_session`; prefix routing uses the centralized `humansession-` definition.
- `HumanSession` is the canonical metadata plus entries; `HumanSessionEntry` is one immutable note.
- User-facing copy consistently says “Work log” for the feature, “title” for its optional canonical name, and “note” or “entry” for appended content; persistence and routing retain the established Human-session identifiers. The shared mention menu says “Session,” because it is not agent-only.

### Layer 4 — Semantic overloading

| Term | Meaning | Verdict |
| ------------------ | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------- |
| Human session | Internal type for a user-authored append-only log represented in the canonical session directory | Keep; distinct category and prefix |
| Work log | User-facing name for creating and opening a Human session | Keep; describes the outcome without presenting it as an agent |
| Agent session | Runnable agent transcript/runtime | Keep; Human routing never enters it |
| Human entry / note | One immutable timestamped body in a Human session | Keep; one persistence concept |
| Session reference | Stable serialized `[session:<session-id>]` mention | Keep; references rather than embeds another transcript |

No Human field is reused as an agent prompt, transcript event, or runtime status.

### Layer 5 — Default branch analysis

- Human prefix/category checks occur before unknown-session fallback to `rust_agent`.
- Aggregate conversion and runtime artifact mapping have explicit Human branches.
- `SessionContentView` checks hydrated category and canonical prefix, allowing deep links before sidebar hydration.
- Sidebar deletion explicitly selects Human deletion; Human rows do not fall into CLI or agent deletion.
- Agent-only transcript/export controls are hidden for Human sessions.

### Layer 6 — Cross-domain concept leakage

- Human entry validation and writes stay in `agent_sessions::human`.
- Shared persistence knows only the new child table and its foreign-key cascade.
- Shared frontend extensions are domain-neutral: the design-system `Input` and its ghost-placeholder token, an accessible icon-button label, optional composer capability flags, a session-content resolver, and a clearly named `hideSessionSetupControls` creator flag. Work logs retain the shared creator's regular plus and round-arrow actions as well as its existing `SessionInfoLine` repository, branch, and location/worktree selectors. The read surface composes the existing shared Work-item activity-timeline primitives without changing their contracts.
- Human sessions reuse directory/pagination/navigation infrastructure without entering agent execution infrastructure.

### Layer 7 — New-developer confusion test

- `human.rs` begins with an append-only timeline description and exposes only four commands.
- `HumanSessionView` is the read/append surface, composes the shared Work-item activity timeline, and reuses the normal bottom `InputArea`; the regular creator reuses its existing upper `composerHeaderContent` slot and the same ghost `Input` title treatment as Work item creation, outside `EditorArea`.
- `SessionContentView` is the single visible content decision between Human timeline and agent chat.
- `TEST_CASES.md` records creation, append, mention, persistence, and deletion behavior, including explicitly deferred features.

### Layer 8 — Wire protocol and serialization

| Payload | Bound | Validation | Serialized shape |
| ---------------- | ----------------------------------------------------: | ------------------------------------------------------------------------------------ | ---------------------------------- |
| Optional title | 80 characters | trimmed and bounded in TypeScript and Rust; blank resolves to the first-note preview | `{ title? }` within create request |
| Initial note | 100,000 characters | trimmed and non-empty in TypeScript and Rust | `{ body, title?, workspacePath? }` |
| Appended note | 100,000 characters | trimmed and non-empty in TypeScript and Rust | `{ sessionId, body }` |
| Human session ID | UUID with `humansession-` prefix on the Rust boundary | canonical prefix and UUID parse | string |
| Session mention | one ID token per pill | shared parser/serializer | `Display [session:<id>]` |

No model request, base64 screenshot payload, or evidence-specific wire format remains.

### Layer 9 — Init and entry-point parity

| Entry point / host | Human recognition | Renderer |
| -------------------------- | ------------------------------ | ------------------------- |
| Main ChatPanel | category or prefix | `SessionContentView` |
| WorkStation tab | category or prefix; GUI forced | `SessionContentView` |
| Work-item floating session | category or prefix | `SessionContentView` |
| Project manager session | category or prefix | `SessionContentView` |
| Task detail session | category or prefix | `SessionContentView` |
| Sidebar initial/load-more | `human` aggregate category | normal session navigation |

All hosts use the same resolver. Only session-creation pickers expose Work logs; agent-team, benchmark, and runnable-agent selectors remain agent-only.

### Layer 10 — Resolver symmetry

| Field | Create | Append | Read |
| -------------- | --------------------------------------------------------------- | ------------------------------------------------------ | ----------------------------------------- |
| Human identity | generated canonical prefix + `session_type::HUMAN` | verified before mutation | verified before return |
| Note body | shared 100k/non-empty validation | same validation | ordered entry rows |
| Timestamps | canonical + first entry use one timestamp | transaction updates canonical row and timestamps entry | canonical metadata + each entry timestamp |
| Workspace | optional creator repository path | unchanged | canonical session value |
| Title | trimmed explicit title, otherwise bounded preview of first note | intentionally stable | canonical session name |

The entry table has one ownership chain rooted at `agent_sessions`; deleting the canonical row cascades all entries.

## Systematic sweep

- Swept session category unions, prefixes, aggregate schemas, pagination, sidebar groups, runtime artifacts, content hosts, import/export controls, and delete routing for agent-only assumptions.
- Swept direct session `ChatView` hosts and routed them through `SessionContentView`.
- Swept creator-only category picker consumers so Human is offered only where a new session can be created.
- Swept production and RPC symbols for prior document/update/model/link/screenshot concepts; none remain.
- Swept mention serialization and rehydration across the shared creator and append composer.
- Swept the former Project-Manager-owned ghost placeholder token and promoted it beside the shared `Input` component so Session Creator does not import a project-specific styling module.
24 changes: 24 additions & 0 deletions docs/frontend-ui-audit-2026-07-22/HumanSessions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
# Human sessions frontend UI audit

**Scope:** Regular creator reuse, optional Work-log titles, the single-line localized Work log option, shared slash/mention input, Work-item activity timeline reuse, sidebar/session-host routing, and shared component extensions.

**Summary:** 0 fix, 14 keep with reason, 0 abstract.

| Line | Element | Verdict | Reason | Suggested change |
| ----------------------------------------------------------------------: | -------------------------------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
| `SessionCreator/variants/ChatPanel/index.tsx:456` | Human create branch in the regular session creator | keep with reason | Reuses the existing composer, launch state, sidebar refresh, and normal session-open callback; no parallel Human creator shell remains. | None. |
| `SessionCreator/variants/ChatPanel/index.tsx:659` | Human creator input capabilities | keep with reason | Uses the same `ComposerInput`, slash-command handlers, skill pills, and `@` context pipeline as regular sessions while retaining the intentionally reduced Human launch payload. | None. |
| `SessionCreator/variants/ChatPanel/index.tsx:664` | Optional Work log title field | keep with reason | Reuses the design-system `Input` and the creator's existing upper `composerHeaderContent` slot with the same ghost mode, size, height, and placeholder treatment as Work item creation. It is outside `EditorArea`, and the note remains the only required field. | None. |
| `components/Input/tokens.ts:1` | Shared ghost-input placeholder token | keep with reason | Moving this presentation token beside `Input` lets Work items, Projects, Project content, and Session Creator share one style without importing across feature domains. | None. |
| `SessionCreator/variants/ChatPanel/index.tsx:751` | Shared session context selectors | keep with reason | Work logs render the same `SessionInfoLine` as regular sessions, including repository, branch, and location/worktree selectors. The existing shared state and handlers are reused without a Human-specific selector implementation. | None. |
| `SessionCreator/variants/ChatPanel/SessionCreatorChatPanelView.tsx:283` | Human suppression of agent-only setup controls | keep with reason | The explicit `hideSessionSetupControls` flag keeps the established creator layout while hiding model/action, presence, work-item, and file controls that do not apply; it no longer suppresses the shared session-context row. | None. |
| `SessionCreator/components/EditorArea.tsx:125` | Shared compact creator actions | keep with reason | Work logs retain the regular `ComposerBar` plus menu and round-arrow `LaunchButton`. The domain-neutral `launchAriaLabel` keeps “Create work log” for assistive technology without introducing a Human-only visible button treatment. | None. |
| `DispatchCategoryPalette/useDispatchCategoryOptions.tsx:394` | Work log placement in Built-ins | keep with reason | Both picker variants combine the single-line Work log option with built-in agents under a neutral localized Built-ins heading; the separate Session types group is removed. | None. |
| `i18n/locales/zh/sessions.json:8` | Work log, context, and skill translations | keep with reason | Every supported locale defines the Work log and Built-ins picker names, while Simplified and Traditional Chinese also define the complete Work log composer/view strings instead of displaying English fallbacks. | None. |
| `HumanSessionView.tsx:162` | Shared append-only activity timeline | keep with reason | Reuses Work items' `TimelineStack`, `ConnectedTimelineItem`, `TimelineCard`, and `TimelineCardHeader`, including their timestamp and copy behavior. The only Human-specific renderer is the read-only pill-aware note body. | None. |
| `HumanSessionView.tsx:172` | Shared floating bottom composer | keep with reason | Reuses the regular `InputArea` and its standard floating placement, send action, slash/skill pipeline, `@` mentions, error restoration, and session drag/drop behavior instead of maintaining a Work-log-specific composer. | None. |
| `InputArea/index.tsx:67` | Domain-neutral composer capability flags | keep with reason | Optional flags hide agent-only controls, filter slash categories, disable agent command interception, and opt out of file drops while all existing chat callers retain their defaults. | None. |
| `GlobalDragDrop/utils/dragDetection.ts:99` | File-drop opt-out selector | keep with reason | The data attribute prevents unsupported OS file payloads from reaching a text-only Work log while retaining the existing internal session drag target used for mention pills. | None. |
| `SessionContentView.tsx:10` | Human/chat content resolver | keep with reason | One small typed resolver keeps all session hosts visually consistent and prevents host-specific Human UI forks. | None. |

No multi-file design-system sweep candidate remains. The Work log now composes the established activity-timeline and chat-composer primitives directly; it introduces no arbitrary color values or duplicate timeline/control patterns.
Loading
Loading