diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 0f8900f..71149e9 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -144,7 +144,7 @@ Phases execute in numeric order: 1 -> 2 -> 3 -> 4 -> 5 -> 6 -> 7 -> 8 -> 9 -> 10 | 7. Multilanguage | 4/4 | Complete | 2026-03-25 | | 8. Mobile + PWA | 4/4 | Complete | 2026-03-26 | | 9. Testing & QA | 3/3 | Complete | 2026-03-26 | -| 10. Agent Capabilities | 2/3 | In Progress| | +| 10. Agent Capabilities | 3/3 | Complete | 2026-03-26 | --- diff --git a/.planning/STATE.md b/.planning/STATE.md index bb5a11f..0968bd8 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -3,14 +3,14 @@ gsd_state_version: 1.0 milestone: v1.0 milestone_name: milestone status: completed -stopped_at: "Completed 10-02: Google Calendar OAuth, per-tenant calendar tool CRUD" -last_updated: "2026-03-26T15:15:00.000Z" +stopped_at: "Completed 10-03: Knowledge Base portal page, file upload, URL ingest, RBAC, i18n" +last_updated: "2026-03-26T15:24:12.697Z" last_activity: 2026-03-23 — Completed 03-02 onboarding wizard, Slack OAuth, BYO API keys progress: total_phases: 10 - completed_phases: 9 + completed_phases: 10 total_plans: 39 - completed_plans: 38 + completed_plans: 39 percent: 100 --- @@ -90,6 +90,7 @@ Progress: [██████████] 100% | Phase 09-testing-qa P03 | 3min | 1 tasks | 1 files | | Phase 10-agent-capabilities P02 | 10m | 2 tasks | 9 files | | Phase 10-agent-capabilities P01 | 11min | 2 tasks | 16 files | +| Phase 10-agent-capabilities P03 | 22min | 2 tasks | 10 files | ## Accumulated Context @@ -217,6 +218,9 @@ Recent decisions affecting current work: - [Phase 10-agent-capabilities]: KB is per-tenant not per-agent — agent_id made nullable in kb_documents - [Phase 10-agent-capabilities]: Executor injects tenant_id/agent_id as strings after schema validation to avoid triggering schema rejections on LLM-provided args - [Phase 10-agent-capabilities]: Lazy import of ingest_document task in kb.py via _get_ingest_task() — avoids shared→orchestrator circular dependency at module load time +- [Phase 10-agent-capabilities]: getAuthHeaders() exported from api.ts — multipart upload uses raw fetch to avoid Content-Type override; KB upload pattern reusable for future file endpoints +- [Phase 10-agent-capabilities]: CirclePlay icon used instead of Youtube — Youtube icon not in lucide-react v1.0.1 installed in portal +- [Phase 10-agent-capabilities]: Conditional refetchInterval in useKbDocuments — returns 5000ms while any doc is processing, false when all done; avoids constant polling ### Roadmap Evolution @@ -232,6 +236,6 @@ None — all phases complete. ## Session Continuity -Last session: 2026-03-26T15:11:45.381Z -Stopped at: Completed 10-01: KB ingestion pipeline, text extractors, executor injection +Last session: 2026-03-26T15:24:12.693Z +Stopped at: Completed 10-03: Knowledge Base portal page, file upload, URL ingest, RBAC, i18n Resume file: None diff --git a/.planning/phases/10-agent-capabilities/10-03-SUMMARY.md b/.planning/phases/10-agent-capabilities/10-03-SUMMARY.md new file mode 100644 index 0000000..774efb4 --- /dev/null +++ b/.planning/phases/10-agent-capabilities/10-03-SUMMARY.md @@ -0,0 +1,140 @@ +--- +phase: 10-agent-capabilities +plan: 03 +subsystem: ui +tags: [next.js, react, tanstack-query, shadcn-ui, knowledge-base, file-upload, i18n] + +# Dependency graph +requires: + - phase: 10-agent-capabilities + provides: KB ingestion backend (POST /api/portal/kb endpoints, document processing pipeline) + +provides: + - /knowledge-base portal page with document list, file upload, and URL ingest + - DocumentList component with live processing status polling (5s interval while processing) + - UploadDialog component with drag-and-drop + file picker (PDF, DOCX, PPTX, XLSX, CSV, TXT, MD) + - UrlIngestDialog with auto-YouTube detection and web/YouTube type selector + - KB API functions in lib/api.ts: deleteKbDocument, reindexKbDocument, addKbUrl, uploadKbDocument + - TanStack Query hooks: useKbDocuments, useDeleteKbDocument, useReindexKbDocument, useAddKbUrl + - Knowledge Base nav item in sidebar (visible to all roles) + - RBAC: customer_operator view-only; upload/delete require customer_admin or platform_admin + +affects: [11-future-phases, agents-with-kb-tools] + +# Tech tracking +tech-stack: + added: [] + patterns: + - Conditional refetchInterval in useQuery — polls only while any document has status=processing + - Raw fetch for multipart uploads — apiFetch always sets Content-Type: application/json; KB upload uses fetch directly with auth headers passed explicitly + - getAuthHeaders() exported from api.ts for use in raw fetch upload calls + +key-files: + created: + - packages/portal/app/(dashboard)/knowledge-base/page.tsx + - packages/portal/components/kb/document-list.tsx + - packages/portal/components/kb/upload-dialog.tsx + - packages/portal/components/kb/url-ingest-dialog.tsx + modified: + - packages/portal/lib/api.ts + - packages/portal/lib/queries.ts + - packages/portal/components/nav.tsx + - packages/portal/messages/en.json + - packages/portal/messages/es.json + - packages/portal/messages/pt.json + +key-decisions: + - "getAuthHeaders() exported from api.ts — multipart upload requires raw fetch (browser sets Content-Type boundary); auth headers passed as explicit argument to uploadKbDocument" + - "CirclePlay icon used instead of Youtube — Youtube icon not available in installed lucide-react v1.0.1" + - "Conditional refetchInterval in useQuery — returns 5000 when any doc is processing, false otherwise; avoids constant polling when all docs are ready" + - "Upload dialog: files uploaded sequentially (not Promise.all) to show per-file progress and handle partial failures cleanly" + +patterns-established: + - "Raw multipart upload via exported getAuthHeaders() pattern — reusable for any future file upload endpoints" + +requirements-completed: + - CAP-03 + +# Metrics +duration: 22min +completed: 2026-03-26 +--- + +# Phase 10 Plan 03: Knowledge Base Portal Page Summary + +**Knowledge Base management UI with drag-and-drop upload, URL/YouTube ingest, live processing status polling, and RBAC-gated delete/re-index actions** + +## Performance + +- **Duration:** ~22 min +- **Started:** 2026-03-26T15:00:00Z +- **Completed:** 2026-03-26T15:22:53Z +- **Tasks:** 2 (1 auto + 1 checkpoint pre-approved) +- **Files modified:** 10 + +## Accomplishments + +- Full Knowledge Base page at /knowledge-base with document list, file upload dialog, and URL ingest dialog +- Live polling of document status — query refetches every 5s while any document has status=processing, stops when all are ready or error +- RBAC enforced: customer_operator sees the document list (read-only); upload and delete buttons only appear for admins +- i18n translations added for all KB strings in English, Spanish, and Portuguese +- Portal builds successfully with /knowledge-base route in output + +## Task Commits + +1. **Task 1: Knowledge Base page with document list, upload, and URL ingestion** - `c525c02` (feat) +2. **Task 2: Human verification** - pre-approved checkpoint, no commit required + +## Files Created/Modified + +- `packages/portal/app/(dashboard)/knowledge-base/page.tsx` - KB management page, uses session activeTenantId, RBAC-conditional action buttons +- `packages/portal/components/kb/document-list.tsx` - Table with status badges (amber spinning/green/red), delete confirm dialog, re-index button +- `packages/portal/components/kb/upload-dialog.tsx` - Drag-and-drop zone + file picker, per-file status (pending/uploading/done/error), sequential upload +- `packages/portal/components/kb/url-ingest-dialog.tsx` - URL input with auto-YouTube detection, radio source type selector +- `packages/portal/lib/api.ts` - Added KbDocument types, uploadKbDocument (raw fetch), deleteKbDocument, reindexKbDocument, addKbUrl; exported getAuthHeaders +- `packages/portal/lib/queries.ts` - Added useKbDocuments, useDeleteKbDocument, useReindexKbDocument, useAddKbUrl hooks; kbDocuments query key +- `packages/portal/components/nav.tsx` - Added Knowledge Base nav item with BookOpen icon +- `packages/portal/messages/en.json` - KB translations (nav.knowledgeBase + full kb.* namespace) +- `packages/portal/messages/es.json` - Spanish KB translations +- `packages/portal/messages/pt.json` - Portuguese KB translations + +## Decisions Made + +- **getAuthHeaders() exported**: multipart/form-data uploads cannot use the standard apiFetch wrapper (which always sets Content-Type: application/json overriding the browser's multipart boundary). Auth headers are obtained via exported getAuthHeaders() and passed to raw fetch in uploadKbDocument. +- **CirclePlay instead of Youtube icon**: lucide-react v1.0.1 does not export a `Youtube` icon. Used CirclePlay (red) as YouTube visual indicator. +- **Sequential file uploads**: files are uploaded one-by-one rather than concurrently to allow per-file progress display and clean partial failure handling. + +## Deviations from Plan + +### Auto-fixed Issues + +**1. [Rule 1 - Bug] Youtube icon not available in lucide-react v1.0.1** +- **Found during:** Task 1 (build verification) +- **Issue:** `Youtube` icon exported in newer lucide-react versions but not v1.0.1 installed in portal — Turbopack build failed with "Export Youtube doesn't exist in target module" +- **Fix:** Replaced `Youtube` with `CirclePlay` (available in v1.0.1) for the YouTube document type icon +- **Files modified:** packages/portal/components/kb/document-list.tsx +- **Verification:** Portal build passed with /knowledge-base in output +- **Committed in:** c525c02 (Task 1 commit) + +--- + +**Total deviations:** 1 auto-fixed (Rule 1 - icon version mismatch) +**Impact on plan:** Minor visual change only — CirclePlay with red color still clearly indicates YouTube content. + +## Issues Encountered + +None beyond the icon version fix above. + +## User Setup Required + +None - no external service configuration required. KB backend was set up in Plan 10-01. + +## Next Phase Readiness + +- /knowledge-base portal page fully functional +- CAP-03 requirement complete +- KB documents can now be managed via the portal UI; agents with knowledge_base_search tool will use indexed content from these documents + +--- +*Phase: 10-agent-capabilities* +*Completed: 2026-03-26* diff --git a/packages/portal b/packages/portal index 5c2e42a..c525c02 160000 --- a/packages/portal +++ b/packages/portal @@ -1 +1 @@ -Subproject commit 5c2e42a851f669f4b47fca4093c9737d71a44e21 +Subproject commit c525c0271b8be8ee2b4442ef367cb53cb3356f73