Skip to content

Reader chat history, audit conversations, and the localhost client - #6

Merged
raylrui merged 5 commits into
mainfrom
feat/conversations-chat-history
Nov 11, 2026
Merged

raylrui merged 5 commits into
mainfrom
feat/conversations-chat-history

Conversation

@raylrui

@raylrui raylrui commented Nov 10, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Readers can list and reopen their own conversations from the last 30 days.
  • Admins get the audit log grouped by conversation, for the OrcaSonar Console.
  • Answers report their cost on done. Saved answers keep their citations exactly as the reader saw them.
  • Beta accepts the dev pool's localhost Cognito client, so the console can run locally against dev.

API

Route Who Returns
GET /chat/history any signed-in reader Own conversations, most recently active first: {items: [{conversationId, title, startedAt, lastAt, questions}], nextCursor?}
GET /chat/history/{conversationId} its owner Its exchanges, oldest first, with answers and citations. 403 for someone else's, 404 if not in history
GET /audit/conversations admin (beta: *) The window grouped by conversation, with counts, tokens and cost. Filters and paging as /audit/exchanges, plus total

Also changed, all additive:

  • The chat done event and JSON response carry costUsd.
  • Saved sources (audit log and S3 records) are now the citations the reader was shown: ref, title, site,
    snippet, and the score rounded to 3 places. Older entries keep {id, url, score}.
  • The audit and history routes send 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

  • Sonar table: new GSI audit-by-caller (callerId, at). It projects only conversationId, question and
    outcome, so listing conversations never reads answers. Only audit items have callerId, so the index holds nothing
    else. There is no new table.
  • The query Lambda serves /chat/history… and may query only that index. The audit Lambda serves
    /audit/conversations.
  • Beta's authorizer also accepts /cognito/localhost-app/app-client-id. Prod and CORS are unchanged: a local app calls
    the 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 that
gets 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

  • Beta needs /cognito/localhost-app/app-client-id in dev's SSM.
  • A GSI's projection can't change in place. If dev's table already has audit-by-caller with projection ALL, deploy
    beta's stateful stack from main before merging, which removes it. The merge then adds it back.
  • Deploy stateful, wait for the index to be ACTIVE (CloudFormation doesn't wait for it), then deploy stateless. For
    prod: approve stateful, wait for the index, then approve stateless.

Known trade-offs

  • History is read from the audit log. An audit write that fails is logged, not thrown, so that exchange is missing
    from history. History will need its own conversation items if audit retention changes or readers can delete
    conversations.
  • The index is eventually consistent, so an answer that has just finished can take a moment to appear in the list.

@raylrui
raylrui requested a balanced review from Copilot November 10, 2026 22:08
@raylrui raylrui self-assigned this Nov 10, 2026
@raylrui raylrui added the enhancement New feature or request label Nov 10, 2026

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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

Comment thread app/src/services/audit.ts Resolved
Comment thread app/src/app.ts Resolved
Comment thread app/src/app.ts Resolved

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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

Comment thread app/src/app.ts Resolved
Comment thread app/src/lib/pages.ts Resolved

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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.

1 open issue
2 resolved since last review
1 file not reviewed
  • pnpm-lock.yaml: Generated file

Review effort: Balanced

Comment thread app/src/lib/pages.ts Resolved
@raylrui
raylrui merged commit 6cf51a4 into main Nov 11, 2026
7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants