Repository navigation
Reader chat history, audit conversations, and the localhost client - #6
Conversation
There was a problem hiding this comment.
🟡 Changes recommended
Unresolved issues let denied cross-caller requests misattribute audit usage and costs and block owners’ history access, while expired history cursors can trigger invalid database queries.
3 open issues
What changed in this PR
Adds reader chat history and conversation-level auditing to OrcaSonar, supporting chat panels and the OrcaSonar Console.
Changes:
- Adds 30-day reader history and paginated audit conversation summaries.
- Preserves displayed citations in saved exchanges and reports answer cost.
- Adds a caller-based DynamoDB index and beta-only localhost client authentication, with updated tests and documentation.
| File | Description |
|---|---|
test/stage.test.ts |
Tests new routes, index permissions, projection, and allowed clients. |
README.md |
Introduces history and beta localhost access. |
infrastructure/stage/stateless-stack.ts |
Wires new routes and grants caller-index access. |
infrastructure/stage/stateful-stack.ts |
Adds the caller-based audit index. |
infrastructure/stage/constants.ts |
Defines the caller index and projected attributes. |
infrastructure/stage/config.ts |
Makes allowed clients stage-specific. |
infrastructure/shared/platform.ts |
Defines the localhost client parameter and documents proxy access. |
docs/tech.md |
Documents history privacy, storage, and index readiness. |
docs/runbook.md |
Updates audit authentication guidance. |
docs/project.md |
Includes history and localhost access in release scope. |
docs/design.md |
Updates architecture diagrams and API descriptions. |
docs/deploy.md |
Documents localhost prerequisites and index deployment sequencing. |
docs/architecture.md |
Describes new routes, indexing, and cost reporting. |
docs/api.md |
Documents history, audit summaries, citations, cost, and paging. |
app/src/testing/fakes.ts |
Adds caller-scoped audit reads to the test store. |
app/src/services/stores.ts |
Defines saved citations and caller-index query contracts. |
app/src/services/history.ts |
Filters and maps audit entries into reader history. |
app/src/services/chat.ts |
Saves full citations and returns answer cost. |
app/src/services/audit.ts |
Aggregates exchanges into conversation summaries. |
app/src/server.ts |
Adds local request examples in comments. |
app/src/lib/pages.ts |
Adds cursor-window validation and key-based pagination. |
app/src/aws/dynamodb.ts |
Implements caller-index reads and shared query pagination. |
app/src/aws/adapters.test.ts |
Tests caller-index query parameters and pagination. |
app/src/app.ts |
Adds endpoints, cursor handling, and no-store responses. |
app/src/app.test.ts |
Tests history, audit summaries, costs, citations, and access controls. |
app/schema/openapi.yaml |
Defines new endpoints, response schemas, and shared parameters. |
Review effort: Balanced
There was a problem hiding this comment.
🟡 Changes recommended
Pagination can permanently skip late-visible conversations, while partial write failures can cause ownership checks to reject callers whose successful exchanges remain in their history.
2 open issues
3 resolved since last review
1 file not reviewed
pnpm-lock.yaml: Generated file
Review effort: Balanced
There was a problem hiding this comment.
🟡 Changes recommended
Pagination cursors can exceed the 4,000-character input limit and 100-ID cap, causing subsequent history requests to fail unless state is bounded while preserving duplicate prevention.
2 resolved since last review
1 file not reviewed
pnpm-lock.yaml: Generated file
Review effort: Balanced


Summary
done. Saved answers keep their citations exactly as the reader saw them.API
GET /chat/history{items: [{conversationId, title, startedAt, lastAt, questions}], nextCursor?}GET /chat/history/{conversationId}403for someone else's,404if not in historyGET /audit/conversationsadmin(beta:*)/audit/exchanges, plustotalAlso changed, all additive:
doneevent and JSON response carrycostUsd.ref,title,site,snippet, and the score rounded to 3 places. Older entries keep{id, url, score}.Cache-Control: no-store.History takes the caller from the token's
sub, never from a parameter. It copies fields one by one, so no email,client, cost, tokens or model reach the reader. Failed exchanges are left out.
Storage and infrastructure
audit-by-caller(callerId,at). It projects onlyconversationId,questionandoutcome, so listing conversations never reads answers. Only audit items havecallerId, so the index holds nothingelse. There is no new table.
/chat/history…and may query only that index. The audit Lambda serves/audit/conversations./cognito/localhost-app/app-client-id. Prod and CORS are unchanged: a local app callsthe API through its dev server's proxy.
Paging
Lists are built in memory and paged by
lastAt#conversationId. The cursor carries its window, so a conversation thatgets a new question mid-paging is neither repeated nor skipped. Cursors aren't signed, so their window is now checked:
at most 31 days for audit lists and 30 for history, and history never reads back past the last 30 days. The budget
($50 a month in prod, $0.40 per reader per day) bounds how much a window holds.
Deploy
/cognito/localhost-app/app-client-idin dev's SSM.audit-by-callerwith projectionALL, deploybeta's stateful stack from
mainbefore merging, which removes it. The merge then adds it back.ACTIVE(CloudFormation doesn't wait for it), then deploy stateless. Forprod: approve stateful, wait for the index, then approve stateless.
Known trade-offs
from history. History will need its own conversation items if audit retention changes or readers can delete
conversations.