@wpic/ui 0.3.5

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@wpic/ui",
+  "version": "0.3.5",
+  "type": "module",
+  "description": "WPIC shared Vue 3 component library",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "src/style.css",
+    "src/components/chat/*.md"
+  ],
+  "main": "./dist/wpic-ui.cjs",
+  "module": "./dist/wpic-ui.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/wpic-ui.js",
+      "require": "./dist/wpic-ui.cjs"
+    },
+    "./style.css": "./dist/wpic-ui.css",
+    "./dist/wpic-ui.css": "./dist/wpic-ui.css"
+  },
+  "scripts": {
+    "build": "vue-tsc --noEmit && vite build && node scripts/postbuild.js",
+    "dev": "vite build --watch",
+    "test:ui": "vite --config test-ui/vite.config.ts",
+    "postbuild": "node scripts/postbuild.js"
+  },
+  "peerDependencies": {
+    "@floating-ui/vue": ">=1",
+    "lucide-vue-next": ">=0.4",
+    "pinia": ">=2",
+    "vue": ">=3.4"
+  },
+  "devDependencies": {
+    "@floating-ui/vue": "^1.1.11",
+    "@tailwindcss/vite": "^4.2.1",
+    "@vitejs/plugin-vue": "^6.0.0",
+    "lucide-vue-next": "^0.577.0",
+    "pinia": "^3.0.4",
+    "tailwindcss": "^4.2.1",
+    "typescript": "^5.0.0",
+    "vite": "^7.3.1",
+    "vite-plugin-dts": "^5.0.0",
+    "vue": "^3.5.0",
+    "vue-tsc": "^2.0.0"
+  }
+}

package/src/components/chat/DB_SCHEMA.md

@@ -0,0 +1,440 @@
+# Chat database schema guide
+
+Use this when an app needs DB-backed chat history, sessions, projects, memory, or usage. `WChatPanel` works with local-only state, but production assistants usually need persistent tables.
+
+This guide is based on the working WPIC Perform migrations:
+
+- `migrations/20260507000000_agent.sql`
+- `migrations/20260507000001_chat_projects.sql`
+- `routes/chat.py`
+
+## When to use DB persistence
+
+Use DB-backed chat when any of these are true:
+
+- conversations must survive logout, browser changes, or device changes
+- users need conversation history and session switching
+- conversations can be grouped by project/client/workspace
+- admins need audit/debug visibility
+- token usage/cost must be tracked
+- the assistant needs durable user memory
+- the app uses tool calls that mutate business objects
+
+Use localStorage only for a first MVP where history is personal, disposable, and not needed across devices.
+
+## Core concepts
+
+Recommended model:
+
+- `wpic_chat_projects`: optional folders or workspaces inside a user/org
+- `wpic_chat_sessions`: one conversation thread
+- `wpic_chat_messages`: ordered messages in a session
+- `wpic_chat_provider_runs`: one provider/API call for observability and debugging
+- `wpic_chat_memory`: durable user facts/preferences
+- `wpic_chat_usage`: daily token/message/cost counters
+- `wpic_chat_attachments`: uploaded files, assets, or parsed text attached to messages
+- `wpic_chat_tool_events`: structured tool calls/results for audit and replay
+
+Names can vary by product. The important part is the relationship:
+
+```text
+user/org
+  -> wpic_chat_projects
+    -> wpic_chat_sessions
+      -> wpic_chat_messages
+```
+
+## Perform schema
+
+Perform uses `agent_conversations`, `agent_memory`, `agent_usage`, `chat_projects`, and `chat_sessions`.
+
+```sql
+CREATE TABLE IF NOT EXISTS agent_conversations (
+  id         BIGSERIAL PRIMARY KEY,
+  user_id    UUID NOT NULL,
+  role       VARCHAR(20) NOT NULL,
+  content    TEXT NOT NULL,
+  tokens     INT DEFAULT 0,
+  created_at TIMESTAMPTZ DEFAULT NOW()
+);
+CREATE INDEX IF NOT EXISTS agent_conv_user_idx
+  ON agent_conversations (user_id, created_at DESC);
+
+CREATE TABLE IF NOT EXISTS agent_memory (
+  user_id    UUID NOT NULL,
+  key        VARCHAR(100) NOT NULL,
+  value      TEXT NOT NULL,
+  updated_at TIMESTAMPTZ DEFAULT NOW(),
+  PRIMARY KEY (user_id, key)
+);
+
+CREATE TABLE IF NOT EXISTS agent_usage (
+  user_id       UUID NOT NULL,
+  date          DATE NOT NULL DEFAULT CURRENT_DATE,
+  input_tokens  INT DEFAULT 0,
+  output_tokens INT DEFAULT 0,
+  messages      INT DEFAULT 0,
+  PRIMARY KEY (user_id, date)
+);
+
+CREATE TABLE IF NOT EXISTS chat_projects (
+  id          BIGSERIAL PRIMARY KEY,
+  user_id     UUID NOT NULL,
+  name        VARCHAR(200) NOT NULL,
+  color       VARCHAR(20) DEFAULT '#5E6AD2',
+  created_at  TIMESTAMPTZ DEFAULT NOW(),
+  updated_at  TIMESTAMPTZ DEFAULT NOW()
+);
+CREATE INDEX IF NOT EXISTS chat_projects_user_idx
+  ON chat_projects (user_id, updated_at DESC);
+
+CREATE TABLE IF NOT EXISTS chat_sessions (
+  id          BIGSERIAL PRIMARY KEY,
+  user_id     UUID NOT NULL,
+  project_id  BIGINT REFERENCES chat_projects(id) ON DELETE SET NULL,
+  title       VARCHAR(200) NOT NULL DEFAULT 'New conversation',
+  created_at  TIMESTAMPTZ DEFAULT NOW(),
+  updated_at  TIMESTAMPTZ DEFAULT NOW()
+);
+CREATE INDEX IF NOT EXISTS chat_sessions_user_idx
+  ON chat_sessions (user_id, updated_at DESC);
+CREATE INDEX IF NOT EXISTS chat_sessions_project_idx
+  ON chat_sessions (project_id);
+
+ALTER TABLE agent_conversations
+  ADD COLUMN IF NOT EXISTS session_id BIGINT REFERENCES chat_sessions(id) ON DELETE CASCADE;
+CREATE INDEX IF NOT EXISTS agent_conv_session_idx
+  ON agent_conversations (session_id, created_at ASC);
+```
+
+Perform saves user and assistant rows only after the final assistant response is known, then updates `chat_sessions.updated_at` and upserts daily `agent_usage`.
+
+## Recommended `wpic_chat_*` schema
+
+For new apps, use the `wpic_chat_*` prefix to avoid collisions with existing app tables. Include `app` so Studio, Perform, admin, support, or future apps can share the same table family without logical collisions.
+
+```sql
+CREATE TABLE wpic_chat_projects (
+  id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  app             TEXT NOT NULL DEFAULT 'studio',
+  organization_id UUID NOT NULL,
+  created_by      UUID NOT NULL,
+  name             TEXT NOT NULL,
+  color            TEXT NOT NULL DEFAULT '#5E6AD2',
+  metadata         JSONB NOT NULL DEFAULT '{}'::jsonb,
+  created_at       TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at       TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  deleted_at       TIMESTAMPTZ
+);
+CREATE INDEX idx_wpic_chat_projects_owner
+  ON wpic_chat_projects (app, organization_id, created_by, updated_at DESC);
+
+CREATE TABLE wpic_chat_sessions (
+  id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  app             TEXT NOT NULL DEFAULT 'studio',
+  organization_id UUID NOT NULL,
+  created_by      UUID NOT NULL,
+  project_id       UUID REFERENCES wpic_chat_projects(id) ON DELETE SET NULL,
+  title            TEXT NOT NULL DEFAULT 'New conversation',
+  metadata         JSONB NOT NULL DEFAULT '{}'::jsonb,
+  created_at       TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at       TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  deleted_at       TIMESTAMPTZ
+);
+CREATE INDEX idx_wpic_chat_sessions_owner
+  ON wpic_chat_sessions (app, organization_id, created_by, updated_at DESC);
+CREATE INDEX idx_wpic_chat_sessions_project
+  ON wpic_chat_sessions (project_id, updated_at DESC);
+
+CREATE TABLE wpic_chat_provider_runs (
+  id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  app             TEXT NOT NULL DEFAULT 'studio',
+  organization_id UUID NOT NULL,
+  user_id          UUID NOT NULL,
+  session_id       UUID REFERENCES wpic_chat_sessions(id) ON DELETE SET NULL,
+  provider         TEXT NOT NULL,
+  model            TEXT NOT NULL,
+  status           TEXT NOT NULL DEFAULT 'running'
+    CHECK (status IN ('running','succeeded','failed','cancelled')),
+  request_id       TEXT,
+  input_tokens     INT NOT NULL DEFAULT 0,
+  output_tokens    INT NOT NULL DEFAULT 0,
+  cost_usd_micros  BIGINT NOT NULL DEFAULT 0,
+  latency_ms       INT,
+  error            TEXT,
+  request          JSONB NOT NULL DEFAULT '{}'::jsonb,
+  response         JSONB NOT NULL DEFAULT '{}'::jsonb,
+  metadata         JSONB NOT NULL DEFAULT '{}'::jsonb,
+  started_at       TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  completed_at     TIMESTAMPTZ
+);
+CREATE INDEX idx_wpic_chat_provider_runs_owner
+  ON wpic_chat_provider_runs (app, organization_id, user_id, started_at DESC);
+
+CREATE TABLE wpic_chat_messages (
+  id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  app             TEXT NOT NULL DEFAULT 'studio',
+  organization_id UUID NOT NULL,
+  session_id       UUID NOT NULL REFERENCES wpic_chat_sessions(id) ON DELETE CASCADE,
+  created_by       UUID NOT NULL,
+  provider_run_id  UUID REFERENCES wpic_chat_provider_runs(id) ON DELETE SET NULL,
+  role             TEXT NOT NULL CHECK (role IN ('system', 'user', 'assistant', 'tool')),
+  content          TEXT NOT NULL,
+  provider         TEXT,
+  model            TEXT,
+  input_tokens     INT NOT NULL DEFAULT 0,
+  output_tokens    INT NOT NULL DEFAULT 0,
+  cost_usd_micros  BIGINT NOT NULL DEFAULT 0,
+  tool_name        TEXT,
+  tool_call_id     TEXT,
+  metadata         JSONB NOT NULL DEFAULT '{}'::jsonb,
+  created_at       TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  deleted_at       TIMESTAMPTZ
+);
+CREATE INDEX idx_wpic_chat_messages_session
+  ON wpic_chat_messages (session_id, created_at ASC);
+CREATE INDEX idx_wpic_chat_messages_owner
+  ON wpic_chat_messages (app, organization_id, created_by, created_at DESC);
+
+CREATE TABLE wpic_chat_usage (
+  app             TEXT NOT NULL DEFAULT 'studio',
+  organization_id UUID NOT NULL,
+  user_id          UUID NOT NULL,
+  date             DATE NOT NULL DEFAULT CURRENT_DATE,
+  input_tokens     INT NOT NULL DEFAULT 0,
+  output_tokens    INT NOT NULL DEFAULT 0,
+  messages         INT NOT NULL DEFAULT 0,
+  cost_usd_micros  BIGINT NOT NULL DEFAULT 0,
+  metadata         JSONB NOT NULL DEFAULT '{}'::jsonb,
+  updated_at       TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (app, organization_id, user_id, date)
+);
+
+CREATE TABLE wpic_chat_memory (
+  app             TEXT NOT NULL DEFAULT 'studio',
+  organization_id UUID NOT NULL,
+  user_id          UUID NOT NULL,
+  key              TEXT NOT NULL,
+  value            TEXT NOT NULL,
+  metadata         JSONB NOT NULL DEFAULT '{}'::jsonb,
+  updated_at       TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (app, organization_id, user_id, key)
+);
+```
+
+If the product has no organizations, remove `organization_id` or make it nullable consistently.
+
+## Attachment table
+
+Use this when uploads, assets, or media must be auditable or reused:
+
+```sql
+CREATE TABLE wpic_chat_attachments (
+  id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  app             TEXT NOT NULL DEFAULT 'studio',
+  organization_id UUID NOT NULL,
+  session_id       UUID REFERENCES wpic_chat_sessions(id) ON DELETE CASCADE,
+  message_id       UUID REFERENCES wpic_chat_messages(id) ON DELETE CASCADE,
+  asset_id         UUID,
+  media_item_id    UUID,
+  created_by       UUID NOT NULL,
+  name             TEXT NOT NULL,
+  mime_type        TEXT,
+  bytes            BIGINT,
+  storage_key      TEXT,
+  extracted_text   TEXT,
+  metadata         JSONB NOT NULL DEFAULT '{}'::jsonb,
+  created_at       TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  deleted_at       TIMESTAMPTZ
+);
+CREATE INDEX idx_wpic_chat_attachments_session
+  ON wpic_chat_attachments (session_id, created_at DESC);
+```
+
+For small text attachments, storing extracted text in message metadata is acceptable. For files, store the file in object storage and keep `storage_key`.
+
+## Tool-event table
+
+Use this when tool calls mutate app data and you need audit/debug trails:
+
+```sql
+CREATE TABLE wpic_chat_tool_events (
+  id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  app             TEXT NOT NULL DEFAULT 'studio',
+  organization_id UUID NOT NULL,
+  session_id       UUID NOT NULL REFERENCES wpic_chat_sessions(id) ON DELETE CASCADE,
+  message_id       UUID REFERENCES wpic_chat_messages(id) ON DELETE SET NULL,
+  provider_run_id  UUID REFERENCES wpic_chat_provider_runs(id) ON DELETE SET NULL,
+  created_by       UUID NOT NULL,
+  tool_name        TEXT NOT NULL,
+  tool_call_id     TEXT,
+  status           TEXT NOT NULL DEFAULT 'succeeded'
+    CHECK (status IN ('succeeded','failed','cancelled','skipped')),
+  arguments        JSONB NOT NULL DEFAULT '{}'::jsonb,
+  result           JSONB NOT NULL DEFAULT '{}'::jsonb,
+  error            TEXT,
+  metadata         JSONB NOT NULL DEFAULT '{}'::jsonb,
+  created_at       TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+CREATE INDEX idx_wpic_chat_tool_events_session
+  ON wpic_chat_tool_events (session_id, created_at ASC);
+```
+
+## Required API endpoints
+
+Minimum DB-backed session API:
+
+```text
+GET    /api/chat/projects
+POST   /api/chat/projects
+PATCH  /api/chat/projects/:id
+DELETE /api/chat/projects/:id
+
+GET    /api/chat/sessions?project_id=...
+POST   /api/chat/sessions
+PATCH  /api/chat/sessions/:id
+DELETE /api/chat/sessions/:id
+GET    /api/chat/sessions/:id/messages
+
+POST   /api/chat
+```
+
+For admin/debug:
+
+```text
+GET    /api/admin/chat/usage
+DELETE /api/admin/chat/conversations/:user_id
+```
+
+## Save flow
+
+Use this flow for a streamed response:
+
+1. Authenticate user and resolve org/workspace.
+2. Validate session belongs to user/org.
+3. Build messages:
+   - system prompt
+   - DB history for session, latest N messages
+   - current user message
+4. Stream provider response to client.
+5. Execute tool calls if needed.
+6. Collect final assistant text and usage.
+7. If not cancelled and assistant text is non-empty, insert user message and assistant message.
+8. Update `wpic_chat_sessions.updated_at`.
+9. Upsert `wpic_chat_usage`.
+10. Return `[DONE]`.
+
+Do not write the final assistant row before the stream completes unless the product explicitly wants partial messages.
+
+## History loading
+
+Perform uses:
+
+```sql
+SELECT role, content
+FROM agent_conversations
+WHERE user_id = $1
+  AND session_id = $2
+  AND role IN ('user', 'assistant')
+  AND content IS NOT NULL
+  AND content != ''
+ORDER BY created_at DESC
+LIMIT $3;
+```
+
+Then it reverses rows before sending to the model. This keeps provider context small and ordered.
+
+Recommended defaults:
+
+- history limit: 20 messages
+- memory max chars: 2000
+- frontend local fallback: last 10-12 messages
+- hard max request messages: 20
+- hard max content length per message: 12000 chars
+
+## Usage upsert
+
+Pattern:
+
+```sql
+INSERT INTO wpic_chat_usage (app, organization_id, user_id, date, input_tokens, output_tokens, messages, cost_usd_micros)
+VALUES ($1, $2, $3, CURRENT_DATE, $4, $5, 1, $6)
+ON CONFLICT (app, organization_id, user_id, date) DO UPDATE SET
+  input_tokens    = wpic_chat_usage.input_tokens + EXCLUDED.input_tokens,
+  output_tokens   = wpic_chat_usage.output_tokens + EXCLUDED.output_tokens,
+  messages        = wpic_chat_usage.messages + 1,
+  cost_usd_micros = wpic_chat_usage.cost_usd_micros + EXCLUDED.cost_usd_micros,
+  updated_at      = NOW();
+```
+
+If the app is not org-scoped, make the primary key `(user_id, date)`.
+
+## Auth and tenancy rules
+
+- Every project/session/message query must be scoped by user and organization/workspace.
+- Never trust `session_id` alone.
+- Validate `project_id` belongs to the same user/org before attaching a session.
+- If admins can inspect conversations, add explicit admin endpoints and do not reuse user endpoints.
+- Decide whether deleted sessions are soft-deleted or hard-deleted. Perform hard-deletes sessions and cascades messages.
+- For shared org workspaces, decide whether sessions are private to the user or shared with team members.
+
+## Title generation
+
+Perform uses the first user message sliced to 60 chars. That is good enough for MVP.
+
+Options:
+
+- first user message, truncated
+- LLM-generated title after first response
+- editable user title
+
+If using LLM-generated titles, do it async and never block the main chat stream.
+
+## Memory
+
+`chat_memory` / `agent_memory` should store durable facts, not transient conversation summaries. Good entries:
+
+- user preferences
+- stable client notes
+- recurring workflow preferences
+
+Bad entries:
+
+- one-off prompt drafts
+- temporary instructions
+- secrets
+- raw uploaded file contents
+
+Memory should have explicit write rules. Do not let arbitrary assistant output become memory without a tool or reviewed pathway.
+
+## Migration checklist
+
+- Add tables and indexes.
+- Backfill `session_id` if migrating existing flat conversations.
+- Add session/project API endpoints.
+- Add auth scoping tests for every endpoint.
+- Add stream save tests:
+  - normal completion inserts two messages
+  - cancelled stream inserts nothing or marks partial according to product decision
+  - provider error does not insert assistant success
+  - usage upsert increments
+  - deleting a session removes or hides messages
+- Add admin usage visibility if needed.
+
+## Drizzle implementation notes
+
+For Drizzle apps, model these as normal `pgTable`s. Prefer UUID primary keys for new Studio-like apps. Use `jsonb` for metadata, not ad-hoc text columns for every future extension.
+
+Store provider-specific details in message metadata when they are not first-class query dimensions:
+
+```json
+{
+  "provider": "deepseek",
+  "model": "deepseek-v4-flash",
+  "finish_reason": "stop",
+  "tools_used": ["navigate"],
+  "request_id": "..."
+}
+```
+
+Use first-class columns for fields that will be filtered, joined, or aggregated frequently: `session_id`, `user_id`, `organization_id`, `created_at`, `role`, `input_tokens`, `output_tokens`.