Files
streamline/docs/eddy/conversations.md
T
2026-11-16 17:26:44 -08:00

111 lines
8.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Eddy main-Agent conversation sync
The Eddy setting is opt-out, enabled by default; there is no separate sync confirmation.
The client first requires the person's Streamline SSO session and a task-bound source.
It uploads that entire source session's available visible history and new records,
including user/assistant messages and tool calls/results, without the summary reader's text budget.
Hidden reasoning, system/developer instructions, Claude sidechain records and binary attachments
are excluded. Recognizable credentials are masked on the client on a best-effort basis.
This is not a complete multimedia replay or a guarantee of arbitrary-secret detection.
`POST /api/eddy/conversations`: schema 1, batchId (sha256), taskId, taskTitle, sourceId (sha256),
provider (codex/claude/file), machine (16 hex), events (1–64). Body is limited to 512 KiB.
Each event contains id, streamId (optional hash of the log basename), position (byte offset), block,
part (zero-based), parts, kind (message/tool_call/tool_result/attachment), role, text, redacted,
and optional timestamp/toolName/callId. Unknown properties are discarded.
Long text parts are reconstructed in streamId/position/block/part order; identical repeated messages
retain different event ids. The server acknowledges `{batchId, accepted}` after its atomic insert.
Duplicate event delivery is accepted without another row. Ownership is part of the deduplication key.
`GET /api/eddy/conversations?task=<taskId>&machine=<machine>&source=<sourceId>&cursor=<sequence>&limit=100`:
returns `{events, nextCursor}`, 1–500 records per page in insertion-sequence order.
Each envelope carries taskId/taskTitle, sourceId/provider, machine, receivedAt, sequence and event.
Use nextCursor until null. Same main session bound to several Eddy tasks is intentionally associated
with all those tasks; these records are not a claim of per-message task attribution.
## Viewing history
The SSO-only `/eddy/tasks` page is linked from the account menu (“我的 Eddy 任务”) and
Management → Eddy (“我的任务与会话”). It is available to ordinary signed-in users,
independent of the administrator-only usage/knowledge panels. Each user sees their own
records there. Browser-SSO Streamline administrators can also read every account's history
(internal employee data): `/eddy/tasks?scope=all` (linked from Management → Eddy as
「全部用户任务与会话」) adds a per-account summary (tasks, sessions, devices, records, first/last
sync), an account filter and the owner on each task; an Eddy session never grants this.
The standalone page does not boot the task board or its background fetches.
- Search tasks by latest reported title or task id; same task id on two installations
is displayed separately. Task titles reflect the latest received event, not a live
task metadata mirror. Tasks with no uploaded conversation do not appear.
- Select a Codex/Claude/imported source; the task, machine and source ride in the URL
for refresh/back/forward. Opening the link still requires the same SSO owner.
- Read available visible messages in source-file position order. Text split over upload
or read pages is reconstructed; incomplete parts are labelled until loaded. Repeated
messages are preserved. Tool calls/results are collapsed and all content renders as
inert text. No remote images, HTML or attachment binaries are loaded by the viewer.
- “任务信息与产物” shows task identifiers and the first available user message as a
requirement reference, clearly labelled. It is not an independently maintained task
description. Screenshots, patches and snapshots are not uploaded by conversation sync;
handoff bundles remain accessible through the corresponding Streamline feature.
- Read more via bounded pages or refresh explicitly. Empty data, old server (404), expired
login (401) and retryable failures have distinct states. Private reads are `no-store`
and are not shared by the Web API's cross-component in-flight GET cache.
Metadata list APIs (same SSO/owner checks and no-store):
`GET /api/eddy/conversations/tasks?q=<title-or-id>&before=<sequence>&limit=30`
returns `{items, nextCursor}`. Each item contains `machine, taskId, taskTitle,
lastReceivedAt, lastSequence, recordCount, sourceCount`; there are no transcript bodies.
Search is literal/case-insensitive (including `%`, `_` and backslashes), at most 200 characters.
`GET /api/eddy/conversations/sources?task=<taskId>&machine=<machine>&before=<sequence>&limit=30`
requires both selectors and returns `{items, nextCursor}` with `sourceId, provider,
firstReceivedAt, lastReceivedAt, lastSequence, recordCount`. A missing or non-owned task
returns an empty list. Both lists allow 1–100 rows per page, newest received sequence first;
pass `nextCursor` as `before`. New uploads can move an item to the front during browsing;
refresh the list to see these updates. Counts are stored fragments, not message counts.
Both methods require verified browser SSO or an active Eddy SSO session, scoped by the **full email**.
No API-key, release-token, X-Eddy-User or administrator bypass. Responses are `Cache-Control: no-store`.
The historical scope string stays `eddy:knowledge:write` for existing client compatibility, as for handoffs;
these routes use the SSO identity, and do not grant admin/release rights. Nothing enters the public knowledge feed.
Switching off stops subsequent client reads and uploads after an in-flight short request finishes;
it does not delete already stored data. Switching on catches up. Logged-out clients never read transcripts.
Only acknowledged offsets/parts are stored locally. 401/404/503/offline preserve progress for retry.
An old control plane returns 404; this does not block local Eddy use.
## Rollout and validation
Apply additive `drizzle/0065_eddy_conversations.sql` using the normal deployment flow **before** the server release,
then release the client. There is no production schema/data mutation in local development.
Rolling back the client stops the worker; the additive table can remain. Stop the route to stop receiving.
```sh
# TEST_DATABASE_URL must be an explicitly isolated database.
bun test control-server/test/eddy_conversations.test.ts
TEST_DATABASE_URL=postgres://user@127.0.0.1:55483/test bun test control-server/test/eddy_conversations.integration.test.ts
# Optional actual Eddy Python → HTTP → Postgres probe, using synthetic temporary sessions only:
EDDY_TEST_SOURCE=/path/to/eddy-source TEST_DATABASE_URL=postgres://user@127.0.0.1:55483/test bun test control-server/test/eddy_conversations.integration.test.ts
```
The integration database needs `0032_eddy_sso.sql` and `0065_eddy_conversations.sql`.
Tests cover authentication, expiry, owner isolation, no admin bypass, retries, pagination, limits,
Unicode/long messages, tools, reasoning exclusion, masking and default-on/off/on catch-up.
The optional browser integration test `control-server/test/eddy_history.browser.test.ts` seeds only
synthetic records, starts a loopback HTTP fixture and cleans them up. Build the real page fixture with
`bun build control-web/test/fixtures/eddy-history.tsx --target browser --outdir /tmp/eddy-history-bundle
--define 'import.meta.env={"VITE_DEBUG":"1","DEV":true}'`, then set `TEST_DATABASE_URL` (isolated PG),
`EDDY_HISTORY_BUNDLE=/tmp/eddy-history-bundle` and run the test. The committed driver is
`control-web/test/eddyHistory.browser.mjs`; it requires Playwright/Chrome in the test environment.
`EDDY_HISTORY_BROWSER_NODE` selects Node, `EDDY_HISTORY_PLAYWRIGHT_PACKAGE` can point at a dependency
package.json from which Playwright resolves, and `EDDY_HISTORY_OUTPUT_DIR` selects the screenshots/report
directory. The driver rejects a non-loopback fixture URL; it never needs production SSO or data.
Administrator APIs (browser SSO administrator only, no-store; same pagination and validation):
`GET /api/eddy/admin/conversations/users` → `{items:[{owner, taskCount, sourceCount, machineCount,
recordCount, firstReceivedAt, lastReceivedAt}]}`; `GET /api/eddy/admin/conversations/tasks?owner=&q=&before=&limit=`
(owner optional; items carry `owner`); `GET /api/eddy/admin/conversations/sources?owner=&task=&machine=…` and
`GET /api/eddy/admin/conversations?owner=&task=&machine=&source=&cursor=&limit=` (owner required).