Purpose

Second-opinion brief for a research agent. All route and URL claims below are backed by repository grep/read, not inference. Use this to validate architecture, security, and implementation options for the Vitto VS Code extension native Chat tab and any future agent-session API.

MCP / session context

• Preflight was run for session 265 with subSession 2, then subSession 3 after log_decision (investigation).
• Manifest: sessions/manifests/S265.json (verify current subSessions if continuing work).

Verification methodology (reproducible)

1. Search for the HTTP path string the extension uses
   Pattern: engine/agent-session
   Scope: entire gspace1 repo, *.ts
   Result: Matches appear only in
   apps/vitto-vscode-extension/src/services/agent-session.service.ts (two fetch URLs).
   No match in APIs/backend-vitto-api/**/*.ts for that path as a route decorator or string literal.

2. Search for agent-session in backend-vitto-api
   Result: Occurrences are imports / class name AgentSessionService, Mongo schema agent-session.schema, collection name agent-sessions — not an Express/Nest route segment agent-session.

3. Enumerate POST routes on the main engine controller
   File: APIs/backend-vitto-api/src/app/engine/vitto.controller.ts
   Result: Includes @Post('message'), @Post('media/upload'), @Post('chat'), many others — no @Post('agent-session') and no @Post('...agent-session...') in the grep output for that file.

4. Confirm global API prefix
   File: APIs/backend-vitto-api/src/main.ts
   Fact: app.setGlobalPrefix('vitto-api')
   Therefore Nest @Controller('engine') + @Post('message') resolves to
   POST /vitto-api/engine/message (not /engine/message at server root).

5. Confirm SPA dev proxy to Vitto backend
   File: libs/libs-foundational/api-config/proxy.conf.js
   Fact: /vitto-api → http://localhost:3003 with no pathRewrite stripping the prefix.
   Fact: There is no proxy entry for bare /engine.

6. Extension base URL for those fetches
   File: apps/vitto-vscode-extension/src/services/config.service.ts
   Fact (dev): vittoUrl in detectEnvironment() is http://localhost:5400 (comment: Vitto AI panel frontend).
   File: apps/vitto-vscode-extension/src/services/agent-session.service.ts
   Fact: const vittoUrl = env.vittoUrl || 'http://localhost:3003';
   then fetch(\${vittoUrl}/engine/agent-session`, ...)`.

7. Angular chat engine (contrast)
   File: libs/libs-foundational/api-config/src/lib/environment-presets.ts
   Fact: VITTO_API_URLS.localDirect = http://localhost:3003/vitto-api
localProxy = /vitto-api
   So browser chat code that uses VITTO_API_URL is aligned with the prefixed API.
   File: libs/libs-ai/vitto-chat/src/lib/services/vitto-chat-engine.service.ts
   Fact: If this.vittoApiUrl is set, sendMessage uses sendMessageViaVitto → POST ${vittoApiUrl}/engine/message (i.e. with prefix when token is .../vitto-api).

Findings (ranked by severity)

F1 — Extension calls a route that does not exist in this repo (Certain)

• Evidence: Grep shows only the extension references .../engine/agent-session. No controller defines that path under APIs/backend-vitto-api.
• Impact: Native Chat tab’s AgentSessionService.chat() will get 404 (or non-SSE error) against a correctly running backend-vitto-api, even if URL/host were fixed.
• Mitigation options (for research to compare):
  • A. Implement POST /vitto-api/engine/agent-session (+ tool-result sub-route) on backend-vitto-api, reusing existing agent loop / AgentSessionService (Mongo) as appropriate.
  • B. Change the extension to call an existing endpoint (e.g. POST /vitto-api/engine/message + SSE stream) and adapt the protocol (today extension expects a specific SSE event shape and tool-result POST).
  • C. Proxy to another service if agent-session was intentionally hosted elsewhere (no evidence in this repo — verify externally if prod works today).

F2 — Wrong URL shape vs Nest global prefix and dev proxy (Certain)

• Backend expects routes under /vitto-api/....
• Extension builds ${vittoUrl}/engine/agent-session — missing vitto-api segment.
• In dev, vittoUrl is typically the Angular dev server (localhost:5400), which only proxies /vitto-api, not /engine.
• Impact: Double failure mode: wrong host role (SPA vs API) and wrong path.

F3 — Comment vs code in agent-session.service.ts (Certain, minor)

• Comment says Vitto API is on port 3003; actual first choice is env.vittoUrl, which in dev is 5400 per config.service.ts. The 3003 fallback is misleading when vittoUrl is always set.

F4 — Angular vitto-chat fallback to backend-ai-api (Certain, contextual)

• When VITTO_API_URL is not injected, sendMessage uses AI_API_URL + /chat (backend-ai-api). That is not the primary Vitto engine path; it is a documented fallback in code comments.
• Separate gap (from prior implementation work): In that fallback branch, files passed to sendMessage are not forwarded to /ai-api/chat — only relevant for deployments without Vitto API.

What is actually fine

• Mongo-backed AgentSessionService in vitto-api is a real, used subsystem for conversation persistence (referenced from vitto-engine.service.ts, channel processing, etc.). The gap is HTTP exposure for the VS Code extension protocol, not the absence of session storage.
• Angular Vitto chat path when VITTO_API_URL is set is consistent with proxy.conf.js and main.ts global prefix (assuming apps provide the token correctly).

Questions for the research agent

1. Product: Is native VS Code Chat intended to ship before a dedicated agent-session HTTP API? If yes, should the extension align to /vitto-api/engine/message only?
2. Security: If attachments stay inline (base64 in JSON), what are max sizes, redaction, and logging policies vs R2 upload (/vitto-api/engine/media/upload) used by Angular?
3. Ops: What is the canonical vittoUrl for the extension in each environment — SPA origin, API origin (3003/vitto-api), or configurable per setting?
4. S258 docs claimed backend work “not in scope” — reconcile with F1 (route missing in repo).

Key file index

Suggested follow-up grep (if repo changes)

rg "agent-session" APIs/backend-vitto-api --glob "*.ts"
rg "@Post\\('agent" APIs/backend-vitto-api --glob "*.ts"
rg "engine/agent-session" apps/vitto-vscode-extension --glob "*.ts"

End of handoff.