konstruct/.planning/phases/10-agent-capabilities/10-02-SUMMARY.md

phase, plan, subsystem, tags, dependency_graph, tech_stack, key_files, decisions, metrics

phase	plan	subsystem	tags	dependency_graph	tech_stack	key_files	decisions	metrics
10-agent-capabilities	02	agent-capabilities	calendar oauth google tools cap-05 cap-06	requires provides affects 10-01 CAP-05 CAP-06 orchestrator gateway shared-api	added patterns google-auth google-api-python-client per-tenant-oauth token-refresh-writeback natural-language-tool-results	created modified packages/shared/shared/api/calendar_auth.py tests/unit/test_calendar_auth.py tests/unit/test_calendar_lookup.py migrations/versions/013_google_calendar_channel.py packages/orchestrator/orchestrator/tools/builtins/calendar_lookup.py packages/orchestrator/orchestrator/tools/registry.py packages/orchestrator/orchestrator/agents/builder.py packages/shared/shared/api/__init__.py packages/gateway/gateway/main.py	calendar_lookup receives _session param for test injection — production obtains session from async_session_factory Token write-back is non-fatal: refresh failure logged but API result still returned requires_confirmation=False for calendar CRUD — user intent (asking agent to book) is the confirmation build() imported at module level for patchability in tests (try/except ImportError handles missing dep) Tool result formatting instruction added to build_system_prompt when agent has tool_assignments (CAP-06)	duration completed tasks files ~10m 2026-03-26 2 9

Phase 10 Plan 02: Google Calendar OAuth and Calendar Tool CRUD Summary

Per-tenant Google Calendar OAuth install/callback with encrypted token storage, full CRUD calendar tool replacing the service account stub, and natural language tool result formatting (CAP-05, CAP-06).

Tasks Completed

Task 1: Google Calendar OAuth endpoints and calendar tool replacement (TDD)

Files created/modified:

• packages/shared/shared/api/calendar_auth.py — OAuth install/callback/status endpoints
• packages/orchestrator/orchestrator/tools/builtins/calendar_lookup.py — Per-tenant OAuth calendar tool
• migrations/versions/013_google_calendar_channel.py — Add google_calendar to CHECK constraint
• tests/unit/test_calendar_auth.py — 6 tests for OAuth endpoints
• tests/unit/test_calendar_lookup.py — 10 tests for calendar tool

Commit: 08572fc

What was built:

• calendar_auth_router at /api/portal/calendar with 3 endpoints:
  • GET /install?tenant_id= — generates HMAC-signed state, returns Google OAuth URL with offline/consent
  • GET /callback?code=&state= — verifies HMAC state, exchanges code for tokens, upserts ChannelConnection
  • GET /{tenant_id}/status — returns {"connected": bool}
• calendar_lookup.py fully replaced — no more GOOGLE_SERVICE_ACCOUNT_KEY dependency:
  • action="list" — fetches events for date, formats as - HH:MM: Event title
  • action="check_availability" — lists busy slots or "entire day is free"
  • action="create" — creates event with summary/start/end, returns confirmation
  • Token auto-refresh: google-auth refreshes expired access tokens, updated token written back to DB
  • Returns informative messages for missing tenant_id, no connection, and errors

Task 2: Mount new API routers and update tool schema + prompt builder

Files modified:

• packages/shared/shared/api/__init__.py — export kb_router and calendar_auth_router
• packages/gateway/gateway/main.py — mount kb_router and calendar_auth_router
• packages/orchestrator/orchestrator/tools/registry.py — updated calendar_lookup schema with CRUD params
• packages/orchestrator/orchestrator/agents/builder.py — add tool result formatting instruction (CAP-06)

Commit: a64634f

What was done:

• KB and Calendar Auth routers mounted on gateway under Phase 10 section
• calendar_lookup schema updated: action (enum), event_summary, event_start, event_end added
• required updated to ["date", "action"]
• build_system_prompt() now appends "Never show raw data or JSON to user" when agent has tool_assignments
• Confirmed CAP-04 (http_request): in registry, works, no changes needed
• Confirmed CAP-07 (audit logging): executor.py calls audit_logger.log_tool_call() on every tool invocation

Deviations from Plan

Auto-fixed Issues

1. [Rule 2 - Missing functionality] Module-level imports for patchability

• Found during: Task 1 TDD GREEN phase
• Issue: KeyEncryptionService and googleapiclient.build imported lazily (inside function), making them unpatchable in tests with standard patch() calls
• Fix: Added module-level imports with try/except ImportError guard for the google library optional dep; settings and KeyEncryptionService imported at module level
• Files modified: packages/orchestrator/orchestrator/tools/builtins/calendar_lookup.py
• Commit: 08572fc

2. [Rule 1 - Bug] Test patched non-existent module attribute

• Found during: Task 1 TDD GREEN phase
• Issue: Tests patched get_async_session and KeyEncryptionService before those names existed at module level; tests also needed settings patched to bypass platform_encryption_key check
• Fix: Updated tests to pass _session directly (no need to patch get_async_session), extracted _make_mock_settings() helper, added patch(_PATCH_SETTINGS) to all action tests
• Files modified: tests/unit/test_calendar_lookup.py
• Commit: 08572fc

3. [Already done] google_client_id/secret in Settings and GOOGLE_CALENDAR in ChannelTypeEnum

• These were already committed in plan 10-01 — no action needed for this plan

Requirements Satisfied

• CAP-05: Calendar availability checking and event creation — per-tenant OAuth, list/check_availability/create actions
• CAP-06: Natural language tool results — formatting instruction added to system prompt; calendar_lookup returns human-readable strings, not raw JSON

Self-Check: PASSED

All files verified:

• FOUND: packages/shared/shared/api/calendar_auth.py
• FOUND: packages/orchestrator/orchestrator/tools/builtins/calendar_lookup.py
• FOUND: migrations/versions/013_google_calendar_channel.py
• FOUND: tests/unit/test_calendar_auth.py
• FOUND: tests/unit/test_calendar_lookup.py
• FOUND: commit 08572fc (Task 1)
• FOUND: commit a64634f (Task 2)