​

Voice Knowledge Search Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

​

Global Constraints

• The voice worker imports no backend modules and reaches platform state only through /internal/voice/v1.
• No instruction or knowledge content is preloaded; empty selection means all independently for each category.
• Selected scopes fail closed and never fall back to unrestricted organization content.
• Every search enforces organization, public visibility, phone channel, contact segment, draft/deletion, and active-time boundaries before candidate limiting.
• Retrieval uses one embedding with no query-generation model or reranker.
• Every Kysely migration up() and down() begins with SET LOCAL lock_timeout = '10s'.
• Handwritten code remains strictly typed: no any, no unknown in MCP code, and no inline casts other than as const.
• Any change under backend/voice-agent or backend/src/voice-runtime requires cd backend && pnpm voice:test before completion.
• Public copy describes outcomes and never names internal models, providers, infrastructure vendors, or libraries.

​

Task 1: Persist explicit knowledge selections

• Create: backend/src/db/kysely-migrations/20260824160000_add_phone_agent_knowledge_scopes.ts
• Create: backend/src/phone/phone.knowledge-scope-persistence.spec.ts
• Modify (generated): backend/src/db/opencx.ts

• Produces phone_agent_knowledgebase_items(id, phone_agent_id, knowledgebase_item_id).
• Produces phone_agent_knowledgebase_folders(id, phone_agent_id, folder_key).
• Agent/item foreign keys cascade and both agent-selection pairs are unique.
• Step 1: Write the failing schema contract test

test('stores independent knowledge item and folder selections', async () => {
  await db.insertInto('phone_agent_knowledgebase_items').values({
    phone_agent_id: agentId,
    knowledgebase_item_id: itemId,
  }).execute();
  await db.insertInto('phone_agent_knowledgebase_folders').values({
    phone_agent_id: agentId,
    folder_key: 'website:help.example.com',
  }).execute();
  expect(await db.selectFrom('phone_agent_knowledgebase_items').selectAll().execute()).toHaveLength(1);
  expect(await db.selectFrom('phone_agent_knowledgebase_folders').selectAll().execute()).toHaveLength(1);
});

• Step 2: Run RED

• Step 3: Add the migration and regenerate types

• Step 4: Run GREEN and commit

​

Task 2: Canonicalize knowledge-folder identities

• Create: backend/src/rag/knowledgebase/knowledgebase-folder.utils.ts
• Create: backend/src/rag/knowledgebase/knowledgebase-folder.utils.spec.ts
• Modify: backend/src/airbyte/knowledgebase-items.service.ts
• Modify: backend/src/airbyte/knowledgebase-items.service.spec.ts

• Produces KnowledgebaseFolderIdentity = { dataSource: KnowledgebaseDataSourceEnum; stream: string | null }.
• Produces static KnowledgebaseFolderUtils.toKey, fromKey, and fromItem methods.
• Step 1: Write table-driven RED tests with literal expectations

it.each([
  [{ sourceType: 'website', sourceUrl: 'https://help.example.com/a' }, 'website:help.example.com'],
  [{ sourceType: 'workflow', folder: 'Returns' }, 'workflow:Returns'],
  [{ sourceType: 'workflow', folder: null }, 'workflow:'],
])('round-trips %#', (item, expectedKey) => {
  const identity = KnowledgebaseFolderUtils.fromItem(item);
  expect(KnowledgebaseFolderUtils.toKey(identity)).toBe(expectedKey);
  expect(KnowledgebaseFolderUtils.fromKey(expectedKey)).toEqual(identity);
});

• Step 2: Implement and reuse the static utility

• Step 3: Run GREEN and commit

​

Task 3: Extend phone-agent scope configuration APIs

• Modify: backend/src/phone/dto/knowledge-sources.dto.ts
• Modify: backend/src/phone/phone.service.ts
• Create: backend/src/phone/phone.knowledge-scope-selection.spec.ts
• Modify: backend/src/phone/phone.controller.ts
• Modify: backend/src/public-api/controllers/phone.public.controller.ts
• Modify: backend/src/public-api/controllers/phone.public.controller.spec.ts
• Modify (generated): backend/tmp/public-openapi.json
• Modify (generated): backend/mcp-server/src/schema.ts
• Modify: backend/mcp-server/src/tools/phone.ts
• Modify: backend/mcp-server/src/tools/phone.spec.ts

• Extends update input with optional knowledgeItemIds/knowledgeFolderKeys; omission leaves knowledge rows unchanged for older clients.
• Adds instruction and knowledge modes plus explicit IDs/folder summaries to KnowledgeSourceTreeDto while retaining existing instruction fields.
• Adds paginated knowledge-item listing by canonical folder key.
• Changes PhoneService.updateAgentKnowledgeSources to one object input and one transaction.
• Step 1: Write RED service/controller tests

• Step 2: Implement transactional DTO/service/controller behavior

• Step 3: Run GREEN

• Step 4: Regenerate public types and update MCP

• Step 5: Commit

​

Task 4: Replace bootstrap preloading with scope snapshots

• Modify: backend/src/voice-channel/voice-agent-routing.service.ts
• Modify: backend/src/voice-channel/voice-agent-routing.service.spec.ts
• Modify: backend/src/voice-runtime/dtos/bootstrap.dto.ts
• Modify: backend/src/voice-runtime/dtos/events.dto.ts
• Modify: backend/src/voice-channel/voice-call-session.service.ts
• Modify: backend/src/chat-session/dtos/chat-session.dto.ts
• Modify: backend/src/voice-runtime/services/voice-bootstrap.service.ts
• Modify: backend/src/voice-runtime/__tests__/voice-bootstrap.e2e.spec.ts

• Produces VoiceAgentRoutingService.getKnowledgeScope({ agentId, contactId }).
• Snapshot: { instruction_scope: { mode, instruction_ids, directory_ids }, knowledge_scope: { mode, item_ids, folder_keys }, captured_at }.
• Bootstrap excludes selected content while explicit dynamic instructions remain appended.
• Step 1: Write RED routing/bootstrap tests

expect(response.instructions).not.toContain(INSTRUCTION_SENTINEL);
expect(response.knowledge.snapshot?.instruction_scope).toEqual({
  mode: 'selected', instruction_ids: [instructionId], directory_ids: [],
});
expect(response.knowledge.snapshot?.knowledge_scope.mode).toBe('all');

• Step 2: Implement no-preload scope resolution

• Step 3: Run GREEN and commit

​

Task 5: Build scoped, ranked backend retrieval

• Modify: backend/src/rag/knowledgebase/knowledgebase.ts
• Create: backend/src/rag/knowledgebase/knowledgebase.allowlist.spec.ts
• Create: backend/src/voice-runtime/services/voice-knowledge-search.service.ts
• Create: backend/src/voice-runtime/services/voice-knowledge-search.service.spec.ts

• Extends KnowledgebaseService.search with strict sourceRecordIds, allowedItemIds, and allowedFolderKeys; undefined is unrestricted and [] returns no results.
• Produces VoiceKnowledgeSearchService.search({ orgId, agentId, contactId, query }).
• Results are { type, id, chunkIndex, title, content, sourceUrl }, ranked together by distance and capped at five.
• Step 1: Write RED access-filter tests

• Step 2: Implement SQL predicates before ANN limiting

• Step 3: Write RED service tests

• Step 4: Implement one-embedding concurrent retrieval

• Step 5: Run GREEN and commit

​

Task 6: Expose the internal voice search endpoint

• Create: backend/src/voice-runtime/dtos/knowledge-search.dto.ts
• Modify: backend/src/voice-runtime/voice-call-ops.controller.ts
• Create: backend/src/voice-runtime/__tests__/voice-knowledge-search.e2e.spec.ts
• Modify: backend/src/voice-runtime/contract-version.ts
• Modify: backend/voice-agent/src/__tests__/deploy-workflow.guard.spec.ts
• Modify: .github/workflows/voice-agent-deploy.yml

• Adds voiceSearchKnowledge at POST /internal/voice/v1/sessions/{sessionId}/tools/knowledge-search.
• Request: { orgId, agentId, query }, trimmed to 1–500 characters.
• Response status: ok | no_match | restricted_empty, plus both modes and typed results.
• Step 1: Write RED real-HTTP tests

• Step 2: Implement guarded route and deadline

• Step 3: Bump/pin contract and run GREEN

• Step 4: Commit

​

Task 7: Register the isolated worker search tool

• Modify (generated): backend/tmp/voice-openapi.json
• Modify (generated): backend/voice-agent/src/api/schema.ts
• Modify: backend/voice-agent/src/api/voice-backend-api.ts
• Modify: backend/voice-agent/src/api/voice-backend-api.spec.ts
• Create: backend/voice-agent/src/tools/knowledge.tools.ts
• Create: backend/voice-agent/src/tools/knowledge.tools.spec.ts
• Modify: backend/voice-agent/src/voice-agent-dynamic-imports.ts
• Modify: backend/voice-agent/src/voice-agent-dynamic-imports.spec.ts
• Modify: backend/voice-agent/src/index.ts
• Modify: backend/voice-agent/src/testing.ts

• Produces VoiceBackendApi.searchKnowledge with a four-second client deadline.
• Produces getKnowledgeTools({ orgId, agentId, sessionId }) and search_knowledge.
• Tool preserves exact IDs; corpus miss and unavailability have distinct honest-answer guidance.
• Step 1: Write RED API/tool tests

• Step 2: Regenerate and implement

• Step 3: Run GREEN, isolation, type, and build checks

• Step 4: Commit

​

Task 8: Build the two-folder dashboard selector

• Modify: dashboard/apps/dashboard/app/(authenticated)/(dashboard)/(channels)/channels/phone/_components/KnowledgeSourcesSelector/selection.utils.ts
• Modify: dashboard/apps/dashboard/app/(authenticated)/(dashboard)/(channels)/channels/phone/_components/KnowledgeSourcesSelector/selection.utils.test.ts
• Modify: dashboard/apps/dashboard/app/(authenticated)/(dashboard)/(channels)/channels/phone/_components/KnowledgeSourcesSelector/index.tsx
• Create: dashboard/apps/dashboard/app/(authenticated)/(dashboard)/(channels)/channels/phone/_components/KnowledgeSourcesSelector/index.test.tsx
• Modify: dashboard/apps/dashboard/app/(authenticated)/(dashboard)/(channels)/channels/phone/_components/ModifyAIPhoneAgent/ModifyAIPhoneAgent__Form.tsx
• Modify (generated): dashboard/packages/sdk/src/schema.ts

• Selection utilities track instruction IDs/directories separately from knowledge item IDs/folder keys.
• Component ref remains save, hasChanges, fetchTree.
• Roots expose All searchable or Restricted · N selected as visible text.
• Step 1: Write RED utility tests

• Step 2: Implement pure state utilities and run GREEN

• Step 3: Write RED component tests

• Step 4: Regenerate SDK and implement the component

• Step 5: Run GREEN, typecheck, lint, and commit

​

Task 9: Port and expand production-grounded evals

• Create: backend/src/agent-evals/benches/foodics-voice-knowledge.bench.spec.ts
• Modify: backend/src/agent-evals/benches/foodics-voice.bench.spec.ts
• Modify: backend/src/agent-evals/gate-runner-config.ts
• Modify: backend/src/agent-evals/gate-runner-config.spec.ts
• Create: backend/src/agent-evals/research/foodics-voice-knowledge-search.md
• Modify: backend/src/voice-e2e/provider-roundtrip.e2e.spec.ts
• Modify: backend/scripts/voice-smoke/provider-roundtrip-helpers.ts

• FoodicsKnowledgeCall.start uses RealBackendTestServer, VoiceBackendApi.bootstrap, and getKnowledgeTools.
• Artifacts include scope snapshot, tool input/output, exact IDs, latency, and priced usage.
• Both voice gate targets include moneygram-voice and foodics-voice-knowledge.
• Step 1: Write/run RED gate-config test

• Step 2: Port production-grounded cases at K=1

• Step 3: Add K=1 gap cases

• Step 4: Add deterministic no-preload and latency contracts

• Step 5: Run K=1 and repair only evidence-backed failures

• Step 6: Add opt-in audio knowledge roundtrip

• Step 7: Run both voice targets at K=10 and commit

​

Task 10: Verify, review, repair, and open the draft PR

• Review every file changed from base 5f10cfcf674eca5e771be8b6c2663397e938cdc2.
• Modify only files required by failing verification or concrete review findings.

• Pushes m-tabaza/feature/voice-knowledge-search-v2.
• Opens a draft PR based on m-tabaza/feat/voice-agent-network-isolation until #2260 merges.
• Step 1: Run focused verification

• Step 2: Run mandatory full voice verification

• Step 3: Run formatting/lint/diff checks

• Step 4: Review for production readiness

• Step 5: Fix each concrete issue through RED/GREEN

• Step 6: Push and open the draft PR