From 63a256a187ebbaa1e24c9a6f5e9fe82a4748c85b Mon Sep 17 00:00:00 2001 From: moises-cisneros Date: Mon, 19 Oct 2026 23:52:14 -0400 Subject: [PATCH 1/5] feat(feedback): add d1 schema and repository for feedback inbox --- migrations/0006_feedback_inbox.sql | 16 ++++ src/adapters/d1/feedback-repo.ts | 107 +++++++++++++++++++++++++ src/domain/entities.ts | 16 ++++ src/domain/ports.ts | 22 +++++ test/adapters/d1/feedback-repo.test.ts | 99 +++++++++++++++++++++++ test/adapters/migrations.test.ts | 44 ++++++++++ 6 files changed, 304 insertions(+) create mode 100644 migrations/0006_feedback_inbox.sql create mode 100644 src/adapters/d1/feedback-repo.ts create mode 100644 test/adapters/d1/feedback-repo.test.ts diff --git a/migrations/0006_feedback_inbox.sql b/migrations/0006_feedback_inbox.sql new file mode 100644 index 0000000..e8b6de1 --- /dev/null +++ b/migrations/0006_feedback_inbox.sql @@ -0,0 +1,16 @@ +-- Feedback & Bug Inbox: stores raw feedback and bug observations per team and optional repository hint. + +CREATE TABLE feedback_notes ( + id TEXT PRIMARY KEY, + team_id TEXT NOT NULL REFERENCES teams(id), + author_membership_id TEXT NOT NULL REFERENCES memberships(id), + repo_hint TEXT, + raw_text TEXT NOT NULL, + source_type TEXT NOT NULL DEFAULT 'text' CHECK (source_type IN ('text', 'voice')), + status TEXT NOT NULL DEFAULT 'inbox' CHECK (status IN ('inbox', 'triaged', 'archived')), + created_at INTEGER NOT NULL, + updated_at INTEGER NOT NULL +); + +CREATE INDEX idx_feedback_notes_team_status ON feedback_notes(team_id, status); +CREATE INDEX idx_feedback_notes_team_repo ON feedback_notes(team_id, repo_hint); diff --git a/src/adapters/d1/feedback-repo.ts b/src/adapters/d1/feedback-repo.ts new file mode 100644 index 0000000..c35dc1a --- /dev/null +++ b/src/adapters/d1/feedback-repo.ts @@ -0,0 +1,107 @@ +import type { FeedbackNote, FeedbackSource, FeedbackStatus } from "../../domain/entities"; +import { asMembershipId, asTeamId } from "../../domain/ids"; +import type { TeamId } from "../../domain/ids"; +import type { FeedbackFilter, FeedbackRepo } from "../../domain/ports"; + +interface FeedbackRow { + id: string; + team_id: string; + author_membership_id: string; + repo_hint: string | null; + raw_text: string; + source_type: string; + status: string; + created_at: number; + updated_at: number; +} + +function rowToNote(row: FeedbackRow): FeedbackNote { + return { + id: row.id, + teamId: asTeamId(row.team_id), + authorMembershipId: asMembershipId(row.author_membership_id), + repoHint: row.repo_hint, + rawText: row.raw_text, + sourceType: row.source_type as FeedbackSource, + status: row.status as FeedbackStatus, + createdAt: row.created_at, + updatedAt: row.updated_at, + }; +} + +export function createD1FeedbackRepo(db: D1Database): FeedbackRepo { + return { + async save(teamId: TeamId, note: FeedbackNote): Promise { + await db + .prepare( + `INSERT INTO feedback_notes ( + id, team_id, author_membership_id, repo_hint, raw_text, source_type, status, created_at, updated_at + ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?) + ON CONFLICT(id) DO UPDATE SET + repo_hint = excluded.repo_hint, + raw_text = excluded.raw_text, + status = excluded.status, + updated_at = excluded.updated_at`, + ) + .bind( + note.id, + teamId, + note.authorMembershipId, + note.repoHint, + note.rawText, + note.sourceType, + note.status, + note.createdAt, + note.updatedAt, + ) + .run(); + }, + + async list(teamId: TeamId, filter: FeedbackFilter = {}): Promise { + let query = "SELECT * FROM feedback_notes WHERE team_id = ?"; + const params: unknown[] = [teamId]; + + if (filter.status) { + query += " AND status = ?"; + params.push(filter.status); + } + + if (filter.repoHint) { + query += " AND repo_hint = ?"; + params.push(filter.repoHint); + } + + if (filter.since !== undefined) { + query += " AND created_at >= ?"; + params.push(filter.since); + } + + query += " ORDER BY created_at ASC"; + + if (filter.limit !== undefined && filter.limit > 0) { + query += " LIMIT ?"; + params.push(filter.limit); + } + + const rows = await db.prepare(query).bind(...params).all(); + return (rows.results || []).map(rowToNote); + }, + + async updateStatus( + teamId: TeamId, + noteIds: string[], + status: FeedbackStatus, + ): Promise { + if (noteIds.length === 0) return; + const now = Date.now(); + const stmts = noteIds.map((id) => + db + .prepare( + "UPDATE feedback_notes SET status = ?, updated_at = ? WHERE team_id = ? AND id = ?", + ) + .bind(status, now, teamId, id), + ); + await db.batch(stmts); + }, + }; +} diff --git a/src/domain/entities.ts b/src/domain/entities.ts index 7687dc1..35a0303 100644 --- a/src/domain/entities.ts +++ b/src/domain/entities.ts @@ -185,3 +185,19 @@ export type ClaimResult = // value; `src/index.ts`'s `queue()` handler maps this to `msg.ack()` or // `msg.retry()` and never throws. export type JobOutcome = { kind: "ack" } | { kind: "retry"; delaySeconds: number }; + +export type FeedbackStatus = "inbox" | "triaged" | "archived"; +export type FeedbackSource = "text" | "voice"; + +export interface FeedbackNote { + id: string; + teamId: TeamId; + authorMembershipId: MembershipId; + repoHint: string | null; + rawText: string; + sourceType: FeedbackSource; + status: FeedbackStatus; + createdAt: number; + updatedAt: number; +} + diff --git a/src/domain/ports.ts b/src/domain/ports.ts index 9c80cca..6702ba2 100644 --- a/src/domain/ports.ts +++ b/src/domain/ports.ts @@ -10,6 +10,8 @@ import type { DmSelection, RepoTopicLink, Team, + FeedbackNote, + FeedbackStatus, } from "./entities"; import type { RepoFullName } from "./github"; import type { MemberId, MembershipId, TeamId } from "./ids"; @@ -430,3 +432,23 @@ export interface ChatPublisher { // Removes the inline keyboard from a message (throws PublishFailedError). clearButtons(chatId: number, messageId: number): Promise; } + +// --- Feedback Inbox ports --- + +export interface FeedbackFilter { + repoHint?: string; + status?: FeedbackStatus; + since?: number; + limit?: number; +} + +export interface FeedbackRepo { + save(teamId: TeamId, note: FeedbackNote): Promise; + list(teamId: TeamId, filter?: FeedbackFilter): Promise; + updateStatus(teamId: TeamId, noteIds: string[], status: FeedbackStatus): Promise; +} + +export interface SpeechToText { + transcribe(audioBuffer: ArrayBuffer, signal?: AbortSignal): Promise; +} + diff --git a/test/adapters/d1/feedback-repo.test.ts b/test/adapters/d1/feedback-repo.test.ts new file mode 100644 index 0000000..e39398c --- /dev/null +++ b/test/adapters/d1/feedback-repo.test.ts @@ -0,0 +1,99 @@ +import { env } from "cloudflare:test"; +import { describe, expect, it } from "vitest"; +import { createD1FeedbackRepo } from "../../../src/adapters/d1/feedback-repo"; +import { asMembershipId, asTeamId } from "../../../src/domain/ids"; + +async function seedTeamAndMember(teamId: string, memberId: string) { + await env.DB.batch([ + env.DB.prepare( + "INSERT OR IGNORE INTO teams (id, telegram_chat_id, created_at) VALUES (?, ?, ?)", + ).bind(teamId, Math.floor(Math.random() * 1000000), 0), + env.DB.prepare( + "INSERT OR IGNORE INTO members (id, telegram_user_id, created_at) VALUES (?, ?, ?)", + ).bind(memberId, Math.floor(Math.random() * 1000000), 0), + env.DB.prepare( + "INSERT OR IGNORE INTO memberships (id, team_id, member_id, role, joined_at) VALUES (?, ?, ?, 'member', ?)", + ).bind(`mship-${memberId}`, teamId, memberId, 0), + ]); + return asMembershipId(`mship-${memberId}`); +} + +describe("createD1FeedbackRepo", () => { + it("saves and lists feedback notes scoped to team", async () => { + const teamId = asTeamId("team-fb-1"); + const authorId = await seedTeamAndMember("team-fb-1", "user-fb-1"); + const repo = createD1FeedbackRepo(env.DB); + + const note1 = { + id: "note-1", + teamId, + authorMembershipId: authorId, + repoHint: "puls3", + rawText: "Demo bug in Freighter wallet connection", + sourceType: "text" as const, + status: "inbox" as const, + createdAt: 1000, + updatedAt: 1000, + }; + + const note2 = { + id: "note-2", + teamId, + authorMembershipId: authorId, + repoHint: "hack_bot", + rawText: "Voice note transcription worked well", + sourceType: "voice" as const, + status: "inbox" as const, + createdAt: 2000, + updatedAt: 2000, + }; + + await repo.save(teamId, note1); + await repo.save(teamId, note2); + + const allNotes = await repo.list(teamId); + expect(allNotes).toEqual([note1, note2]); + + const puls3Notes = await repo.list(teamId, { repoHint: "puls3" }); + expect(puls3Notes).toEqual([note1]); + }); + + it("updates feedback note status across multiple IDs", async () => { + const teamId = asTeamId("team-fb-2"); + const authorId = await seedTeamAndMember("team-fb-2", "user-fb-2"); + const repo = createD1FeedbackRepo(env.DB); + + await repo.save(teamId, { + id: "note-update-1", + teamId, + authorMembershipId: authorId, + repoHint: null, + rawText: "Feedback item 1", + sourceType: "text", + status: "inbox", + createdAt: 100, + updatedAt: 100, + }); + + await repo.save(teamId, { + id: "note-update-2", + teamId, + authorMembershipId: authorId, + repoHint: null, + rawText: "Feedback item 2", + sourceType: "text", + status: "inbox", + createdAt: 200, + updatedAt: 200, + }); + + await repo.updateStatus(teamId, ["note-update-1", "note-update-2"], "triaged"); + + const triaged = await repo.list(teamId, { status: "triaged" }); + expect(triaged).toHaveLength(2); + expect(triaged.map((n) => n.id)).toEqual(["note-update-1", "note-update-2"]); + + const pending = await repo.list(teamId, { status: "inbox" }); + expect(pending).toHaveLength(0); + }); +}); diff --git a/test/adapters/migrations.test.ts b/test/adapters/migrations.test.ts index f1ba98a..6bc618d 100644 --- a/test/adapters/migrations.test.ts +++ b/test/adapters/migrations.test.ts @@ -15,6 +15,8 @@ describe("migrations/0001_init.sql", () => { expect(names).toEqual([ "audit_log", "dm_selections", + // feedback_notes: migrations/0006_feedback_inbox.sql + "feedback_notes", // github_org_claims and repo_topic_links: migrations/0002_github_alerts.sql // (PR2 covers their own FK/UNIQUE/CHECK migration tests). "github_org_claims", @@ -571,4 +573,46 @@ describe("migrations/0005_natural_language_text.sql", () => { .run(), ).rejects.toThrow(/UNIQUE/i); }); + + it("creates feedback_notes and enforces status check and fk", async () => { + await seedTeamAndMembership("team-fb-mig", "mem-fb-mig", 9999); + await env.DB.prepare( + `INSERT INTO feedback_notes + (id, team_id, author_membership_id, repo_hint, raw_text, source_type, status, created_at, updated_at) + VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`, + ) + .bind( + "note-mig-1", + "team-fb-mig", + "mem-fb-mig", + "org/repo", + "Test note", + "text", + "inbox", + 1000, + 1000, + ) + .run(); + + // Invalid status CHECK constraint + await expect( + env.DB.prepare( + `INSERT INTO feedback_notes + (id, team_id, author_membership_id, repo_hint, raw_text, source_type, status, created_at, updated_at) + VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`, + ) + .bind( + "note-mig-2", + "team-fb-mig", + "mem-fb-mig", + "org/repo", + "Test note", + "text", + "invalid_status", + 1000, + 1000, + ) + .run(), + ).rejects.toThrow(/CHECK/i); + }); }); From 1b92ba45b110abba798a4d83b42c9ed7a5a8b8d7 Mon Sep 17 00:00:00 2001 From: moises-cisneros Date: Mon, 19 Oct 2026 23:52:35 -0400 Subject: [PATCH 2/5] feat(feedback): add domain use cases and copy for feedback notes --- src/domain/copy.ts | 39 ++++++++ src/domain/usecases/archive-feedback.ts | 34 +++++++ src/domain/usecases/list-feedback.ts | 39 ++++++++ src/domain/usecases/record-feedback.ts | 59 ++++++++++++ src/domain/usecases/synthesize-feedback.ts | 86 +++++++++++++++++ test/domain/usecases/archive-feedback.test.ts | 47 +++++++++ test/domain/usecases/list-feedback.test.ts | 59 ++++++++++++ test/domain/usecases/record-feedback.test.ts | 96 +++++++++++++++++++ .../usecases/synthesize-feedback.test.ts | 88 +++++++++++++++++ 9 files changed, 547 insertions(+) create mode 100644 src/domain/usecases/archive-feedback.ts create mode 100644 src/domain/usecases/list-feedback.ts create mode 100644 src/domain/usecases/record-feedback.ts create mode 100644 src/domain/usecases/synthesize-feedback.ts create mode 100644 test/domain/usecases/archive-feedback.test.ts create mode 100644 test/domain/usecases/list-feedback.test.ts create mode 100644 test/domain/usecases/record-feedback.test.ts create mode 100644 test/domain/usecases/synthesize-feedback.test.ts diff --git a/src/domain/copy.ts b/src/domain/copy.ts index 9299afe..87faeb9 100644 --- a/src/domain/copy.ts +++ b/src/domain/copy.ts @@ -107,3 +107,42 @@ export const githubCopy = { reviewerLabel: "Revisor:", byLabel: "Por:", }; + +export function formatShortDate(timestampMs: number): string { + const d = new Date(timestampMs); + const day = String(d.getUTCDate()).padStart(2, "0"); + const month = String(d.getUTCMonth() + 1).padStart(2, "0"); + return `${day}/${month}`; +} + +export function formatFeedbackDateSpan(startDate: number | null, endDate: number | null): string { + if (startDate === null || endDate === null) return ""; + const startStr = formatShortDate(startDate); + const endStr = formatShortDate(endDate); + if (startStr === endStr) { + return `del ${startStr}`; + } + return `entre el ${startStr} y el ${endStr}`; +} + +export const feedbackCopy = { + recorded: (repo?: string | null): string => + repo ? `✅ Nota guardada en el buzón para ${repo}.` : "✅ Nota guardada en el buzón.", + empty: "No hay observaciones pendientes en el buzón.", + noSynthesis: "No hay observaciones pendientes para resumir.", + archived: (count: number): string => + count === 1 ? "1 observación archivada." : `${count} observaciones archivadas.`, + voiceFailed: + "No pude entender el mensaje de voz. Por favor intenta de nuevo o escribe tu mensaje.", + summaryHeader: (count: number, dateSpan: string, repo?: string | null): string => { + const countPart = count === 1 ? "1 observación" : `${count} observaciones`; + const repoPart = repo ? ` para ${repo}` : ""; + const spanPart = dateSpan ? ` ${dateSpan}` : ""; + return `📋 Resumen de ${countPart}${repoPart}${spanPart}:`; + }, + noteLine: (id: string, dateStr: string, text: string, repo?: string | null, isVoice = false): string => { + const prefix = isVoice ? "🎙️ " : ""; + const repoPart = repo ? `[${repo}] ` : ""; + return `• (${id.slice(0, 6)}) ${prefix}${repoPart}${dateStr}: ${text}`; + }, +}; diff --git a/src/domain/usecases/archive-feedback.ts b/src/domain/usecases/archive-feedback.ts new file mode 100644 index 0000000..69e31cb --- /dev/null +++ b/src/domain/usecases/archive-feedback.ts @@ -0,0 +1,34 @@ +import type { FeedbackStatus } from "../entities"; +import type { TeamId } from "../ids"; +import type { FeedbackRepo, Logger } from "../ports"; + +export interface ArchiveFeedbackInput { + teamId: TeamId; + noteIds: string[]; + targetStatus?: FeedbackStatus; +} + +export interface ArchiveFeedbackDeps { + feedbackRepo: FeedbackRepo; + logger: Logger; +} + +export async function archiveFeedback( + input: ArchiveFeedbackInput, + deps: ArchiveFeedbackDeps, +): Promise<{ updatedCount: number }> { + if (input.noteIds.length === 0) { + return { updatedCount: 0 }; + } + + const status = input.targetStatus ?? "triaged"; + await deps.feedbackRepo.updateStatus(input.teamId, input.noteIds, status); + + deps.logger.log({ + event: "feedback-archived", + teamId: input.teamId, + outcome: "ok", + }); + + return { updatedCount: input.noteIds.length }; +} diff --git a/src/domain/usecases/list-feedback.ts b/src/domain/usecases/list-feedback.ts new file mode 100644 index 0000000..b6d41da --- /dev/null +++ b/src/domain/usecases/list-feedback.ts @@ -0,0 +1,39 @@ +import type { FeedbackNote, FeedbackStatus } from "../entities"; +import type { TeamId } from "../ids"; +import type { FeedbackRepo, RepoTopicLinkRepo } from "../ports"; + +export interface ListFeedbackInput { + teamId: TeamId; + threadId?: number | null; + repoHint?: string | null; + status?: FeedbackStatus; + since?: number; + limit?: number; +} + +export interface ListFeedbackDeps { + feedbackRepo: FeedbackRepo; + repoTopicLinkRepo: RepoTopicLinkRepo; +} + +export async function listFeedback( + input: ListFeedbackInput, + deps: ListFeedbackDeps, +): Promise { + let resolvedRepo = input.repoHint?.trim() || undefined; + + if (!resolvedRepo && input.threadId !== undefined && input.threadId !== null) { + const links = await deps.repoTopicLinkRepo.list(input.teamId); + const matched = links.find((l) => l.threadId === input.threadId); + if (matched) { + resolvedRepo = matched.repoFullName; + } + } + + return await deps.feedbackRepo.list(input.teamId, { + repoHint: resolvedRepo, + status: input.status ?? "inbox", + since: input.since, + limit: input.limit, + }); +} diff --git a/src/domain/usecases/record-feedback.ts b/src/domain/usecases/record-feedback.ts new file mode 100644 index 0000000..e1fc9c4 --- /dev/null +++ b/src/domain/usecases/record-feedback.ts @@ -0,0 +1,59 @@ +import type { FeedbackNote, FeedbackSource } from "../entities"; +import type { MembershipId, TeamId } from "../ids"; +import type { Clock, FeedbackRepo, IdGen, Logger, RepoTopicLinkRepo } from "../ports"; + +export interface RecordFeedbackInput { + teamId: TeamId; + authorMembershipId: MembershipId; + threadId: number | null; + rawText: string; + repoHint?: string | null; + sourceType?: FeedbackSource; +} + +export interface RecordFeedbackDeps { + feedbackRepo: FeedbackRepo; + repoTopicLinkRepo: RepoTopicLinkRepo; + idGen: IdGen; + clock: Clock; + logger: Logger; +} + +export async function recordFeedback( + input: RecordFeedbackInput, + deps: RecordFeedbackDeps, +): Promise { + let resolvedRepo = input.repoHint?.trim() || null; + + if (!resolvedRepo && input.threadId !== null) { + const links = await deps.repoTopicLinkRepo.list(input.teamId); + const matched = links.find((l) => l.threadId === input.threadId); + if (matched) { + resolvedRepo = matched.repoFullName; + } + } + + const now = deps.clock.now(); + const note: FeedbackNote = { + id: deps.idGen.newId(), + teamId: input.teamId, + authorMembershipId: input.authorMembershipId, + repoHint: resolvedRepo, + rawText: input.rawText.trim(), + sourceType: input.sourceType ?? "text", + status: "inbox", + createdAt: now, + updatedAt: now, + }; + + await deps.feedbackRepo.save(input.teamId, note); + + deps.logger.log({ + event: "feedback-recorded", + teamId: input.teamId, + membershipId: input.authorMembershipId, + outcome: "ok", + }); + + return note; +} diff --git a/src/domain/usecases/synthesize-feedback.ts b/src/domain/usecases/synthesize-feedback.ts new file mode 100644 index 0000000..eb94d93 --- /dev/null +++ b/src/domain/usecases/synthesize-feedback.ts @@ -0,0 +1,86 @@ +import type { FeedbackNote } from "../entities"; +import type { TeamId } from "../ids"; +import type { FeedbackRepo, Logger, RepoTopicLinkRepo } from "../ports"; + +export interface FeedbackSynthesizer { + summarize(notes: FeedbackNote[], signal?: AbortSignal): Promise; +} + +export interface SynthesizeFeedbackInput { + teamId: TeamId; + threadId?: number | null; + repoHint?: string | null; + since?: number; + limit?: number; + signal?: AbortSignal; +} + +export interface SynthesizedFeedbackSummary { + repoHint: string | null; + totalNotes: number; + startDate: number | null; + endDate: number | null; + summaryText: string; + noteIds: string[]; +} + +export interface SynthesizeFeedbackDeps { + feedbackRepo: FeedbackRepo; + repoTopicLinkRepo: RepoTopicLinkRepo; + synthesizer: FeedbackSynthesizer; + logger: Logger; +} + +export async function synthesizeFeedback( + input: SynthesizeFeedbackInput, + deps: SynthesizeFeedbackDeps, +): Promise { + let resolvedRepo = input.repoHint?.trim() || null; + + if (!resolvedRepo && input.threadId !== undefined && input.threadId !== null) { + const links = await deps.repoTopicLinkRepo.list(input.teamId); + const matched = links.find((l) => l.threadId === input.threadId); + if (matched) { + resolvedRepo = matched.repoFullName; + } + } + + const notes = await deps.feedbackRepo.list(input.teamId, { + repoHint: resolvedRepo ?? undefined, + status: "inbox", + since: input.since, + limit: input.limit ?? 30, + }); + + if (notes.length === 0) { + return { + repoHint: resolvedRepo, + totalNotes: 0, + startDate: null, + endDate: null, + summaryText: "", + noteIds: [], + }; + } + + const sortedNotes = [...notes].sort((a, b) => a.createdAt - b.createdAt); + const startDate = sortedNotes[0]?.createdAt ?? null; + const endDate = sortedNotes[sortedNotes.length - 1]?.createdAt ?? null; + + const summaryText = await deps.synthesizer.summarize(sortedNotes, input.signal); + + deps.logger.log({ + event: "feedback-synthesized", + teamId: input.teamId, + outcome: "ok", + }); + + return { + repoHint: resolvedRepo, + totalNotes: notes.length, + startDate, + endDate, + summaryText, + noteIds: sortedNotes.map((n) => n.id), + }; +} diff --git a/test/domain/usecases/archive-feedback.test.ts b/test/domain/usecases/archive-feedback.test.ts new file mode 100644 index 0000000..b17815e --- /dev/null +++ b/test/domain/usecases/archive-feedback.test.ts @@ -0,0 +1,47 @@ +import { describe, expect, it, vi } from "vitest"; +import { asTeamId } from "../../../src/domain/ids"; +import { archiveFeedback } from "../../../src/domain/usecases/archive-feedback"; + +describe("archiveFeedback", () => { + it("updates status of given noteIds to triaged by default", async () => { + const updateStatus = vi.fn().mockResolvedValue(undefined); + const feedbackRepo = { + save: vi.fn(), + list: vi.fn(), + updateStatus, + }; + const logger = { log: vi.fn() }; + + const result = await archiveFeedback( + { + teamId: asTeamId("team-1"), + noteIds: ["note-1", "note-2"], + }, + { feedbackRepo, logger }, + ); + + expect(result.updatedCount).toBe(2); + expect(updateStatus).toHaveBeenCalledWith( + asTeamId("team-1"), + ["note-1", "note-2"], + "triaged", + ); + }); + + it("handles empty noteIds list safely", async () => { + const updateStatus = vi.fn().mockResolvedValue(undefined); + const feedbackRepo = { save: vi.fn(), list: vi.fn(), updateStatus }; + const logger = { log: vi.fn() }; + + const result = await archiveFeedback( + { + teamId: asTeamId("team-1"), + noteIds: [], + }, + { feedbackRepo, logger }, + ); + + expect(result.updatedCount).toBe(0); + expect(updateStatus).not.toHaveBeenCalled(); + }); +}); diff --git a/test/domain/usecases/list-feedback.test.ts b/test/domain/usecases/list-feedback.test.ts new file mode 100644 index 0000000..f4d3a9a --- /dev/null +++ b/test/domain/usecases/list-feedback.test.ts @@ -0,0 +1,59 @@ +import { describe, expect, it, vi } from "vitest"; +import { asTeamId } from "../../../src/domain/ids"; +import type { RepoFullName } from "../../../src/domain/github"; +import { listFeedback } from "../../../src/domain/usecases/list-feedback"; + +describe("listFeedback", () => { + it("lists feedback with default inbox status", async () => { + const list = vi.fn().mockResolvedValue([]); + const feedbackRepo = { save: vi.fn(), list, updateStatus: vi.fn() }; + const repoTopicLinkRepo = { + get: vi.fn(), + upsert: vi.fn(), + remove: vi.fn(), + list: vi.fn().mockResolvedValue([]), + }; + + await listFeedback( + { teamId: asTeamId("team-1") }, + { feedbackRepo, repoTopicLinkRepo }, + ); + + expect(list).toHaveBeenCalledWith(asTeamId("team-1"), { + repoHint: undefined, + status: "inbox", + since: undefined, + limit: undefined, + }); + }); + + it("resolves repo hint from threadId when in topic", async () => { + const list = vi.fn().mockResolvedValue([]); + const feedbackRepo = { save: vi.fn(), list, updateStatus: vi.fn() }; + const repoTopicLinkRepo = { + get: vi.fn(), + upsert: vi.fn(), + remove: vi.fn(), + list: vi.fn().mockResolvedValue([ + { + teamId: asTeamId("team-1"), + repoFullName: "org/puls3" as RepoFullName, + threadId: 42, + createdAt: 0, + }, + ]), + }; + + await listFeedback( + { teamId: asTeamId("team-1"), threadId: 42 }, + { feedbackRepo, repoTopicLinkRepo }, + ); + + expect(list).toHaveBeenCalledWith(asTeamId("team-1"), { + repoHint: "org/puls3", + status: "inbox", + since: undefined, + limit: undefined, + }); + }); +}); diff --git a/test/domain/usecases/record-feedback.test.ts b/test/domain/usecases/record-feedback.test.ts new file mode 100644 index 0000000..b33a452 --- /dev/null +++ b/test/domain/usecases/record-feedback.test.ts @@ -0,0 +1,96 @@ +import { describe, expect, it, vi } from "vitest"; +import { asMembershipId, asTeamId } from "../../../src/domain/ids"; +import type { RepoFullName } from "../../../src/domain/github"; +import { recordFeedback } from "../../../src/domain/usecases/record-feedback"; + +describe("recordFeedback", () => { + it("records a feedback note with explicit repo hint", async () => { + const save = vi.fn().mockResolvedValue(undefined); + const feedbackRepo = { + save, + list: vi.fn(), + updateStatus: vi.fn(), + }; + const repoTopicLinkRepo = { + get: vi.fn(), + upsert: vi.fn(), + remove: vi.fn(), + list: vi.fn().mockResolvedValue([]), + }; + const logger = { log: vi.fn() }; + const clock = { now: () => 12345 }; + const idGen = { newId: () => "note-uuid-1" }; + + const note = await recordFeedback( + { + teamId: asTeamId("team-1"), + authorMembershipId: asMembershipId("mship-1"), + threadId: null, + rawText: "Issue with Freighter wallet", + repoHint: "puls3", + sourceType: "text", + }, + { + feedbackRepo, + repoTopicLinkRepo, + logger, + clock, + idGen, + }, + ); + + expect(note).toEqual({ + id: "note-uuid-1", + teamId: asTeamId("team-1"), + authorMembershipId: asMembershipId("mship-1"), + repoHint: "puls3", + rawText: "Issue with Freighter wallet", + sourceType: "text", + status: "inbox", + createdAt: 12345, + updatedAt: 12345, + }); + expect(save).toHaveBeenCalledWith(asTeamId("team-1"), note); + }); + + it("infers repo hint from topic link if omitted", async () => { + const save = vi.fn().mockResolvedValue(undefined); + const feedbackRepo = { save, list: vi.fn(), updateStatus: vi.fn() }; + const repoTopicLinkRepo = { + get: vi.fn(), + upsert: vi.fn(), + remove: vi.fn(), + list: vi.fn().mockResolvedValue([ + { + teamId: asTeamId("team-1"), + repoFullName: "org/puls3" as RepoFullName, + threadId: 99, + createdAt: 0, + }, + ]), + }; + const logger = { log: vi.fn() }; + const clock = { now: () => 20000 }; + const idGen = { newId: () => "note-uuid-2" }; + + const note = await recordFeedback( + { + teamId: asTeamId("team-1"), + authorMembershipId: asMembershipId("mship-1"), + threadId: 99, + rawText: "Login is broken in demo", + sourceType: "voice", + }, + { + feedbackRepo, + repoTopicLinkRepo, + logger, + clock, + idGen, + }, + ); + + expect(note.repoHint).toBe("org/puls3"); + expect(note.sourceType).toBe("voice"); + }); +}); diff --git a/test/domain/usecases/synthesize-feedback.test.ts b/test/domain/usecases/synthesize-feedback.test.ts new file mode 100644 index 0000000..74ad315 --- /dev/null +++ b/test/domain/usecases/synthesize-feedback.test.ts @@ -0,0 +1,88 @@ +import { describe, expect, it, vi } from "vitest"; +import { asMembershipId, asTeamId } from "../../../src/domain/ids"; +import type { FeedbackNote } from "../../../src/domain/entities"; +import { synthesizeFeedback } from "../../../src/domain/usecases/synthesize-feedback"; + +describe("synthesizeFeedback", () => { + it("returns empty summary when no pending notes exist", async () => { + const feedbackRepo = { + save: vi.fn(), + list: vi.fn().mockResolvedValue([]), + updateStatus: vi.fn(), + }; + const repoTopicLinkRepo = { + get: vi.fn(), + upsert: vi.fn(), + remove: vi.fn(), + list: vi.fn().mockResolvedValue([]), + }; + const synthesizer = { summarize: vi.fn() }; + const logger = { log: vi.fn() }; + + const result = await synthesizeFeedback( + { teamId: asTeamId("team-1"), repoHint: "puls3" }, + { feedbackRepo, repoTopicLinkRepo, synthesizer, logger }, + ); + + expect(result.totalNotes).toBe(0); + expect(result.startDate).toBeNull(); + expect(result.endDate).toBeNull(); + expect(result.summaryText).toBe(""); + expect(synthesizer.summarize).not.toHaveBeenCalled(); + }); + + it("calculates real date range across irregular intervals and formats summary", async () => { + const notes: FeedbackNote[] = [ + { + id: "note-1", + teamId: asTeamId("team-1"), + authorMembershipId: asMembershipId("m-1"), + repoHint: "puls3", + rawText: "First bug from 2 weeks ago", + sourceType: "text", + status: "inbox", + createdAt: 100000, + updatedAt: 100000, + }, + { + id: "note-2", + teamId: asTeamId("team-1"), + authorMembershipId: asMembershipId("m-1"), + repoHint: "puls3", + rawText: "Second bug from today", + sourceType: "voice", + status: "inbox", + createdAt: 500000, + updatedAt: 500000, + }, + ]; + + const feedbackRepo = { + save: vi.fn(), + list: vi.fn().mockResolvedValue(notes), + updateStatus: vi.fn(), + }; + const repoTopicLinkRepo = { + get: vi.fn(), + upsert: vi.fn(), + remove: vi.fn(), + list: vi.fn().mockResolvedValue([]), + }; + const synthesizer = { + summarize: vi.fn().mockResolvedValue("- Recurring issue in Freighter wallet"), + }; + const logger = { log: vi.fn() }; + + const result = await synthesizeFeedback( + { teamId: asTeamId("team-1"), repoHint: "puls3" }, + { feedbackRepo, repoTopicLinkRepo, synthesizer, logger }, + ); + + expect(result.totalNotes).toBe(2); + expect(result.startDate).toBe(100000); + expect(result.endDate).toBe(500000); + expect(result.summaryText).toBe("- Recurring issue in Freighter wallet"); + expect(result.noteIds).toEqual(["note-1", "note-2"]); + expect(synthesizer.summarize).toHaveBeenCalledWith(notes, undefined); + }); +}); From 5a64b8dcb9f84d4b80e11a1017e287b7654e77e8 Mon Sep 17 00:00:00 2001 From: moises-cisneros Date: Mon, 19 Oct 2026 23:52:48 -0400 Subject: [PATCH 3/5] feat(voice): support telegram voice notes with whisper stt transcription --- src/adapters/llm/workers-ai-whisper.ts | 45 +++++++++++++++++++ src/adapters/telegram/voice.ts | 25 +++++++++++ test/adapters/llm/workers-ai-whisper.test.ts | 47 ++++++++++++++++++++ 3 files changed, 117 insertions(+) create mode 100644 src/adapters/llm/workers-ai-whisper.ts create mode 100644 src/adapters/telegram/voice.ts create mode 100644 test/adapters/llm/workers-ai-whisper.test.ts diff --git a/src/adapters/llm/workers-ai-whisper.ts b/src/adapters/llm/workers-ai-whisper.ts new file mode 100644 index 0000000..a6fce7c --- /dev/null +++ b/src/adapters/llm/workers-ai-whisper.ts @@ -0,0 +1,45 @@ +import type { SpeechToText } from "../../domain/ports"; + +export type WorkersAiRun = ( + model: string, + inputs: Record, + options?: { signal?: AbortSignal }, +) => Promise; + +export const DEFAULT_WHISPER_MODEL = "@cf/openai/whisper-large-v3-turbo"; + +export interface WorkersAiWhisperOptions { + run: WorkersAiRun; + modelId?: string; +} + +export function createWorkersAiWhisper(options: WorkersAiWhisperOptions): SpeechToText { + const modelId = options.modelId?.trim() || DEFAULT_WHISPER_MODEL; + + return { + async transcribe(audioBuffer: ArrayBuffer, signal?: AbortSignal): Promise { + if (signal?.aborted) { + throw new DOMException("Aborted", "AbortError"); + } + + const audioArray = Array.from(new Uint8Array(audioBuffer)); + + const result = await options.run( + modelId, + { + audio: audioArray, + }, + signal ? { signal } : undefined, + ); + + if (typeof result === "object" && result !== null && "text" in result) { + const text = (result as { text: unknown }).text; + if (typeof text === "string") { + return text.trim(); + } + } + + return ""; + }, + }; +} diff --git a/src/adapters/telegram/voice.ts b/src/adapters/telegram/voice.ts new file mode 100644 index 0000000..aedf233 --- /dev/null +++ b/src/adapters/telegram/voice.ts @@ -0,0 +1,25 @@ +import type { Api } from "grammy"; + +export interface VoiceDownloader { + download(fileId: string): Promise; +} + +export function createTelegramVoiceDownloader( + api: Api, + botToken: string, +): VoiceDownloader { + return { + async download(fileId: string): Promise { + const file = await api.getFile(fileId); + if (!file.file_path) { + throw new Error("Telegram did not return a file_path for voice note"); + } + const url = `https://api.telegram.org/file/bot${botToken}/${file.file_path}`; + const response = await fetch(url); + if (!response.ok) { + throw new Error(`Failed to download voice file from Telegram: ${response.status}`); + } + return await response.arrayBuffer(); + }, + }; +} diff --git a/test/adapters/llm/workers-ai-whisper.test.ts b/test/adapters/llm/workers-ai-whisper.test.ts new file mode 100644 index 0000000..e8183e1 --- /dev/null +++ b/test/adapters/llm/workers-ai-whisper.test.ts @@ -0,0 +1,47 @@ +import { describe, expect, it, vi } from "vitest"; +import { + createWorkersAiWhisper, + DEFAULT_WHISPER_MODEL, +} from "../../../src/adapters/llm/workers-ai-whisper"; + +describe("createWorkersAiWhisper", () => { + it("transcribes audio buffer by calling run with audio array", async () => { + const run = vi.fn().mockResolvedValue({ text: " El botón de login no responde " }); + const whisper = createWorkersAiWhisper({ run }); + + const buffer = new Uint8Array([1, 2, 3, 4]).buffer; + const text = await whisper.transcribe(buffer); + + expect(text).toBe("El botón de login no responde"); + expect(run).toHaveBeenCalledTimes(1); + expect(run).toHaveBeenCalledWith( + DEFAULT_WHISPER_MODEL, + { audio: [1, 2, 3, 4] }, + undefined, + ); + }); + + it("handles custom model id and abort signals", async () => { + const run = vi.fn(); + const whisper = createWorkersAiWhisper({ + run, + modelId: "@cf/openai/whisper", + }); + + const controller = new AbortController(); + controller.abort(); + + await expect( + whisper.transcribe(new Uint8Array([5, 6]).buffer, controller.signal), + ).rejects.toThrow(); + expect(run).not.toHaveBeenCalled(); + }); + + it("returns empty string if result does not contain text", async () => { + const run = vi.fn().mockResolvedValue({}); + const whisper = createWorkersAiWhisper({ run }); + + const text = await whisper.transcribe(new Uint8Array([1]).buffer); + expect(text).toBe(""); + }); +}); From 0e5cf72e563e3ee40d00997a65922f555a8e478f Mon Sep 17 00:00:00 2001 From: moises-cisneros Date: Mon, 19 Oct 2026 23:53:09 -0400 Subject: [PATCH 4/5] feat(nl): wire feedback intents and synthesis in natural language pipeline --- .../llm/workers-ai-feedback-synthesizer.ts | 81 ++++ .../llm/workers-ai-intent-classifier.ts | 6 +- src/adapters/telegram/commands.ts | 8 + src/adapters/telegram/natural-language.ts | 150 ++++++- src/composition.ts | 18 + src/domain/nl/intents.ts | 21 + .../usecases/handle-natural-language.ts | 153 ++++++- .../workers-ai-feedback-synthesizer.test.ts | 95 +++++ .../telegram/natural-language.test.ts | 390 ++++++++++++++++++ .../usecases/handle-natural-language.test.ts | 150 ++++++- test/fakes/index.ts | 32 ++ 11 files changed, 1100 insertions(+), 4 deletions(-) create mode 100644 src/adapters/llm/workers-ai-feedback-synthesizer.ts create mode 100644 test/adapters/llm/workers-ai-feedback-synthesizer.test.ts create mode 100644 test/adapters/telegram/natural-language.test.ts diff --git a/src/adapters/llm/workers-ai-feedback-synthesizer.ts b/src/adapters/llm/workers-ai-feedback-synthesizer.ts new file mode 100644 index 0000000..a62b117 --- /dev/null +++ b/src/adapters/llm/workers-ai-feedback-synthesizer.ts @@ -0,0 +1,81 @@ +import type { FeedbackNote } from "../../domain/entities"; +import type { FeedbackSynthesizer } from "../../domain/usecases/synthesize-feedback"; + +export type WorkersAiRun = ( + model: string, + inputs: Record, + options?: { signal?: AbortSignal }, +) => Promise; + +export interface WorkersAiFeedbackSynthesizerOptions { + run: WorkersAiRun; + modelId: string; +} + +const SYSTEM_PROMPT = `Eres un asistente técnico de ingeniería de software para un equipo de desarrolladores. +Tu tarea es sintetizar una lista de observaciones de feedback y reportes de errores recibidos en Telegram. + +Reglas: +1. Agrupa observaciones duplicadas, similares o relacionadas por tema/componente. +2. Destaca severidad o impacto evidente. +3. Formula sugerencias accionables y redactadas de forma clara para redactar issues o tareas técnicas en GitHub. +4. Escribe en español neutro, conciso y profesional, utilizando formato Markdown limpio con viñetas. +5. NO inventes información que no esté en las notas.`; + +function extractText(raw: unknown): string { + if (raw !== null && typeof raw === "object" && "choices" in raw) { + const { choices } = raw as { choices: unknown }; + const first: unknown = Array.isArray(choices) ? choices[0] : undefined; + const message = + first !== null && typeof first === "object" + ? (first as { message?: unknown }).message + : undefined; + const content = + message !== null && typeof message === "object" + ? (message as { content?: unknown }).content + : undefined; + if (typeof content === "string") return content.trim(); + } + if (raw !== null && typeof raw === "object" && "response" in raw) { + const { response } = raw as { response: unknown }; + if (typeof response === "string") return response.trim(); + } + return ""; +} + +export function createWorkersAiFeedbackSynthesizer( + options: WorkersAiFeedbackSynthesizerOptions, +): FeedbackSynthesizer { + const { run, modelId } = options; + + return { + async summarize(notes: FeedbackNote[], signal?: AbortSignal): Promise { + if (notes.length === 0) return ""; + + const notesBlock = notes + .map((n, idx) => { + const dateStr = new Date(n.createdAt).toISOString().slice(0, 10); + const repo = n.repoHint ? ` [repo: ${n.repoHint}]` : ""; + const source = n.sourceType === "voice" ? " [audio]" : ""; + return `${idx + 1}. [${dateStr}]${repo}${source}: ${n.rawText}`; + }) + .join("\n"); + + const raw = await run( + modelId, + { + messages: [ + { role: "system", content: SYSTEM_PROMPT }, + { + role: "user", + content: `Por favor sintetiza las siguientes observaciones:\n\n${notesBlock}`, + }, + ], + }, + signal ? { signal } : undefined, + ); + + return extractText(raw); + }, + }; +} diff --git a/src/adapters/llm/workers-ai-intent-classifier.ts b/src/adapters/llm/workers-ai-intent-classifier.ts index cb2b448..bf23ee8 100644 --- a/src/adapters/llm/workers-ai-intent-classifier.ts +++ b/src/adapters/llm/workers-ai-intent-classifier.ts @@ -39,8 +39,12 @@ export interface WorkersAiIntentClassifierOptions { const SYSTEM_PROMPT = `You classify Spanish Telegram messages for a hackathon team bot. Reply with ONLY a JSON object: {"intent":"","confidence":0.0-1.0,"slots":{...}}. Allowed intent ids: ${NL_INTENT_IDS.join(", ")}. -Slots (optional strings): slug, url, repo, membershipId, profileField, profileValue, targetName. +Slots (optional strings): slug, url, repo, membershipId, profileField, profileValue, targetName, feedbackText, noteIds. profileField must be one of: full_name, emails, social_links, github_username. +For bug reports, issues, user feedback, or observations (e.g. "anota este bug en puls3: ...", "feedback de la demo: ..."), use intent "capture_feedback", with slots: repo (optional repo name), feedbackText (the raw observation text). +For listing feedback/bugs (e.g. "listar feedback", "qué bugs hay pendientes"), use intent "list_feedback", with slots: repo (optional). +For summarizing feedback/bugs (e.g. "resumen del feedback", "sintetizar notas de puls3"), use intent "summarize_feedback", with slots: repo (optional). +For archiving/triaging feedback (e.g. "marcar feedback como procesado", "archivar notas"), use intent "archive_feedback". For hackathon names in natural language (e.g. "BNB Chain", "Meta VR"), put the human name in targetName — do NOT invent slugs. In a forum topic, "esta/este hackathon" with no name → unlink_hackathon_topic or link_hackathon_topic with empty slug/targetName (topic context). If unsure, use intent "unknown" with low confidence. Never invent intents.`; diff --git a/src/adapters/telegram/commands.ts b/src/adapters/telegram/commands.ts index 5be80fc..c0db18c 100644 --- a/src/adapters/telegram/commands.ts +++ b/src/adapters/telegram/commands.ts @@ -18,6 +18,7 @@ import type { ChatAdminChecker, Clock, DmSelectionRepo, + FeedbackRepo, GithubOrgClaimRepo, IdGen, IntentClassifier, @@ -28,8 +29,11 @@ import type { NlConfirmationRepo, ProfileRepo, RepoTopicLinkRepo, + SpeechToText, TeamRepo, } from "../../domain/ports"; +import type { FeedbackSynthesizer } from "../../domain/usecases/synthesize-feedback"; +import type { VoiceDownloader } from "./voice"; import { callerLocation, resolveGroupMembership } from "./context"; import type { CallerLocation } from "./context"; import { runCommand } from "./command-outcome"; @@ -86,6 +90,10 @@ export interface CommandDeps extends HackathonCommandDeps { nlConfirmationRepo: NlConfirmationRepo; intentClassifier: IntentClassifier; nlModelPrimary: string; + feedbackRepo?: FeedbackRepo; + feedbackSynthesizer?: FeedbackSynthesizer; + speechToText?: SpeechToText; + voiceDownloader?: VoiceDownloader; } const profileFields = new Set([ diff --git a/src/adapters/telegram/natural-language.ts b/src/adapters/telegram/natural-language.ts index 54f3740..1a7306a 100644 --- a/src/adapters/telegram/natural-language.ts +++ b/src/adapters/telegram/natural-language.ts @@ -1,5 +1,5 @@ import type { Bot, Context, NextFunction } from "grammy"; -import type { Membership, ProfileField, RepoTopicLink } from "../../domain/entities"; +import type { FeedbackNote, Membership, ProfileField, RepoTopicLink } from "../../domain/entities"; import type { MembershipId, TeamId } from "../../domain/ids"; import { isEligibleNlMessage } from "../../domain/nl/eligibility"; import { joinLinesWithinLimit } from "../../domain/text-limit"; @@ -10,6 +10,7 @@ import type { ChatAdminChecker, ChatPublisher, Clock, + FeedbackRepo, ForumTopicManager, GithubOrgClaimRepo, HackathonAnalysisRepo, @@ -23,8 +24,19 @@ import type { ProfileRepo, RepoTopicLinkRepo, Sleep, + SpeechToText, TeamRepo, } from "../../domain/ports"; +import type { + FeedbackSynthesizer, + SynthesizedFeedbackSummary, +} from "../../domain/usecases/synthesize-feedback"; +import { + feedbackCopy, + formatFeedbackDateSpan, + formatShortDate, +} from "../../domain/copy"; +import type { VoiceDownloader } from "./voice"; import { handleNaturalLanguage } from "../../domain/usecases/handle-natural-language"; import { resolveNlConfirmation, @@ -76,6 +88,10 @@ export interface NaturalLanguageDeps { idGen: IdGen; logger: Logger; nlModelPrimary: string; + speechToText?: SpeechToText; + voiceDownloader?: VoiceDownloader; + feedbackRepo?: FeedbackRepo; + feedbackSynthesizer?: FeedbackSynthesizer; } function errorCodeOf(err: unknown): string { @@ -136,6 +152,36 @@ function formatProfiles( return `${profileCopy.teamHeader(teamId)}\n${memberships.map((m) => formatMemberBlock(m, fields)).join("\n\n")}`; } +function formatFeedbackList(notes: FeedbackNote[]): string { + if (notes.length === 0) { + return feedbackCopy.empty; + } + const lines = notes.map((n) => + feedbackCopy.noteLine( + n.id, + formatShortDate(n.createdAt), + n.rawText, + n.repoHint, + n.sourceType === "voice", + ), + ); + const header = `📥 Observaciones pendientes (${notes.length}):`; + return joinLinesWithinLimit([header, ...lines], REPLY_MAX, feedbackCopy.empty); +} + +function formatFeedbackSummary(summary: SynthesizedFeedbackSummary): string { + if (summary.totalNotes === 0) { + return feedbackCopy.noSynthesis; + } + const dateSpan = formatFeedbackDateSpan(summary.startDate, summary.endDate); + const header = feedbackCopy.summaryHeader(summary.totalNotes, dateSpan, summary.repoHint); + const full = `${header}\n\n${summary.summaryText}`; + if (full.length <= REPLY_MAX) { + return full; + } + return full.slice(0, REPLY_MAX - 3) + "…"; +} + function nlCopyBag() { return { help: nlCopy.help, @@ -162,6 +208,10 @@ function nlCopyBag() { lexiconHint: nlConfirmCopy.lexiconHint, confirmPrompt: nlConfirmCopy.confirmPrompt, confirmSummaries: nlConfirmCopy.summaries, + feedbackRecorded: feedbackCopy.recorded, + feedbackEmpty: feedbackCopy.empty, + feedbackNoSynthesis: feedbackCopy.noSynthesis, + feedbackArchived: feedbackCopy.archived, resolveCopy: { cancelled: nlConfirmCopy.cancelled, busy: nlConfirmCopy.busy, @@ -363,6 +413,8 @@ export function registerNaturalLanguage(bot: Bot, deps: NaturalLanguageDeps): vo copy: nlCopyBag(), formatRepoLinks, formatProfiles, + formatFeedbackList, + formatFeedbackSummary, }, ); if (result.kind === "ignore") { @@ -385,4 +437,100 @@ export function registerNaturalLanguage(bot: Bot, deps: NaturalLanguageDeps): vo } } }); + + bot.on("message:voice", async (ctx, next: NextFunction) => { + if (isPrivateChat(ctx) || !deps.speechToText || !deps.voiceDownloader) { + await next(); + return; + } + + const chatType = chatTypeOf(ctx); + const botUsername = bot.botInfo.username; + if (chatType === null || !botUsername) { + await next(); + return; + } + + const botId = bot.botInfo.id; + const replyFrom = ctx.message?.reply_to_message?.from; + const replyFromId = replyFrom?.id; + const isReplyToBot = replyFromId === botId; + + const caption = ctx.message?.caption; + const eligibility = isEligibleNlMessage({ + chatType, + text: caption ?? "", + botUsername, + botId, + isCommand: false, + replyFromBotId: isReplyToBot ? botId : null, + }); + + const inTopic = ctx.message?.message_thread_id !== undefined; + const eligibleVoice = eligibility.eligible || isReplyToBot || inTopic; + + if (!eligibleVoice) { + await next(); + return; + } + + const loc = ctx.chat; + const from = ctx.from; + const voice = ctx.message?.voice; + if (!loc || !from || !voice) { + await next(); + return; + } + + try { + const audioBuffer = await deps.voiceDownloader.download(voice.file_id); + const transcript = await deps.speechToText.transcribe(audioBuffer); + if (!transcript.trim()) { + await ctx.reply(feedbackCopy.voiceFailed); + return; + } + + const replyToMessageId = ctx.message?.reply_to_message?.message_id ?? null; + const replyFromUserId = replyFrom && !replyFrom.is_bot ? replyFrom.id : null; + + const result = await handleNaturalLanguage( + { + chatId: loc.id, + threadId: ctx.message?.message_thread_id ?? null, + callerTelegramUserId: from.id, + classifiedText: transcript, + replyToMessageId, + replyFromUserId, + sourceType: "voice", + }, + { + ...deps, + copy: nlCopyBag(), + formatRepoLinks, + formatProfiles, + formatFeedbackList, + formatFeedbackSummary, + }, + ); + if (result.kind === "ignore") { + await next(); + return; + } + if (result.kind === "done") return; + await ctx.reply(result.text); + } catch (err) { + deps.logger.log({ + event: "nl-voice", + outcome: "error", + errorCode: errorCodeOf(err), + reason: "nl-voice-handler-failed", + }); + try { + await ctx.reply(feedbackCopy.voiceFailed); + } catch { + /* ignore */ + } + } + }); } + diff --git a/src/composition.ts b/src/composition.ts index 4422b3a..7e8b88f 100644 --- a/src/composition.ts +++ b/src/composition.ts @@ -8,10 +8,14 @@ import { createD1AnalysisQuota } from "./adapters/d1/analysis-quota"; import { createD1HackathonAnalysisRepo } from "./adapters/d1/hackathon-analysis-repo"; import { createD1NlClassifyQuota } from "./adapters/d1/nl-classify-quota"; import { createD1NlConfirmationRepo } from "./adapters/d1/nl-confirmation-repo"; +import { createD1FeedbackRepo } from "./adapters/d1/feedback-repo"; import { createStaticFetcher } from "./adapters/http/safe-fetcher"; import { createQueueAnalysisJobQueue } from "./adapters/queue/analysis-job-queue"; import { createWorkersAiExtractor } from "./adapters/llm/workers-ai-extractor"; import { createWorkersAiIntentClassifier } from "./adapters/llm/workers-ai-intent-classifier"; +import { createWorkersAiWhisper } from "./adapters/llm/workers-ai-whisper"; +import { createWorkersAiFeedbackSynthesizer } from "./adapters/llm/workers-ai-feedback-synthesizer"; +import { createTelegramVoiceDownloader } from "./adapters/telegram/voice"; import { createD1DmSelectionRepo } from "./adapters/d1/dm-selection-repo"; import { createD1GithubOrgClaimRepo } from "./adapters/d1/github-org-claim-repo"; import { createD1MemberRepo } from "./adapters/d1/member-repo"; @@ -106,6 +110,16 @@ export function buildBot(env: Env) { const analysisJobQueue = createQueueAnalysisJobQueue(env.HACKATHON_QUEUE); const nlModelPrimary = env.NL_MODEL_PRIMARY?.trim() ?? ""; + const feedbackRepo = createD1FeedbackRepo(env.DB); + const speechToText = createWorkersAiWhisper({ + run: (model, inputs, options) => env.AI.run(model, inputs, options), + }); + const voiceDownloader = createTelegramVoiceDownloader(bot.api, env.BOT_TOKEN); + const feedbackSynthesizer = createWorkersAiFeedbackSynthesizer({ + run: (model, inputs, options) => env.AI.run(model, inputs, options), + modelId: nlModelPrimary, + }); + registerCommands(bot, { teamRepo, memberRepo, @@ -132,6 +146,10 @@ export function buildBot(env: Env) { modelId: nlModelPrimary, }), nlModelPrimary, + feedbackRepo, + speechToText, + voiceDownloader, + feedbackSynthesizer, }); return bot; diff --git a/src/domain/nl/intents.ts b/src/domain/nl/intents.ts index 4fd19f2..71010ea 100644 --- a/src/domain/nl/intents.ts +++ b/src/domain/nl/intents.ts @@ -23,6 +23,10 @@ export const NL_INTENT_IDS = [ "request_hackathon_analysis", "show_topic_hackathon", "participate_hackathon", + "capture_feedback", + "list_feedback", + "summarize_feedback", + "archive_feedback", "unknown", ] as const; @@ -35,6 +39,8 @@ export const NL_READ_INTENTS = new Set([ "list_hackathons", "show_hackathon", "show_topic_hackathon", + "list_feedback", + "summarize_feedback", "unknown", ]); @@ -61,6 +67,9 @@ export type NlSlots = { profileField?: "full_name" | "emails" | "social_links" | "github_username"; profileValue?: string; targetName?: string; + feedbackText?: string; + noteIds?: string[]; + since?: number; // Pending multi-match pick for unlink (and later other slug intents). pickSlugs?: string[]; }; @@ -150,6 +159,18 @@ function parseSlots(raw: unknown): NlSlots { if (typeof obj.targetName === "string" && obj.targetName.trim() !== "") { slots.targetName = obj.targetName.trim(); } + if (typeof obj.feedbackText === "string" && obj.feedbackText.trim() !== "") { + slots.feedbackText = obj.feedbackText.trim(); + } + if (Array.isArray(obj.noteIds)) { + const noteIds = obj.noteIds.filter( + (item): item is string => typeof item === "string" && item.trim() !== "", + ); + if (noteIds.length > 0) slots.noteIds = noteIds.map((s) => s.trim()); + } + if (typeof obj.since === "number" && Number.isFinite(obj.since)) { + slots.since = obj.since; + } if (Array.isArray(obj.pickSlugs)) { const pickSlugs = obj.pickSlugs.filter( (item): item is string => typeof item === "string" && item.trim() !== "", diff --git a/src/domain/usecases/handle-natural-language.ts b/src/domain/usecases/handle-natural-language.ts index 0117bd0..0f073aa 100644 --- a/src/domain/usecases/handle-natural-language.ts +++ b/src/domain/usecases/handle-natural-language.ts @@ -1,4 +1,10 @@ -import type { Membership, ProfileField, RepoTopicLink } from "../entities"; +import type { + FeedbackNote, + FeedbackSource, + Membership, + ProfileField, + RepoTopicLink, +} from "../entities"; import { AnalysisNotFoundError, ConfigError, @@ -23,6 +29,7 @@ import { matchConfirmLexicon } from "../nl/lexicon"; import type { ChatPublisher, Clock, + FeedbackRepo, GithubOrgClaimRepo, HackathonAnalysisRepo, IdGen, @@ -52,6 +59,15 @@ import { } from "../nl/hackathon-match"; import { showAnalysis } from "./show-analysis"; import { showTopicAnalysis } from "./show-topic-analysis"; +import { recordFeedback } from "./record-feedback"; +import { listFeedback } from "./list-feedback"; +import { + synthesizeFeedback, + type FeedbackSynthesizer, + type SynthesizedFeedbackSummary, +} from "./synthesize-feedback"; +import { archiveFeedback } from "./archive-feedback"; +import { feedbackCopy, formatFeedbackDateSpan, formatShortDate } from "../copy"; export interface NlCopyBag { help: string; @@ -79,6 +95,10 @@ export interface NlCopyBag { confirmPrompt: (summary: string) => string; confirmSummaries: NlConfirmSummaries; resolveCopy: ResolveNlConfirmationCopy; + feedbackRecorded?: (repo?: string | null) => string; + feedbackEmpty?: string; + feedbackNoSynthesis?: string; + feedbackArchived?: (count: number) => string; } export interface HandleNaturalLanguageInput { @@ -90,6 +110,7 @@ export interface HandleNaturalLanguageInput { replyToMessageId?: number | null; // When the user replied to another user — promote/demote target hint. replyFromUserId?: number | null; + sourceType?: FeedbackSource; } export interface HandleNaturalLanguageDeps extends Omit { @@ -115,6 +136,10 @@ export interface HandleNaturalLanguageDeps extends Omit string; + feedbackRepo?: FeedbackRepo; + feedbackSynthesizer?: FeedbackSynthesizer; + formatFeedbackList?: (notes: FeedbackNote[]) => string; + formatFeedbackSummary?: (summary: SynthesizedFeedbackSummary) => string; } export type HandleNaturalLanguageResult = @@ -227,6 +252,8 @@ export async function handleNaturalLanguage( inDataChannel, replyFromUserId: input.replyFromUserId ?? null, replyToMessageId: input.replyToMessageId ?? null, + classifiedText: input.classifiedText, + sourceType: input.sourceType, }, deps); } @@ -269,6 +296,8 @@ interface DispatchCtx { inDataChannel: boolean; replyFromUserId: number | null; replyToMessageId: number | null; + classifiedText: string; + sourceType?: FeedbackSource; } async function dispatchIntent( @@ -307,6 +336,128 @@ async function dispatchIntent( } case "show_profiles": return await showProfiles(slots, ctx, deps); + case "capture_feedback": { + if (!deps.feedbackRepo) { + return { kind: "reply", text: deps.copy.notConfigured }; + } + const textToSave = slots.feedbackText?.trim() || ctx.classifiedText.trim(); + const note = await recordFeedback( + { + teamId: ctx.teamId, + authorMembershipId: ctx.actorMembershipId, + threadId: ctx.threadId, + rawText: textToSave, + repoHint: slots.repo, + sourceType: ctx.sourceType ?? "text", + }, + { + feedbackRepo: deps.feedbackRepo, + repoTopicLinkRepo: deps.repoTopicLinkRepo, + idGen: deps.idGen, + clock: deps.clock, + logger: deps.logger, + }, + ); + const copyFn = deps.copy.feedbackRecorded ?? feedbackCopy.recorded; + return { kind: "reply", text: copyFn(note.repoHint) }; + } + case "list_feedback": { + if (!deps.feedbackRepo) { + return { kind: "reply", text: deps.copy.notConfigured }; + } + const notes = await listFeedback( + { + teamId: ctx.teamId, + threadId: ctx.threadId, + repoHint: slots.repo, + since: slots.since, + }, + { + feedbackRepo: deps.feedbackRepo, + repoTopicLinkRepo: deps.repoTopicLinkRepo, + }, + ); + if (notes.length === 0) { + return { kind: "reply", text: deps.copy.feedbackEmpty ?? feedbackCopy.empty }; + } + if (deps.formatFeedbackList) { + return { kind: "reply", text: deps.formatFeedbackList(notes) }; + } + const lines = notes.map((n) => + feedbackCopy.noteLine( + n.id, + formatShortDate(n.createdAt), + n.rawText, + n.repoHint, + n.sourceType === "voice", + ), + ); + const header = `📥 Observaciones pendientes (${notes.length}):`; + return { kind: "reply", text: [header, ...lines].join("\n") }; + } + case "summarize_feedback": { + if (!deps.feedbackRepo || !deps.feedbackSynthesizer) { + return { kind: "reply", text: deps.copy.notConfigured }; + } + const summary = await synthesizeFeedback( + { + teamId: ctx.teamId, + threadId: ctx.threadId, + repoHint: slots.repo, + since: slots.since, + }, + { + feedbackRepo: deps.feedbackRepo, + repoTopicLinkRepo: deps.repoTopicLinkRepo, + synthesizer: deps.feedbackSynthesizer, + logger: deps.logger, + }, + ); + if (summary.totalNotes === 0) { + return { + kind: "reply", + text: deps.copy.feedbackNoSynthesis ?? feedbackCopy.noSynthesis, + }; + } + if (deps.formatFeedbackSummary) { + return { kind: "reply", text: deps.formatFeedbackSummary(summary) }; + } + const dateSpan = formatFeedbackDateSpan(summary.startDate, summary.endDate); + const header = feedbackCopy.summaryHeader(summary.totalNotes, dateSpan, summary.repoHint); + return { kind: "reply", text: `${header}\n\n${summary.summaryText}` }; + } + case "archive_feedback": { + if (!deps.feedbackRepo) { + return { kind: "reply", text: deps.copy.notConfigured }; + } + let noteIds = slots.noteIds ?? []; + if (noteIds.length === 0) { + const pending = await listFeedback( + { + teamId: ctx.teamId, + threadId: ctx.threadId, + repoHint: slots.repo, + }, + { + feedbackRepo: deps.feedbackRepo, + repoTopicLinkRepo: deps.repoTopicLinkRepo, + }, + ); + noteIds = pending.map((n) => n.id); + } + const result = await archiveFeedback( + { + teamId: ctx.teamId, + noteIds, + }, + { + feedbackRepo: deps.feedbackRepo, + logger: deps.logger, + }, + ); + const copyFn = deps.copy.feedbackArchived ?? feedbackCopy.archived; + return { kind: "reply", text: copyFn(result.updatedCount) }; + } default: return { kind: "reply", text: deps.copy.unknown }; } diff --git a/test/adapters/llm/workers-ai-feedback-synthesizer.test.ts b/test/adapters/llm/workers-ai-feedback-synthesizer.test.ts new file mode 100644 index 0000000..3e90c1f --- /dev/null +++ b/test/adapters/llm/workers-ai-feedback-synthesizer.test.ts @@ -0,0 +1,95 @@ +import { describe, expect, it } from "vitest"; +import { createWorkersAiFeedbackSynthesizer } from "../../../src/adapters/llm/workers-ai-feedback-synthesizer"; +import type { FeedbackNote } from "../../../src/domain/entities"; +import { asMembershipId, asTeamId } from "../../../src/domain/ids"; + +describe("createWorkersAiFeedbackSynthesizer", () => { + it("returns empty string when notes array is empty", async () => { + let called = false; + const synthesizer = createWorkersAiFeedbackSynthesizer({ + modelId: "@cf/meta/llama-3-8b-instruct", + run: async () => { + called = true; + return { response: "Summary" }; + }, + }); + + const result = await synthesizer.summarize([]); + expect(result).toBe(""); + expect(called).toBe(false); + }); + + it("calls run with formatted notes and returns response text", async () => { + let capturedModel = ""; + let capturedMessages: unknown = null; + + const synthesizer = createWorkersAiFeedbackSynthesizer({ + modelId: "@cf/meta/llama-3-8b-instruct", + run: async (model, inputs) => { + capturedModel = model; + capturedMessages = inputs.messages; + return { response: "Resumen estructurado de observaciones." }; + }, + }); + + const notes: FeedbackNote[] = [ + { + id: "note-1", + teamId: asTeamId("team-1"), + authorMembershipId: asMembershipId("mem-1"), + repoHint: "org/puls3", + rawText: "El login da error 500", + sourceType: "text", + status: "inbox", + createdAt: 1700000000000, + updatedAt: 1700000000000, + }, + { + id: "note-2", + teamId: asTeamId("team-1"), + authorMembershipId: asMembershipId("mem-2"), + repoHint: null, + rawText: "El audio se escucha cortado", + sourceType: "voice", + status: "inbox", + createdAt: 1700000001000, + updatedAt: 1700000001000, + }, + ]; + + const result = await synthesizer.summarize(notes); + expect(result).toBe("Resumen estructurado de observaciones."); + expect(capturedModel).toBe("@cf/meta/llama-3-8b-instruct"); + const msgs = capturedMessages as Array<{ role: string; content: string }>; + expect(msgs).toHaveLength(2); + expect(msgs[0]?.role).toBe("system"); + expect(msgs[1]?.content).toContain("El login da error 500"); + expect(msgs[1]?.content).toContain("[audio]"); + }); + + it("handles choices[0].message.content shape", async () => { + const synthesizer = createWorkersAiFeedbackSynthesizer({ + modelId: "@cf/meta/llama-3-8b-instruct", + run: async () => ({ + choices: [{ message: { content: "Resumen desde choices" } }], + }), + }); + + const notes: FeedbackNote[] = [ + { + id: "note-1", + teamId: asTeamId("team-1"), + authorMembershipId: asMembershipId("mem-1"), + repoHint: null, + rawText: "Test", + sourceType: "text", + status: "inbox", + createdAt: 1700000000000, + updatedAt: 1700000000000, + }, + ]; + + const result = await synthesizer.summarize(notes); + expect(result).toBe("Resumen desde choices"); + }); +}); diff --git a/test/adapters/telegram/natural-language.test.ts b/test/adapters/telegram/natural-language.test.ts new file mode 100644 index 0000000..e5e8bee --- /dev/null +++ b/test/adapters/telegram/natural-language.test.ts @@ -0,0 +1,390 @@ +import { Bot } from "grammy"; +import type { Update } from "grammy/types"; +import { describe, expect, it } from "vitest"; +import { registerNaturalLanguage } from "../../../src/adapters/telegram/natural-language"; +import { asMemberId, asMembershipId, asTeamId } from "../../../src/domain/ids"; +import { feedbackCopy } from "../../../src/domain/copy"; +import { createSafeLogger } from "../../../src/adapters/log/safe-logger"; +import { + fakeAnalysisJobQueue, + fakeAnalysisJobRepo, + fakeAnalysisQuota, + fakeChatAdminChecker, + fakeChatPublisher, + fakeClock, + fakeFeedbackRepo, + fakeForumTopicManager, + fakeGithubOrgClaimRepo, + fakeHackathonAnalysisRepo, + fakeIdGen, + fakeIntentClassifier, + fakeMemberRepo, + fakeMembershipRepo, + fakeNlClassifyQuota, + fakeNlConfirmationRepo, + fakeProfileRepo, + fakeRepoTopicLinkRepo, + fakeSleep, + fakeTeamRepo, +} from "../../fakes"; + +function makeBot(opts: { + intentClassifierFn?: Parameters[0]; + transcribeResult?: string; + transcribeThrows?: boolean; +} = {}) { + const bot = new Bot("123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11", { + botInfo: { + id: 1, + is_bot: true, + first_name: "TestBot", + username: "test_bot", + can_join_groups: true, + can_read_all_group_messages: false, + supports_inline_queries: false, + can_connect_to_business: false, + has_main_web_app: false, + has_topics_enabled: false, + allows_users_to_create_topics: false, + can_manage_bots: false, + supports_join_request_queries: false, + }, + }); + + const replies: Array<{ chatId: number; text: string }> = []; + bot.api.config.use((_prev, method, payload) => { + if (method === "sendMessage") { + const p = payload as { chat_id: number; text: string }; + replies.push({ chatId: p.chat_id, text: p.text }); + return Promise.resolve({ + ok: true, + result: { message_id: replies.length, date: 0, chat: { id: p.chat_id, type: "supergroup" } }, + } as never); + } + return Promise.resolve({ ok: true, result: {} } as never); + }); + + const teamRepo = fakeTeamRepo(); + const memberRepo = fakeMemberRepo(); + const membershipRepo = fakeMembershipRepo(memberRepo); + const feedbackRepo = fakeFeedbackRepo(); + const intentClassifier = fakeIntentClassifier(opts.intentClassifierFn); + + const downloadedFileIds: string[] = []; + const voiceDownloader = { + download: async (fileId: string) => { + downloadedFileIds.push(fileId); + return new Uint8Array([1, 2, 3]).buffer; + }, + }; + + const speechToText = { + transcribe: async () => { + if (opts.transcribeThrows) throw new Error("Whisper failed"); + return opts.transcribeResult ?? "audio transcription"; + }, + }; + + const feedbackSynthesizer = { + summarize: async (notes: unknown[]) => `Resumen sintético de ${notes.length} notas.`, + }; + + const deps = { + teamRepo, + memberRepo, + membershipRepo, + profileRepo: fakeProfileRepo(), + hackathonAnalysisRepo: fakeHackathonAnalysisRepo(), + repoTopicLinkRepo: fakeRepoTopicLinkRepo(), + githubOrgClaimRepo: fakeGithubOrgClaimRepo(), + analysisQuota: fakeAnalysisQuota(), + analysisJobRepo: fakeAnalysisJobRepo(), + analysisJobQueue: fakeAnalysisJobQueue(), + chatAdminChecker: fakeChatAdminChecker([]), + chatPublisher: fakeChatPublisher(), + forumTopicManager: fakeForumTopicManager(), + nlClassifyQuota: fakeNlClassifyQuota({ allow: true }), + nlConfirmationRepo: fakeNlConfirmationRepo(), + intentClassifier, + sleep: fakeSleep(), + clock: fakeClock(), + idGen: fakeIdGen(), + logger: createSafeLogger(), + nlModelPrimary: "@cf/test/model", + feedbackRepo, + feedbackSynthesizer, + speechToText, + voiceDownloader, + }; + + registerNaturalLanguage(bot, deps); + + // Seed team & member + const teamId = asTeamId("team-nl-group"); + const memberId = asMemberId("member-nl-1"); + const membershipId = asMembershipId("membership-nl-1"); + + teamRepo.rows.push({ + id: teamId, + chatId: -100123456, + dataTopicThreadId: null, + createdAt: 0, + }); + memberRepo.rows.push({ + id: memberId, + telegramUserId: 42, + createdAt: 0, + }); + membershipRepo.rows.push({ + id: membershipId, + teamId, + memberId, + role: "member", + joinedAt: 0, + }); + + return { bot, deps, replies, downloadedFileIds, teamId, membershipId }; +} + +let nextUpdateId = 1000; + +describe("Natural Language Adapter — Feedback Flows", () => { + it("captures text feedback via @bot mention in a group", async () => { + const { bot, deps, replies } = makeBot({ + intentClassifierFn: () => ({ + intent: "capture_feedback", + confidence: 0.95, + slots: { feedbackText: "Error 500 al guardar perfil", repo: "org/puls3" }, + }), + }); + + const update: Update = { + update_id: nextUpdateId++, + message: { + message_id: 101, + date: 0, + chat: { id: -100123456, type: "supergroup", title: "Dev Group" }, + from: { id: 42, is_bot: false, first_name: "Alice" }, + text: "@test_bot encontré un bug: Error 500 al guardar perfil", + }, + }; + + await bot.handleUpdate(update); + + expect(replies).toHaveLength(1); + expect(replies[0]?.text).toContain("Nota guardada en el buzón"); + expect(replies[0]?.text).toContain("org/puls3"); + expect(deps.feedbackRepo.rows).toHaveLength(1); + expect(deps.feedbackRepo.rows[0]?.rawText).toBe("Error 500 al guardar perfil"); + expect(deps.feedbackRepo.rows[0]?.sourceType).toBe("text"); + expect(deps.feedbackRepo.rows[0]?.status).toBe("inbox"); + }); + + it("captures voice note feedback via voice message in group", async () => { + const { bot, deps, replies, downloadedFileIds } = makeBot({ + transcribeResult: "hay un problema con el audio en la demo", + intentClassifierFn: () => ({ + intent: "capture_feedback", + confidence: 0.92, + slots: { feedbackText: "hay un problema con el audio en la demo" }, + }), + }); + + const update: Update = { + update_id: nextUpdateId++, + message: { + message_id: 102, + date: 0, + chat: { id: -100123456, type: "supergroup", title: "Dev Group" }, + from: { id: 42, is_bot: false, first_name: "Alice" }, + message_thread_id: 55, // topic + voice: { + file_id: "voice-file-xyz", + file_unique_id: "voice-unique-xyz", + duration: 3, + }, + }, + }; + + await bot.handleUpdate(update); + + expect(downloadedFileIds).toEqual(["voice-file-xyz"]); + expect(replies).toHaveLength(1); + expect(replies[0]?.text).toContain("Nota guardada en el buzón"); + expect(deps.feedbackRepo.rows).toHaveLength(1); + expect(deps.feedbackRepo.rows[0]?.rawText).toBe("hay un problema con el audio en la demo"); + expect(deps.feedbackRepo.rows[0]?.sourceType).toBe("voice"); + expect(deps.feedbackRepo.rows[0]?.status).toBe("inbox"); + }); + + it("replies with friendly failure message when audio transcription is empty", async () => { + const { bot, replies } = makeBot({ + transcribeResult: " ", + }); + + const update: Update = { + update_id: nextUpdateId++, + message: { + message_id: 103, + date: 0, + chat: { id: -100123456, type: "supergroup", title: "Dev Group" }, + from: { id: 42, is_bot: false, first_name: "Alice" }, + message_thread_id: 55, + voice: { + file_id: "voice-empty", + file_unique_id: "voice-empty-unique", + duration: 1, + }, + }, + }; + + await bot.handleUpdate(update); + + expect(replies).toHaveLength(1); + expect(replies[0]?.text).toBe(feedbackCopy.voiceFailed); + }); + + it("replies with friendly failure message when whisper throws", async () => { + const { bot, replies } = makeBot({ + transcribeThrows: true, + }); + + const update: Update = { + update_id: nextUpdateId++, + message: { + message_id: 104, + date: 0, + chat: { id: -100123456, type: "supergroup", title: "Dev Group" }, + from: { id: 42, is_bot: false, first_name: "Alice" }, + message_thread_id: 55, + voice: { + file_id: "voice-throw", + file_unique_id: "voice-throw-unique", + duration: 2, + }, + }, + }; + + await bot.handleUpdate(update); + + expect(replies).toHaveLength(1); + expect(replies[0]?.text).toBe(feedbackCopy.voiceFailed); + }); + + it("lists pending feedback via natural language", async () => { + const { bot, deps, replies, teamId, membershipId } = makeBot({ + intentClassifierFn: () => ({ + intent: "list_feedback", + confidence: 0.9, + slots: {}, + }), + }); + + await deps.feedbackRepo.save(teamId, { + id: "note-123456", + teamId, + authorMembershipId: membershipId, + repoHint: "puls3", + rawText: "El login no funciona en staging", + sourceType: "text", + status: "inbox", + createdAt: 1700000000000, + updatedAt: 1700000000000, + }); + + const update: Update = { + update_id: nextUpdateId++, + message: { + message_id: 105, + date: 0, + chat: { id: -100123456, type: "supergroup", title: "Dev Group" }, + from: { id: 42, is_bot: false, first_name: "Alice" }, + text: "@test_bot lista las notas de feedback", + }, + }; + + await bot.handleUpdate(update); + + expect(replies).toHaveLength(1); + expect(replies[0]?.text).toContain("Observaciones pendientes (1)"); + expect(replies[0]?.text).toContain("El login no funciona en staging"); + }); + + it("synthesizes feedback via natural language", async () => { + const { bot, deps, replies, teamId, membershipId } = makeBot({ + intentClassifierFn: () => ({ + intent: "summarize_feedback", + confidence: 0.9, + slots: {}, + }), + }); + + await deps.feedbackRepo.save(teamId, { + id: "note-abc", + teamId, + authorMembershipId: membershipId, + repoHint: "puls3", + rawText: "Bug en auth", + sourceType: "voice", + status: "inbox", + createdAt: 1700000000000, + updatedAt: 1700000000000, + }); + + const update: Update = { + update_id: nextUpdateId++, + message: { + message_id: 106, + date: 0, + chat: { id: -100123456, type: "supergroup", title: "Dev Group" }, + from: { id: 42, is_bot: false, first_name: "Alice" }, + text: "@test_bot resume el feedback acumulado", + }, + }; + + await bot.handleUpdate(update); + + expect(replies).toHaveLength(1); + expect(replies[0]?.text).toContain("Resumen de 1 observación"); + expect(replies[0]?.text).toContain("Resumen sintético de 1 notas."); + }); + + it("archives feedback via natural language", async () => { + const { bot, deps, replies, teamId, membershipId } = makeBot({ + intentClassifierFn: () => ({ + intent: "archive_feedback", + confidence: 0.9, + slots: { noteIds: ["note-abc"] }, + }), + }); + + await deps.feedbackRepo.save(teamId, { + id: "note-abc", + teamId, + authorMembershipId: membershipId, + repoHint: "puls3", + rawText: "Bug en auth", + sourceType: "text", + status: "inbox", + createdAt: 1700000000000, + updatedAt: 1700000000000, + }); + + const update: Update = { + update_id: nextUpdateId++, + message: { + message_id: 107, + date: 0, + chat: { id: -100123456, type: "supergroup", title: "Dev Group" }, + from: { id: 42, is_bot: false, first_name: "Alice" }, + text: "@test_bot archiva note-abc", + }, + }; + + await bot.handleUpdate(update); + + expect(replies).toHaveLength(1); + expect(replies[0]?.text).toBe("1 observación archivada."); + expect(deps.feedbackRepo.rows[0]?.status).toBe("triaged"); + }); +}); diff --git a/test/domain/usecases/handle-natural-language.test.ts b/test/domain/usecases/handle-natural-language.test.ts index 826b108..4caecf3 100644 --- a/test/domain/usecases/handle-natural-language.test.ts +++ b/test/domain/usecases/handle-natural-language.test.ts @@ -28,6 +28,7 @@ import { fakeRepoTopicLinkRepo, fakeSleep, fakeTeamRepo, + fakeFeedbackRepo, } from "../../fakes"; const COPY: NlCopyBag = { @@ -117,6 +118,7 @@ function makeDeps( const intentClassifier = fakeIntentClassifier(overrides.intent); const chatPublisher = fakeChatPublisher(); const hackathonAnalysisRepo = fakeHackathonAnalysisRepo(); + const feedbackRepo = fakeFeedbackRepo(); const deps: HandleNaturalLanguageDeps = { teamRepo, memberRepo, @@ -143,10 +145,14 @@ function makeDeps( formatRepoLinks: (links) => links.length === 0 ? "none" : links.map((l) => l.repoFullName).join(","), formatProfiles: (_m, _f, teamId) => `profiles:${teamId}`, + feedbackRepo, + feedbackSynthesizer: { + summarize: async (notes) => `Synthesized ${notes.length} notes`, + }, }; return { deps, - repos: { teamRepo, memberRepo, membershipRepo, hackathonAnalysisRepo }, + repos: { teamRepo, memberRepo, membershipRepo, hackathonAnalysisRepo, feedbackRepo }, nlClassifyQuota, nlConfirmationRepo, intentClassifier, @@ -1030,4 +1036,146 @@ describe("handleNaturalLanguage", () => { expect(repos.hackathonAnalysisRepo.rows[0]?.threadId).not.toBeNull(); expect(chatPublisher.posted.some((p) => p.threadId !== null)).toBe(true); }); + + describe("feedback intents", () => { + it("handles capture_feedback and stores note in inbox", async () => { + const { deps, repos } = makeDeps({ + intent: () => ({ + intent: "capture_feedback", + confidence: 0.9, + slots: { feedbackText: "El login falla con 500", repo: "org/puls3" }, + }), + }); + const { teamId } = seedMemberTeam(repos, { chatId: 10, userId: 20 }); + + const result = await handleNaturalLanguage( + { + chatId: 10, + threadId: null, + callerTelegramUserId: 20, + classifiedText: "encontré un bug: el login falla con 500 en org/puls3", + }, + deps, + ); + + expect(result.kind).toBe("reply"); + if (result.kind !== "reply") return; + expect(result.text).toContain("Nota guardada en el buzón"); + expect(repos.feedbackRepo.rows).toHaveLength(1); + expect(repos.feedbackRepo.rows[0]?.rawText).toBe("El login falla con 500"); + expect(repos.feedbackRepo.rows[0]?.repoHint).toBe("org/puls3"); + expect(repos.feedbackRepo.rows[0]?.teamId).toBe(teamId); + }); + + it("handles list_feedback and returns active notes", async () => { + const { deps, repos } = makeDeps({ + intent: () => ({ + intent: "list_feedback", + confidence: 0.85, + slots: {}, + }), + }); + const { teamId, membershipId } = seedMemberTeam(repos, { chatId: 10, userId: 20 }); + await repos.feedbackRepo.save(teamId, { + id: "note-1", + teamId, + authorMembershipId: membershipId, + repoHint: "org/puls3", + rawText: "El modal no cierra", + sourceType: "text", + status: "inbox", + createdAt: 1000, + updatedAt: 1000, + }); + + const result = await handleNaturalLanguage( + { + chatId: 10, + threadId: null, + callerTelegramUserId: 20, + classifiedText: "qué feedback hay", + }, + deps, + ); + + expect(result.kind).toBe("reply"); + if (result.kind !== "reply") return; + expect(result.text).toContain("Observaciones pendientes"); + expect(result.text).toContain("El modal no cierra"); + }); + + it("handles summarize_feedback and returns synthesis briefing", async () => { + const { deps, repos } = makeDeps({ + intent: () => ({ + intent: "summarize_feedback", + confidence: 0.85, + slots: {}, + }), + }); + const { teamId, membershipId } = seedMemberTeam(repos, { chatId: 10, userId: 20 }); + await repos.feedbackRepo.save(teamId, { + id: "note-1", + teamId, + authorMembershipId: membershipId, + repoHint: "org/puls3", + rawText: "El modal no cierra", + sourceType: "text", + status: "inbox", + createdAt: 1000, + updatedAt: 1000, + }); + + const result = await handleNaturalLanguage( + { + chatId: 10, + threadId: null, + callerTelegramUserId: 20, + classifiedText: "resumen del feedback", + }, + deps, + ); + + expect(result.kind).toBe("reply"); + if (result.kind !== "reply") return; + expect(result.text).toContain("Resumen de 1 observación"); + expect(result.text).toContain("Synthesized 1 notes"); + }); + + it("handles archive_feedback and marks notes triaged", async () => { + const { deps, repos } = makeDeps({ + intent: () => ({ + intent: "archive_feedback", + confidence: 0.88, + slots: { noteIds: ["note-1"] }, + }), + }); + const { teamId, membershipId } = seedMemberTeam(repos, { chatId: 10, userId: 20 }); + await repos.feedbackRepo.save(teamId, { + id: "note-1", + teamId, + authorMembershipId: membershipId, + repoHint: "org/puls3", + rawText: "El modal no cierra", + sourceType: "text", + status: "inbox", + createdAt: 1000, + updatedAt: 1000, + }); + + const result = await handleNaturalLanguage( + { + chatId: 10, + threadId: null, + callerTelegramUserId: 20, + classifiedText: "archiva note-1", + }, + deps, + ); + + expect(result.kind).toBe("reply"); + if (result.kind !== "reply") return; + expect(result.text).toContain("1 observación archivada"); + expect(repos.feedbackRepo.rows[0]?.status).toBe("triaged"); + }); + }); }); diff --git a/test/fakes/index.ts b/test/fakes/index.ts index cc32e1e..20a2d51 100644 --- a/test/fakes/index.ts +++ b/test/fakes/index.ts @@ -10,6 +10,8 @@ import type { AnalysisJobMessage, AuditDraft, ClaimResult, + FeedbackNote, + FeedbackStatus, HackathonAnalysis, Member, Membership, @@ -29,6 +31,8 @@ import type { ChatAdminChecker, ChatPublisher, Clock, + FeedbackFilter, + FeedbackRepo, ForumTopicManager, Sleep, TopicCreateOptions, @@ -747,3 +751,31 @@ export function fakeSleep(onSleep?: (ms: number) => void): Sleep & { calls: numb }; return Object.assign(sleep, { calls }); } + +export function fakeFeedbackRepo(): FeedbackRepo & { rows: FeedbackNote[] } { + const rows: FeedbackNote[] = []; + return { + rows, + save: async (teamId, note) => { + rows.push(note); + }, + list: async (teamId, filter) => { + return rows + .filter((r) => r.teamId === teamId) + .filter((r) => (filter?.status ? r.status === filter.status : true)) + .filter((r) => (filter?.repoHint ? r.repoHint === filter.repoHint : true)) + .filter((r) => (filter?.since ? r.createdAt >= filter.since : true)) + .sort((a, b) => b.createdAt - a.createdAt) + .slice(0, filter?.limit ?? 50); + }, + updateStatus: async (teamId, noteIds, status) => { + const idSet = new Set(noteIds); + for (const row of rows) { + if (row.teamId === teamId && idSet.has(row.id)) { + row.status = status; + row.updatedAt = Date.now(); + } + } + }, + }; +} From b8f30e3a58fbb7b15f8e2113321ac37b7b55e2c3 Mon Sep 17 00:00:00 2001 From: moises-cisneros Date: Mon, 19 Oct 2026 23:53:28 -0400 Subject: [PATCH 5/5] docs(feedback): archive feedback-inbox specification and sync main specs --- .../2026-10-19-feedback-inbox/.openspec.yaml | 2 + .../2026-10-19-feedback-inbox/design.md | 85 +++++++++++++++++++ .../2026-10-19-feedback-inbox/proposal.md | 36 ++++++++ .../specs/bot-copy/spec.md | 19 +++++ .../specs/feedback-inbox/spec.md | 68 +++++++++++++++ .../specs/natural-language-text/spec.md | 84 ++++++++++++++++++ .../2026-10-19-feedback-inbox/tasks.md | 33 +++++++ openspec/specs/bot-copy/spec.md | 18 ++++ openspec/specs/feedback-inbox/spec.md | 70 +++++++++++++++ openspec/specs/natural-language-text/spec.md | 38 ++++++++- 10 files changed, 450 insertions(+), 3 deletions(-) create mode 100644 openspec/changes/archive/2026-10-19-feedback-inbox/.openspec.yaml create mode 100644 openspec/changes/archive/2026-10-19-feedback-inbox/design.md create mode 100644 openspec/changes/archive/2026-10-19-feedback-inbox/proposal.md create mode 100644 openspec/changes/archive/2026-10-19-feedback-inbox/specs/bot-copy/spec.md create mode 100644 openspec/changes/archive/2026-10-19-feedback-inbox/specs/feedback-inbox/spec.md create mode 100644 openspec/changes/archive/2026-10-19-feedback-inbox/specs/natural-language-text/spec.md create mode 100644 openspec/changes/archive/2026-10-19-feedback-inbox/tasks.md create mode 100644 openspec/specs/feedback-inbox/spec.md diff --git a/openspec/changes/archive/2026-10-19-feedback-inbox/.openspec.yaml b/openspec/changes/archive/2026-10-19-feedback-inbox/.openspec.yaml new file mode 100644 index 0000000..c1bc902 --- /dev/null +++ b/openspec/changes/archive/2026-10-19-feedback-inbox/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-10-19 diff --git a/openspec/changes/archive/2026-10-19-feedback-inbox/design.md b/openspec/changes/archive/2026-10-19-feedback-inbox/design.md new file mode 100644 index 0000000..7ba31c7 --- /dev/null +++ b/openspec/changes/archive/2026-10-19-feedback-inbox/design.md @@ -0,0 +1,85 @@ +## Context + +See `proposal.md` for motivation. The bot runs on Cloudflare Workers with Hono, grammY, D1 storage, and Workers AI. All tenant-scoped operations mandate `TeamId` as the first argument in domain ports. The Natural Language pipeline (`handle-natural-language.ts`) classifies user utterances into a closed set of intents using `@cf/meta/llama-3.1-8b-instruct`. Cloudflare Workers AI natively supports `@cf/openai/whisper-large-v3-turbo` for speech-to-text. + +## Goals / Non-Goals + +**Goals:** +- Provide team-scoped storage for raw bug reports, feedback, and demo observations in Cloudflare D1. +- Support both text messages and Telegram voice notes (`message:voice`), transcribing audio with Whisper before passing it to the intent classifier. +- Implement an adaptive, state-driven synthesis strategy: summarize whatever is pending in `status = 'inbox'`, reporting the real-world date range spanned, with optional natural language date narrowing. +- Provide AI-assisted synthesis of collected notes into a consolidated issue-ready briefing using Workers AI. +- Enable marking notes as `triaged` or `archived` so the inbox resets for future sessions. + +**Non-Goals:** +- Direct GitHub issue creation or mutation (remains the responsibility of local development workflows and CLI tools). +- Bot audio voice replies (text replies only). +- Public/unauthenticated feedback endpoints. + +## Decisions + +### Decision 1: Voice Note Pipeline via Whisper STT + +When grammY receives an eligible `message:voice`, the flow is: +1. `TelegramVoiceFetcher` uses `ctx.api.getFile(voice.file_id)` to resolve the download URL and fetches the raw audio buffer (OGG/Opus). +2. `SpeechToText` port calls Cloudflare Workers AI: + ```typescript + const response = await env.AI.run("@cf/openai/whisper-large-v3-turbo", { + audio: [...new Uint8Array(audioBuffer)], + }); + ``` +3. The resulting transcript text is passed directly into `handleNaturalLanguage({ classifiedText: transcript.text, ... })`. + +*Alternatives considered*: +- Using an external transcription API (e.g. OpenAI Whisper API): Rejected to avoid external API keys and latency; Cloudflare Workers AI runs within the worker's execution environment. + +### Decision 2: D1 Table Schema for Feedback Notes + +The new table `feedback_notes` follows multi-tenant architecture with strict `team_id` partitioning: + +```sql +CREATE TABLE feedback_notes ( + id TEXT PRIMARY KEY, + team_id TEXT NOT NULL REFERENCES teams(id), + author_membership_id TEXT NOT NULL REFERENCES memberships(id), + repo_hint TEXT, + raw_text TEXT NOT NULL, + source_type TEXT NOT NULL DEFAULT 'text', -- 'text' | 'voice' + status TEXT NOT NULL DEFAULT 'inbox', -- 'inbox' | 'triaged' | 'archived' + created_at INTEGER NOT NULL, + updated_at INTEGER NOT NULL +); + +CREATE INDEX idx_feedback_notes_team_status ON feedback_notes(team_id, status); +CREATE INDEX idx_feedback_notes_team_repo ON feedback_notes(team_id, repo_hint); +``` + +### Decision 3: Adaptive State-Driven Synthesis Strategy + +Instead of rigid calendar jobs (e.g., daily cron summaries), the synthesis operates on **unprocessed inbox state**: +- **Query**: Select notes matching `team_id`, `status = 'inbox'`, and matching `repo_hint` (if specified), ordered by `created_at ASC` up to 30 notes. +- **Date Span Metadata**: The use case extracts `min(created_at)` and `max(created_at)` from the matched set and formats the header (e.g., *"Resumen de 7 observaciones (12/10 al 19/10)"*). +- **Temporal Narrowing (Optional)**: If the user says *"resumen de hoy"* or *"resumen de esta semana"*, a `sinceTimestamp` filter is applied over the pending notes. +- **Triage Transition**: After a summary is reviewed, a member can mark the batch as processed (`archive_feedback`), moving their status to `triaged`. + +### Decision 4: Hexagonal Domain Ports & Use Cases + +Isolate storage and AI dependencies behind domain ports: +- `FeedbackRepo`: + - `save(teamId: TeamId, note: FeedbackNote): Promise` + - `list(teamId: TeamId, filter: FeedbackFilter): Promise` + - `updateStatus(teamId: TeamId, noteIds: string[], status: FeedbackStatus): Promise` +- `SpeechToText`: + - `transcribe(audioBuffer: ArrayBuffer, signal: AbortSignal): Promise` +- `FeedbackSynthesizer`: + - `synthesize(notes: FeedbackNote[], signal: AbortSignal): Promise` +- Domain use cases: + - `record-feedback.ts`: Validates caller membership, derives repo hint from topic context if omitted, and saves note. + - `list-feedback.ts`: Retrieves active notes for the team/repo. + - `synthesize-feedback.ts`: Loads active notes and formats them via `FeedbackSynthesizer`. + - `archive-feedback.ts`: Marks processed notes as `triaged`. + +## Risks / Trade-offs + +- **[Risk] Ambient noise in voice notes during live demos** → *Mitigation*: Whisper STT handles background chatter robustly; if confidence/length is below threshold, the bot returns a friendly error asking to re-record or type. +- **[Risk] Irregular activity creating huge note batches** → *Mitigation*: Synthesis is capped at 30 notes per batch, ensuring responses comfortably fit within the Workers AI context window and Telegram's 4096-character limit. diff --git a/openspec/changes/archive/2026-10-19-feedback-inbox/proposal.md b/openspec/changes/archive/2026-10-19-feedback-inbox/proposal.md new file mode 100644 index 0000000..1577fba --- /dev/null +++ b/openspec/changes/archive/2026-10-19-feedback-inbox/proposal.md @@ -0,0 +1,36 @@ +## Why + +During live demos, hackathons, and mobile testing, developers and team members encounter bugs and receive user feedback away from their development machines. Opening formal GitHub issues immediately is high-friction, leads to duplicate or poorly structured issues, and violates repository contribution standards. Furthermore, typing long bug descriptions on mobile during a demo is cumbersome compared to sending a quick voice message. + +This change introduces an in-chat feedback and bug inbox for Hack-bot, allowing team members to record raw observations and feedback via text or voice messages (transcribed with Whisper on Cloudflare Workers AI), store them per team and target repository, and synthesize all unprocessed inbox notes into consolidated briefings on demand. + +## What Changes + +- Add voice note transcription support to the natural language pipeline using Cloudflare Workers AI (`@cf/openai/whisper-large-v3-turbo`) so voice messages in Telegram are transcribed and routed seamlessly through the natural language intents. +- Add a new `feedback-inbox` domain capability and D1 storage table (`feedback_notes`) to store raw bug reports, feedback, and demo observations. +- Associate notes with the originating team, author (membership), target repository hint (if mentioned or inferred from topic), status (`inbox`, `triaged`, `archived`), and timestamp. +- Implement an adaptive, state-driven synthesis strategy: rather than relying on arbitrary daily or weekly calendar buckets, the synthesis operates on all pending notes (`status = 'inbox'`) regardless of elapsed time, indicating the actual date span covered, while optionally respecting natural language temporal requests (e.g., "resumen de hoy"). +- Extend natural language classification (`natural-language-text`) with new intents: + - `capture_feedback`: parse raw report text, optional repo hint, and tags. + - `list_feedback`: list recent unprocessed feedback notes for a team/repo. + - `summarize_feedback`: invoke LLM extraction to synthesize unprocessed notes into a structured briefing ready for GitHub issue creation. + - `archive_feedback`: mark notes or a summarized batch as triaged/archived. +- Add copy strings for feedback intake confirmation, listings, and summary presentation in `bot-copy`. + +## Capabilities + +### New Capabilities + +- `feedback-inbox`: Captures, queries, and manages raw feedback and bug observations in team-scoped storage, providing state-driven retrieval and AI-assisted synthesis of grouped observations without directly mutating GitHub. + +### Modified Capabilities + +- `natural-language-text`: Adds voice message transcription (`message:voice`) using Whisper STT and adds intent recognition and slot extraction for `capture_feedback`, `list_feedback`, `summarize_feedback`, and `archive_feedback` intents. +- `bot-copy`: Adds bot response copy for feedback intake acknowledgment, note listings, date-ranged summaries, and triaged status confirmations. + +## Impact + +- **Database**: New migration adding `feedback_notes` table with indexes on `(team_id, status)` and `(team_id, repo_hint)`. +- **Domain**: New ports and use cases for audio transcription, feedback recording, listing, status updates, and summary generation. +- **Adapters**: Telegram voice file download adapter, Cloudflare Workers AI Whisper STT adapter, D1 repository adapter for feedback notes, grammar/intent classifier updates for Workers AI. +- **Dependencies**: No new external dependencies; reuses existing Cloudflare Workers AI (`@cf/openai/whisper-large-v3-turbo` and `@cf/meta/llama-3.1-8b-instruct`) and D1 infrastructure. diff --git a/openspec/changes/archive/2026-10-19-feedback-inbox/specs/bot-copy/spec.md b/openspec/changes/archive/2026-10-19-feedback-inbox/specs/bot-copy/spec.md new file mode 100644 index 0000000..54a76d7 --- /dev/null +++ b/openspec/changes/archive/2026-10-19-feedback-inbox/specs/bot-copy/spec.md @@ -0,0 +1,19 @@ +## ADDED Requirements + +### Requirement: Feedback Inbox Copy Formatting + +The system MUST format all feedback intake confirmations, voice transcription messages, feedback listings, and synthesized summaries in neutral, professional Spanish without raw JSON or unmapped technical error codes, and within the 4096-character Telegram limit. + +#### Scenario: Feedback intake confirmation in Spanish +- **WHEN** a feedback note is stored +- **THEN** the confirmation message is sent in Spanish indicating that the observation was recorded in the inbox + +#### Scenario: Feedback summary formatting with date span +- **WHEN** a feedback synthesis briefing is rendered for Telegram +- **THEN** the header specifies the total count and date span of the included notes (e.g. "Resumen de 5 observaciones entre el 12/10 y el 19/10") +- **AND** all section headers, labels, and bullet points are presented in clean Spanish text +- **AND** fits within the Telegram length limits + +#### Scenario: Audio transcription failure copy +- **WHEN** a voice message cannot be transcribed due to noise or model failure +- **THEN** the bot responds with a friendly Spanish message indicating the audio could not be understood and requesting a repeat or text input diff --git a/openspec/changes/archive/2026-10-19-feedback-inbox/specs/feedback-inbox/spec.md b/openspec/changes/archive/2026-10-19-feedback-inbox/specs/feedback-inbox/spec.md new file mode 100644 index 0000000..c913d1e --- /dev/null +++ b/openspec/changes/archive/2026-10-19-feedback-inbox/specs/feedback-inbox/spec.md @@ -0,0 +1,68 @@ +## Purpose + +Provides a tenant-scoped feedback and bug observation inbox where team members capture unstructured notes via Telegram (text or voice), retrieve pending observations, and generate consolidated briefings without directly altering GitHub repositories. + +## ADDED Requirements + +### Requirement: Record Feedback and Bug Observations + +The system MUST allow authenticated team members to record raw feedback or bug observations scoped to their team, submitted as text or transcribed voice messages. Each note MUST store the raw text, the author's membership identifier, the timestamp of submission, an optional target repository hint, and an initial status of `inbox`. + +#### Scenario: Successfully capture a bug note with repository hint +- **WHEN** a team member records a note mentioning an explicit repository hint (e.g. `puls3`) +- **THEN** the system stores the observation in the team's inbox with `repo_hint` set to `puls3` +- **AND** sets status to `inbox` +- **AND** responds with an acknowledgment message confirming the note is recorded + +#### Scenario: Successfully capture general feedback without repository hint +- **WHEN** a team member records feedback without mentioning any repository +- **THEN** the system stores the observation with `repo_hint` set to null +- **AND** sets status to `inbox` +- **AND** acknowledges receipt + +#### Scenario: Non-member cannot record feedback +- **WHEN** a user who is not a registered member of the team attempts to record a note +- **THEN** the system rejects the operation +- **AND** does not persist any observation + +### Requirement: Query Feedback Notes + +The system MUST allow team members to list stored feedback notes for their team, optionally filtered by status (`inbox`, `triaged`, `archived`) and by target repository hint. + +#### Scenario: List active inbox notes +- **WHEN** a team member requests the list of pending feedback +- **THEN** the system returns all notes with status `inbox` for that team ordered by creation time descending +- **AND** limits the output to fit within Telegram message limits + +#### Scenario: Empty inbox returns designated notification +- **WHEN** a team member requests pending feedback but no notes exist in `inbox` status +- **THEN** the system returns a friendly message stating that the inbox is empty + +### Requirement: Adaptive State-Driven Feedback Synthesis + +The system MUST allow team members to trigger an AI-assisted synthesis of feedback notes. By default, the synthesis MUST operate on all pending notes (`status = 'inbox'`) regardless of elapsed days or intervals between notes, explicitly stating the start and end dates of the included observations. If the user specifies a natural language time window (e.g. "de hoy", "de esta semana"), the synthesis MUST narrow the selected inbox notes to that window. The output MUST group duplicate or related observations, highlight severity or impact, and format actionable suggestions ready for issue drafting, without mutating GitHub. + +#### Scenario: Synthesize pending notes across irregular intervals +- **WHEN** a team member requests a summary of feedback for a repository +- **AND** the inbox contains pending notes spanning multiple days or weeks with dormant gaps +- **THEN** the system aggregates all pending notes for that repository +- **AND** generates a structured summary indicating the date span of the aggregated notes +- **AND** does not create any GitHub issues or mutate remote repositories + +#### Scenario: Synthesize with temporal narrowing filter +- **WHEN** a team member explicitly asks for a summary "de hoy" or "de esta semana" +- **THEN** the system filters pending notes matching the requested time window +- **AND** generates the summary for that subset + +#### Scenario: Synthesize with no notes available +- **WHEN** a team member requests a summary for a repository that has no recorded notes in the target scope +- **THEN** the system informs the caller that there are no observations to synthesize + +### Requirement: Triage and Archive Feedback Notes + +The system MUST allow team members to mark individual feedback notes or an entire synthesized batch as `triaged` or `archived`, removing them from the active pending inbox. + +#### Scenario: Mark note as triaged +- **WHEN** a team member marks a note ID as triaged +- **THEN** the system updates its status to `triaged` +- **AND** confirms the update to the user diff --git a/openspec/changes/archive/2026-10-19-feedback-inbox/specs/natural-language-text/spec.md b/openspec/changes/archive/2026-10-19-feedback-inbox/specs/natural-language-text/spec.md new file mode 100644 index 0000000..77badb8 --- /dev/null +++ b/openspec/changes/archive/2026-10-19-feedback-inbox/specs/natural-language-text/spec.md @@ -0,0 +1,84 @@ +## MODIFIED Requirements + +### Requirement: Group-Only Eligible Delivery + +The system MUST accept natural-language handling only in group or supergroup chats (General and topics). The system MUST NOT run the NL path for private (DM) chats. Under Telegram privacy mode, an eligible NL message MUST be either (a) text or voice that `@`-mentions the bot username from `BOT_INFO`, or (b) a text or voice reply to a message authored by the bot. Other plain-text group messages MUST be ignored without error. When an eligible message is a voice note (`message:voice`), the system MUST transcribe the audio to text via Whisper Speech-to-Text before passing the transcribed text to intent classification. Recognized bot commands MUST continue to use the command handlers and MUST NOT also be classified as NL. + +#### Scenario: @mention in General is eligible + +- GIVEN a registered team group and the bot username from `BOT_INFO` +- WHEN a member sends a message that `@`-mentions that username followed by `qué hackathons hay` in General +- THEN the system enters the NL path + +#### Scenario: Reply to bot in a topic is eligible + +- GIVEN a forum topic in a registered team group +- WHEN a member replies to a bot message with `listá los repos` +- THEN the system enters the NL path + +#### Scenario: Plain text without mention or reply is ignored + +- GIVEN a registered team group +- WHEN a member sends `qué hackathons hay` without mentioning the bot and not as a reply to the bot +- THEN the system ignores the update without invoking the NL classifier + +#### Scenario: DM is ignored by NL + +- GIVEN a private chat with the bot +- WHEN the user `@`-mentions the bot username from `BOT_INFO` and asks for help +- THEN the system MUST NOT run the NL path + +#### Scenario: Commands are not double-handled + +- GIVEN a group message `/hackathons` +- WHEN the update is processed +- THEN the existing command handler runs +- AND the NL classifier is NOT called + +#### Scenario: Voice note mentioning the bot is transcribed and handled + +- GIVEN an eligible voice note in a group chat mentioning the bot or replying to a bot message +- WHEN the update is received +- THEN the system downloads the voice note audio +- AND transcribes it via Whisper STT +- AND passes the transcribed text to the NL classifier + +### Requirement: Closed Intent Coverage + +The system MUST classify eligible Spanish utterances into a closed intent set that covers every existing group capability: `help`, `setup_team`, `join_team`, `bind_data_channel`, `show_profiles`, `set_profile_field`, `promote_member`, `demote_member`, `link_repo`, `unlink_repo`, `list_repos`, `list_hackathons`, `show_hackathon`, `link_hackathon_topic`, `unlink_hackathon_topic`, `request_hackathon_analysis`, `show_topic_hackathon`, `participate_hackathon`, `capture_feedback`, `list_feedback`, `summarize_feedback`, `archive_feedback`, and `unknown`. Each non-`help`/`unknown` intent MUST dispatch to the same domain use case (or equivalent path) the matching slash command uses today, with the same authorization rules. + +#### Scenario: List hackathons via NL + +- GIVEN an eligible utterance classified as `list_hackathons` with sufficient confidence +- WHEN the member is a team member +- THEN the system replies with the same listing behavior as `/hackathons` + +#### Scenario: Unknown intent + +- GIVEN the classifier returns `unknown` or confidence below the design floor (0.55) +- WHEN the utterance is processed +- THEN the system replies with the unknown copy and performs no side effect + +#### Scenario: Capture feedback via NL + +- GIVEN an eligible utterance describing a bug, issue, or feedback classified as `capture_feedback` +- WHEN the caller is an authenticated team member +- THEN the system records the feedback note in the team inbox + +#### Scenario: List feedback via NL + +- GIVEN an eligible utterance requesting pending feedback classified as `list_feedback` +- WHEN the caller is an authenticated team member +- THEN the system replies with active feedback notes + +#### Scenario: Summarize feedback via NL + +- GIVEN an eligible utterance requesting a summary or synthesis of feedback classified as `summarize_feedback` +- WHEN the caller is an authenticated team member +- THEN the system synthesizes pending inbox observations and replies with the briefing + +#### Scenario: Archive feedback via NL + +- GIVEN an eligible utterance requesting to triage or archive feedback classified as `archive_feedback` +- WHEN the caller is an authenticated team member +- THEN the system updates the status of the target notes to `triaged` diff --git a/openspec/changes/archive/2026-10-19-feedback-inbox/tasks.md b/openspec/changes/archive/2026-10-19-feedback-inbox/tasks.md new file mode 100644 index 0000000..c5b023c --- /dev/null +++ b/openspec/changes/archive/2026-10-19-feedback-inbox/tasks.md @@ -0,0 +1,33 @@ +## 1. Storage and Schema + +- [x] 1.1 Add D1 migration creating `feedback_notes` table (with `source_type`) and indexes +- [x] 1.2 Define `FeedbackNote`, `FeedbackStatus`, and `FeedbackSource` in `src/domain/entities.ts` +- [x] 1.3 Add `FeedbackRepo` port contract to `src/domain/ports.ts` +- [x] 1.4 Implement D1 repository adapter in `src/adapters/d1/feedback-repo.ts` with unit tests + +## 2. Voice and Audio Transcription + +- [x] 2.1 Add `SpeechToText` port contract to `src/domain/ports.ts` +- [x] 2.2 Implement Workers AI Whisper adapter in `src/adapters/llm/workers-ai-whisper.ts` with unit tests +- [x] 2.3 Implement Telegram voice downloader helper using Bot API `getFile` in `src/adapters/telegram/voice.ts` +- [x] 2.4 Wire `message:voice` events in Telegram adapter to download, transcribe, and route into `handleNaturalLanguage` + +## 3. Domain Use Cases + +- [x] 3.1 Implement `recordFeedback` use case with repository hint resolution and unit tests +- [x] 3.2 Implement `listFeedback` use case with status and repo filters and unit tests +- [x] 3.3 Implement `synthesizeFeedback` adaptive use case (unprocessed inbox + date range detection) with unit tests +- [x] 3.4 Implement `archiveFeedback` use case to transition notes from `inbox` to `triaged` with unit tests + +## 4. Natural Language and Intent Integration + +- [x] 4.1 Add `capture_feedback`, `list_feedback`, `summarize_feedback`, and `archive_feedback` to `NL_INTENT_IDS` in `src/domain/nl/intents.ts` +- [x] 4.2 Update Workers AI intent prompt and slot parser in `src/adapters/llm/workers-ai-intent-classifier.ts` +- [x] 4.3 Wire new intents in `handle-natural-language.ts` to dispatch to feedback use cases + +## 5. Bot Copy, Wiring and Verification + +- [x] 5.1 Add Spanish copy strings for intake confirmation, empty inbox, date-ranged summaries, and transcription errors in `src/domain/copy.ts` +- [x] 5.2 Wire all new repositories, adapters, and use cases into `src/composition.ts` +- [x] 5.3 Add integration tests for text and voice feedback flows in `test/adapters/telegram/natural-language.test.ts` +- [x] 5.4 Run full test suite (`npm test`) and verify clean typecheck (`npm run typecheck`) diff --git a/openspec/specs/bot-copy/spec.md b/openspec/specs/bot-copy/spec.md index 533c25d..bc60f17 100644 --- a/openspec/specs/bot-copy/spec.md +++ b/openspec/specs/bot-copy/spec.md @@ -95,3 +95,21 @@ The system MUST map every code interpolated into user-visible text to a Spanish - GIVEN a pull request `review_requested` event - WHEN the alert is posted - THEN the header is "Revisión solicitada" + +### Requirement: Feedback Inbox Copy Formatting + +The system MUST format all feedback intake confirmations, voice transcription messages, feedback listings, and synthesized summaries in neutral, professional Spanish without raw JSON or unmapped technical error codes, and within the 4096-character Telegram limit. + +#### Scenario: Feedback intake confirmation in Spanish +- **WHEN** a feedback note is stored +- **THEN** the confirmation message is sent in Spanish indicating that the observation was recorded in the inbox + +#### Scenario: Feedback summary formatting with date span +- **WHEN** a feedback synthesis briefing is rendered for Telegram +- **THEN** the header specifies the total count and date span of the included notes (e.g. "Resumen de 5 observaciones entre el 12/10 y el 19/10") +- **AND** all section headers, labels, and bullet points are presented in clean Spanish text +- **AND** fits within the Telegram length limits + +#### Scenario: Audio transcription failure copy +- **WHEN** a voice message cannot be transcribed due to noise or model failure +- **THEN** the bot responds with a friendly Spanish message indicating the audio could not be understood and requesting a repeat or text input diff --git a/openspec/specs/feedback-inbox/spec.md b/openspec/specs/feedback-inbox/spec.md new file mode 100644 index 0000000..27dc71b --- /dev/null +++ b/openspec/specs/feedback-inbox/spec.md @@ -0,0 +1,70 @@ +# Feedback Inbox Specification + +## Purpose + +Provides a tenant-scoped feedback and bug observation inbox where team members capture unstructured notes via Telegram (text or voice), retrieve pending observations, and generate consolidated briefings without directly altering GitHub repositories. + +## Requirements + +### Requirement: Record Feedback and Bug Observations + +The system MUST allow authenticated team members to record raw feedback or bug observations scoped to their team, submitted as text or transcribed voice messages. Each note MUST store the raw text, the author's membership identifier, the timestamp of submission, an optional target repository hint, and an initial status of `inbox`. + +#### Scenario: Successfully capture a bug note with repository hint +- **WHEN** a team member records a note mentioning an explicit repository hint (e.g. `puls3`) +- **THEN** the system stores the observation in the team's inbox with `repo_hint` set to `puls3` +- **AND** sets status to `inbox` +- **AND** responds with an acknowledgment message confirming the note is recorded + +#### Scenario: Successfully capture general feedback without repository hint +- **WHEN** a team member records feedback without mentioning any repository +- **THEN** the system stores the observation with `repo_hint` set to null +- **AND** sets status to `inbox` +- **AND** acknowledges receipt + +#### Scenario: Non-member cannot record feedback +- **WHEN** a user who is not a registered member of the team attempts to record a note +- **THEN** the system rejects the operation +- **AND** does not persist any observation + +### Requirement: Query Feedback Notes + +The system MUST allow team members to list stored feedback notes for their team, optionally filtered by status (`inbox`, `triaged`, `archived`) and by target repository hint. + +#### Scenario: List active inbox notes +- **WHEN** a team member requests the list of pending feedback +- **THEN** the system returns all notes with status `inbox` for that team ordered by creation time descending +- **AND** limits the output to fit within Telegram message limits + +#### Scenario: Empty inbox returns designated notification +- **WHEN** a team member requests pending feedback but no notes exist in `inbox` status +- **THEN** the system returns a friendly message stating that the inbox is empty + +### Requirement: Adaptive State-Driven Feedback Synthesis + +The system MUST allow team members to trigger an AI-assisted synthesis of feedback notes. By default, the synthesis MUST operate on all pending notes (`status = 'inbox'`) regardless of elapsed days or intervals between notes, explicitly stating the start and end dates of the included observations. If the user specifies a natural language time window (e.g. "de hoy", "de esta semana"), the synthesis MUST narrow the selected inbox notes to that window. The output MUST group duplicate or related observations, highlight severity or impact, and format actionable suggestions ready for issue drafting, without mutating GitHub. + +#### Scenario: Synthesize pending notes across irregular intervals +- **WHEN** a team member requests a summary of feedback for a repository +- **AND** the inbox contains pending notes spanning multiple days or weeks with dormant gaps +- **THEN** the system aggregates all pending notes for that repository +- **AND** generates a structured summary indicating the date span of the aggregated notes +- **AND** does not create any GitHub issues or mutate remote repositories + +#### Scenario: Synthesize with temporal narrowing filter +- **WHEN** a team member explicitly asks for a summary "de hoy" or "de esta semana" +- **THEN** the system filters pending notes matching the requested time window +- **AND** generates the summary for that subset + +#### Scenario: Synthesize with no notes available +- **WHEN** a team member requests a summary for a repository that has no recorded notes in the target scope +- **THEN** the system informs the caller that there are no observations to synthesize + +### Requirement: Triage and Archive Feedback Notes + +The system MUST allow team members to mark individual feedback notes or an entire synthesized batch as `triaged` or `archived`, removing them from the active pending inbox. + +#### Scenario: Mark note as triaged +- **WHEN** a team member marks a note ID as triaged +- **THEN** the system updates its status to `triaged` +- **AND** confirms the update to the user diff --git a/openspec/specs/natural-language-text/spec.md b/openspec/specs/natural-language-text/spec.md index c187889..26f549d 100644 --- a/openspec/specs/natural-language-text/spec.md +++ b/openspec/specs/natural-language-text/spec.md @@ -2,13 +2,13 @@ ## Purpose -Lets team members drive every existing group bot capability by speaking Spanish in the team group: either `@`-mentioning the bot or replying to a message the bot posted, in General or in a forum topic. The bot maps utterances onto the existing typed use cases and permission gates. Slash commands remain fully supported. Mutations are confirm-first (inline button or affirmative reply). Bot copy is Spanish per `bot-copy`. Voice input and bot audio replies are out of scope. +Lets team members drive every existing group bot capability by speaking Spanish in the team group: either `@`-mentioning the bot or replying to a message the bot posted, in General or in a forum topic. The bot maps utterances onto the existing typed use cases and permission gates. Slash commands remain fully supported. Mutations are confirm-first (inline button or affirmative reply). Bot copy is Spanish per `bot-copy`. Audio replies are out of scope. Voice input via Whisper Speech-to-Text is supported. ## Requirements ### Requirement: Group-Only Eligible Delivery -The system MUST accept natural-language handling only in group or supergroup chats (General and topics). The system MUST NOT run the NL path for private (DM) chats. Under Telegram privacy mode, an eligible NL message MUST be either (a) text that `@`-mentions the bot username from `BOT_INFO`, or (b) a reply to a message authored by the bot. Other plain-text group messages MUST be ignored without error. Recognized bot commands MUST continue to use the command handlers and MUST NOT also be classified as NL. +The system MUST accept natural-language handling only in group or supergroup chats (General and topics). The system MUST NOT run the NL path for private (DM) chats. Under Telegram privacy mode, an eligible NL message MUST be either (a) text or voice that `@`-mentions the bot username from `BOT_INFO`, or (b) a text or voice reply to a message authored by the bot. Other plain-text group messages MUST be ignored without error. When an eligible message is a voice note (`message:voice`), the system MUST transcribe the audio to text via Whisper Speech-to-Text before passing the transcribed text to intent classification. Recognized bot commands MUST continue to use the command handlers and MUST NOT also be classified as NL. #### Scenario: @mention in General is eligible @@ -41,9 +41,17 @@ The system MUST accept natural-language handling only in group or supergroup cha - THEN the existing command handler runs - AND the NL classifier is NOT called +#### Scenario: Voice note mentioning the bot is transcribed and handled + +- GIVEN an eligible voice note in a group chat mentioning the bot or replying to a bot message +- WHEN the update is received +- THEN the system downloads the voice note audio +- AND transcribes it via Whisper STT +- AND passes the transcribed text to the NL classifier + ### Requirement: Closed Intent Coverage -The system MUST classify eligible Spanish utterances into a closed intent set that covers every existing group capability: `help`, `setup_team`, `join_team`, `bind_data_channel`, `show_profiles`, `set_profile_field`, `promote_member`, `demote_member`, `link_repo`, `unlink_repo`, `list_repos`, `list_hackathons`, `show_hackathon`, `link_hackathon_topic`, `unlink_hackathon_topic`, `request_hackathon_analysis`, `show_topic_hackathon`, `participate_hackathon`, and `unknown`. Each non-`help`/`unknown` intent MUST dispatch to the same domain use case (or equivalent path) the matching slash command uses today, with the same authorization rules. +The system MUST classify eligible Spanish utterances into a closed intent set that covers every existing group capability: `help`, `setup_team`, `join_team`, `bind_data_channel`, `show_profiles`, `set_profile_field`, `promote_member`, `demote_member`, `link_repo`, `unlink_repo`, `list_repos`, `list_hackathons`, `show_hackathon`, `link_hackathon_topic`, `unlink_hackathon_topic`, `request_hackathon_analysis`, `show_topic_hackathon`, `participate_hackathon`, `capture_feedback`, `list_feedback`, `summarize_feedback`, `archive_feedback`, and `unknown`. Each non-`help`/`unknown` intent MUST dispatch to the same domain use case (or equivalent path) the matching slash command uses today, with the same authorization rules. #### Scenario: List hackathons via NL @@ -57,6 +65,30 @@ The system MUST classify eligible Spanish utterances into a closed intent set th - WHEN the utterance is processed - THEN the system replies with the unknown copy and performs no side effect +#### Scenario: Capture feedback via NL + +- GIVEN an eligible utterance describing a bug, issue, or feedback classified as `capture_feedback` +- WHEN the caller is an authenticated team member +- THEN the system records the feedback note in the team inbox + +#### Scenario: List feedback via NL + +- GIVEN an eligible utterance requesting pending feedback classified as `list_feedback` +- WHEN the caller is an authenticated team member +- THEN the system replies with active feedback notes + +#### Scenario: Summarize feedback via NL + +- GIVEN an eligible utterance requesting a summary or synthesis of feedback classified as `summarize_feedback` +- WHEN the caller is an authenticated team member +- THEN the system synthesizes pending inbox observations and replies with the briefing + +#### Scenario: Archive feedback via NL + +- GIVEN an eligible utterance requesting to triage or archive feedback classified as `archive_feedback` +- WHEN the caller is an authenticated team member +- THEN the system updates the status of the target notes to `triaged` + ### Requirement: Dedicated Help Intent The system MUST treat `help` as a first-class intent distinct from `unknown`. Help MUST explain how to trigger NL (@mention or reply), give example phrases, and note that slash commands still work.