SDK type defs vs actual API — ~37 field-access misses across 6 types (Tenant, Task, MaintenanceSession, …)

[asachs01]

Question: SDK type defs vs actual immybot API — incomplete types, or consumer using nonexistent fields?

While doing CI-health rehab on the consumer repo wyre-technology/immybot-mcp,
tsc --noEmit surfaced ~37 TS2339 errors of one shape: the consumer accesses
fields on 6 of this SDK's types that the type defs do not declare. Filing
here because that question only makes sense in this repo: either the SDK type
defs are incomplete vs the actual immybot API response shape, or the consumer
code is wrong.

We can't answer it from the consumer side — it needs someone with domain
knowledge of the immybot API's actual wire shape.

The framing question (per access site)

For each (SDK type, field) pair below — does the actual immybot API expose
that field on that resource?

• If yes → this SDK's type defs are incomplete; add the field(s) here.
• If no → the consumer (immybot-mcp) is wrong; the consumer fixes it
  there and this SDK is fine.

Both answers are useful — both close the gap.

Pattern A field-access misses, grouped by SDK type

All references are in wyre-technology/immybot-mcp src/domains/*.ts, against
@modelcontextprotocol/sdk ^1.29.0 and this SDK at its current pinned version
in that consumer's lockfile. Errors are present from the initial scaffold —
not a migration artifact.

MaintenanceSession (8 access sites, 6 unique fields)

• priority — used at domains/maintenance_sessions.ts:233,255
• duration — used at domains/maintenance_sessions.ts:234,259
• allowReboot — used at domains/maintenance_sessions.ts:256
• description — used at domains/maintenance_sessions.ts:260
• tasksCompleted — used at domains/maintenance_sessions.ts:262
• tasksFailed — used at domains/maintenance_sessions.ts:263

MaintenanceSessionSummary (3 unique fields)

• successfulSessions — domains/maintenance_sessions.ts:472
• averageDuration — domains/maintenance_sessions.ts:474
• totalTasks — domains/maintenance_sessions.ts:476

ScriptExecutionResult (2 unique fields)

• duration — domains/scripts.ts:355
• error — domains/scripts.ts:358

Task (11 access sites, 5 unique fields)

• duration — domains/tasks.ts:300,330,510
• exitCode — domains/tasks.ts:301
• errorMessage — domains/tasks.ts:303,381
• retryCount — domains/tasks.ts:304,382
• maxRetries — domains/tasks.ts:305

TaskQueueStats (4 unique fields)

• averageQueueTime — domains/tasks.ts:484
• averageExecutionTime — domains/tasks.ts:485
• successRate — domains/tasks.ts:486
• queueDepth — domains/tasks.ts:487

Tenant (9 access sites, 7 unique fields)

• type — domains/tenants.ts:153,173,205
• primaryContact — domains/tenants.ts:154,174
• email — domains/tenants.ts:175
• phone — domains/tenants.ts:176
• address — domains/tenants.ts:177
• website — domains/tenants.ts:179
• lastActivity — domains/tenants.ts:183

Total

37 access-site errors across 6 SDK types, 27 unique (type, field) pairs.

Why this matters now

immybot-mcp's main Release workflow is red at the Lint step (tsc --noEmit) on these 37 (plus ~20 unrelated MCP-SDK content-block narrowings
in test files). Until the Release workflow is green, the broken :latest
image cannot be re-shipped to ghcr.io — so a downstream bug-fix in
immybot-mcp cannot ship to customers until this is resolved one way or the
other. We are tracking immybot-mcp Release as KNOWN-BLOCKED-ON-REFACTOR
linked to this issue as the documented dependency.

(There's also a separate, unrelated MCP-SDK content-block discriminated-union
narrowing pattern in immybot-mcp src/__tests__/*.ts — that's a mechanical
fix in the consumer, not an SDK question. It folds into the consumer
refactor once the answer here lands.)

Asks

1. For each (type, field) pair above, indicate which path is correct:
   • SDK gap → field should be added to this SDK's type defs.
   • Consumer wrong → immybot-mcp should drop / rename the access.
2. If a field exists on the wire but under a different name in the API,
   noting the canonical name is enough — the consumer can map.

Surfaced as part of the *-mcp Release-backlog rehab; consumer-side work is
parked KNOWN-BLOCKED-ON-REFACTOR until this resolves.