fix(sdk): TypeScript SDK request/response parity + missing /api prefix (#15528, #16495)

[mrveiss]

Thinking Path

The Python SDK's request/response shapes were already fixed against the real
routes; the TypeScript package still sent the old, wrong ones (#15528 lists
sessions.list's positional limit/offset, knowledge.search's GET+query-
params call, analytics.usage/performance's ignored period argument, and
several invented response fields, among others). Fixing the request shapes
required rewriting types.ts against the real backend models rather than the
SDK's own prior (wrong) assumptions, since the two had diverged together.

While tracing every resource method against the real routes, agents.ts's
getConfig/updateConfig turned out to call a bare /agent/config with no
agent id at all -- confirmed against autobot-backend/api/agent_config.py's
actual route table that per-agent config lives under
/agent_config/agents/{agent_id}/..., and that no PUT route exists for
updateConfig on either mount. updateConfig is removed; setModel/
setEnabled are added to reach parity with the Python SDK's already-correct
surface.

Also discovered mid-work: every TypeScript SDK request was missing the /api
prefix entirely, so no request built by this package could reach a real
backend regardless of path or body correctness. This is the same defect
#15053 already found and fixed once in the Python package, filed here as its
own issue (#16495) for traceability and fixed in this PR since shipping
#15528 without it would leave the SDK still fully non-functional.

This checker cannot execute TypeScript, so verification is a new static-
analysis guard (repo_tests/sdk_ts_request_contract_test.py) rather than a
runtime test: it text-scans each resource method's source for its HTTP verb,
path template and sent field names, and checks both that the source matches
its own pinned table and that the table matches the real backend route
table -- reusing the same route_query_params/route_request_bodies
oracle fixtures the existing Python SDK guards already use, so there is only
one source of truth for what the backend actually accepts.

What Changed

• libs/autobot-sdk-ts/src/client.ts — added API_PREFIX/apiPath(),
  mirroring the Python SDK's api_path(); buildUrl() now applies it (bug(sdk): every TypeScript SDK request omits the /api prefix — 404 against a real backend #16495).
• libs/autobot-sdk-ts/src/types.ts — rewritten to match the backend's real
  response shapes for sessions, chat messages, agent health/config, knowledge
  entries/stats/search, and analytics usage/performance.
• libs/autobot-sdk-ts/src/resources/sessions.ts — list(scope?, teamId?),
  get(sessionId, page?, perPage?).
• libs/autobot-sdk-ts/src/resources/knowledge.ts — search() is now a POST
  with a JSON body; getEntries() is cursor-paginated, not offset-paginated.
• libs/autobot-sdk-ts/src/resources/analytics.ts — usage()/performance()
  take no arguments and hit the routes' real paths.
• libs/autobot-sdk-ts/src/resources/agents.ts — health()'s path gained its
  missing /agent segment; getConfig(agentId) now targets the per-agent
  route; updateConfig() removed (no backend route); setModel/setEnabled
  added.
• libs/autobot-sdk-ts/src/index.ts — export list extended with the new
  nested types.
• libs/autobot-sdk-ts/tests/live/backend.test.ts — updated one call site for
  sessions.list()'s new signature.
• repo_tests/sdk_ts_request_contract_test.py (new) — static contract guard
  for the TS SDK, pinned against the same backend-derived oracle the Python
  SDK guards use.
• docs/sdk/README.md — feature-coverage table and defect notes brought
  current.
• changelog/unreleased/15528-sdk-ts-parity.md (new).

Verification

• repo_tests/sdk_ts_request_contract_test.py: ran via the repo's pre-push
  hook (this checker does not execute product code directly) — passed.
• black, isort, flake8 --max-line-length=120, ruff check, and
  python3 -c "import ast; ast.parse(...)" all pass clean on the new guard
  file.
• Every .ts change was manually traced against the actual backend route
  decorators (autobot-backend/api/agent_config.py,
  autobot-backend/api/knowledge*.py, autobot-backend/api/analytics.py,
  autobot-backend/api/chat_sessions.py) rather than executed, since this
  checker has no TypeScript runtime available.
• Pre-commit (black/isort/flake8/hardcoded-values/detect-secrets/etc.) is
  green on the full diff.

Closes #15528
Closes #16495

Model Used

Claude Sonnet 5

🤖 Generated with Claude Code

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: f6973860-315a-493c-a0a4-d7b281f831c4

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Notice: 29 open PRs — past the runaway threshold (25)

There is no PR queue limit, and this is not a request to defer this PR. Work proceeds one issue at a time without a cap on open PRs; review capacity is the constraint.

This notice only means the count is high enough to be worth a glance for a runaway — something opening PRs in a loop, or a merge pipeline that has stalled so nothing is draining.

Currently open:

• security(routers): gate knowledge_search, knowledge_search_aggregator, knowledge_suggestions and voice_stream (#16507) #16508 security(routers): gate knowledge_search, knowledge_search_aggregator, knowledge_suggestions and voice_stream (security(routers): gate knowledge_search, knowledge_search_aggregator, knowledge_suggestions and voice_stream #16507)
• test(user-management): a user in org A gets no results from org B (#16279) #16506 test(user-management): a user in org A gets no results from org B (security(users): /user-management/users/search answers anonymous callers with names from every organisation #16279)
• security(settings): record the real caller, not the literal "admin" (#16501) #16504 security(settings): record the real caller, not the literal "admin" (security(settings): sync_config and update_hardware_priority record the literal "admin" instead of the real caller #16501)
• fix(chat-knowledge): contexts can be deleted, cascade with their chat, and orphans get cleaned (#16490) #16503 fix(chat-knowledge): contexts can be deleted, cascade with their chat, and orphans get cleaned (bug(chat-knowledge): contexts can be created but never deleted, so orphans accumulate #16490)
• fix(slm-frontend): give the service-log fetch one path and its real timeout (#16256) #16500 fix(slm-frontend): give the service-log fetch one path and its real timeout (tech-debt(slm-frontend): the two log viewers fetch the same journal through two paths with different timeouts #16256)
• fix(a2a): cooperative cancellation checkpoints in execute_a2a_task (#16174) #16498 fix(a2a): cooperative cancellation checkpoints in execute_a2a_task (Cancelling an A2A task does not stop its executor, so claims can only lapse rather than release #16174)
• refactor(agents): extract NPUCodeSearchAgent's pattern helpers, add declared_scopes (#16173) #16496 refactor(agents): extract NPUCodeSearchAgent's pattern helpers, add declared_scopes (NPUCodeSearchAgent cannot declare its write scopes: its file is at the size ceiling #16173)
• fix(frontend): converge the permission vocabulary onto the backend's real Permission enum, wire in v-permission (#16243) #16493 fix(frontend): converge the permission vocabulary onto the backend's real Permission enum, wire in v-permission (tech-debt(frontend): usePermissions' permission strings share nothing with the backend's Permission vocabulary #16243)
• security(research): treat fetched repos and pages as untrusted data (#16488) #16492 security(research): treat fetched repos and pages as untrusted data (security(research): treat fetched repos and pages as untrusted data: prompt-injection hardening for research, adopt and web-fetch #16488)
• feat(frontend): wire router meta.minRole into a real guard, ranked against the backend's role order (#16244) #16489 feat(frontend): wire router meta.minRole into a real guard, ranked against the backend's role order (tech-debt(frontend): router meta.minRole is declared and read by no guard #16244)
• chore(git): rename Dev_new_gui to main and main to release across the repo (#16479) #16487 chore(git): rename Dev_new_gui to main and main to release across the repo (infra(git): swap branch names across the repo for the rename (in-repo half of #16461) #16479)
• feat(secrets): wire in SecretAuditLog, consolidate SecretVault into SecretsManager (#16485) #16486 feat(secrets): wire in SecretAuditLog, consolidate SecretVault into SecretsManager (wire in SecretAuditLog, consolidate SecretVault into SecretsManager #16485)
• fix(frontend): retire four dead settings API paths, stop a fifth calling admin-gated settings from non-admin surfaces (#16481) #16484 fix(frontend): retire four dead settings API paths, stop a fifth calling admin-gated settings from non-admin surfaces (retire useSettingsApi/SystemRepository/services-api.ts/CacheService.ts dead settings paths #16481)
• feat(llm): cross-worker quota headroom store, persist real 429 headroom #16483 feat(llm): cross-worker quota headroom store, persist real 429 headroom
• chore(activity-tracking): retire the terminal/file/browser tracking hooks as dead code (#16466) #16475 chore(activity-tracking): retire the terminal/file/browser tracking hooks as dead code (chore(activity-tracking): wire in or retire terminal/file/browser activity tracking + secret_usage audit (backend) #16466)
• chore(deps): bump the npm_and_yarn group across 4 directories with 2 updates #16474 chore(deps): bump the npm_and_yarn group across 4 directories with 2 updates
• feat(collaboration): surface pending invitations in the collaboration panel (#16470) #16472 feat(collaboration): surface pending invitations in the collaboration panel (impl gap: surface pending collaboration invitations in a UI #16470)
• feat(collaboration): persist activity/notification history, add invitation list+respond endpoints (#16460) #16471 feat(collaboration): persist activity/notification history, add invitation list+respond endpoints (feat(collaboration): persist activity/notification history and add invitation list+respond endpoints #16460)
• security(settings): record the real caller on /sync and /hardware-priority, and test the anonymous and cross-org refusals (#16278) #16469 security(settings): record the real caller on /sync and /hardware-priority, and test the anonymous and cross-org refusals (security(settings): the core /api/settings routes read and write system config with no authentication #16278)
• fix(migrations): port 6 orphaned tables into the canonical Alembic chain (#16464) #16467 fix(migrations): port 6 orphaned tables into the canonical Alembic chain (fix(migrations): 6 tables in the orphaned database/migrations/ chain were never applied to the live Alembic chain #16464)
• feat(collaboration): wire the collaboration UI onto the real backend (#16443) #16462 feat(collaboration): wire the collaboration UI onto the real backend (impl gap: wire in the real-time collaborative-session UI (#608 phases 5-7 / #874) — 6 components + useSessionCollaboration, zero callers #16443)
• feat(mcp): admin-configured external MCP server bridge #16458 feat(mcp): admin-configured external MCP server bridge
• security(collaboration): authenticate and authorize the session-presence WebSocket (#16455) #16456 security(collaboration): authenticate and authorize the session-presence WebSocket (security(collaboration): WS /ws/sessions/{id}/presence trusts an unauthenticated client-supplied user_id #16455)
• fix(mcp): rename autobot-backend/mcp/ off the name it shadows (#16449) #16454 fix(mcp): rename autobot-backend/mcp/ off the name it shadows (chore(mcp): autobot-backend/mcp/ shadows the real mcp PyPI SDK, making it unreachable by name #16449)
• docs(adr): supersede ADR-001's fixed VM count with role-separation placement (#15194) #16452 docs(adr): supersede ADR-001's fixed VM count with role-separation placement (docs: a fixed 6-VM topology is documented as the architecture — AutoBot scales from one VM or Docker to whatever is needed, and ADR-001 enshrines the wrong invariant #15194)
• fix(tooling): scope protect-files.sh's secrets/ rule to real credential storage (#16446) #16448 fix(tooling): scope protect-files.sh's secrets/ rule to real credential storage (fix(tooling): protect-files.sh's secrets/ rule blocks legitimate frontend source, zero real targets #16446)
• docs: describe role-based placement instead of a fixed VM count (#15194) #16445 docs: describe role-based placement instead of a fixed VM count (docs: a fixed 6-VM topology is documented as the architecture — AutoBot scales from one VM or Docker to whatever is needed, and ADR-001 enshrines the wrong invariant #15194)
• feat(secrets): bridge connector credential templates to ConnectorCredentialStore (#16428) #16444 feat(secrets): bridge connector credential templates to ConnectorCredentialStore (secrets: connector credential templates must write where knowledge connectors read #16428)
• security(secrets): admin-gate infrastructure hosts, fix vault-backed template names (#16426, #16427) #16442 security(secrets): admin-gate infrastructure hosts, fix vault-backed template names (security(secrets): any logged-in user can list and delete infrastructure hosts through /api/infrastructure/hosts #16426, bug(secrets): the OpenAI and Anthropic quick-add templates save names the vault mirror never recognizes, so the key never reaches the runtime #16427)

If the queue is draining normally, ignore this. Otherwise:

1. Check whether CI is dispatching at all — see the ci-dispatch-watchdog status on these PRs
2. Merge the ones whose CI has finished and review has passed: gh pr merge <number> --squash --delete-branch
3. Look for a loop opening near-identical PRs

Warn-only runaway detector — .github/workflows/pr-queue-gate.yml. It never blocks a merge.

[github-actions]

✅ SSOT Configuration Compliance: Passing

🎉 No new hardcoded values of either class — ssot and other both block.

Known backlog in pipeline-scripts/hardcoded_values_baseline.txt is suppressed and tracked in #14371.

[mrveiss]

Independent review: changes requested.

Severity	Where	Evidence	Fix
HIGH	repo_tests/sdk_ts_request_contract_test.py / libs/autobot-sdk-ts/src/client.ts	#16495's AC2 says: "A guard test proves it (mock fetch, assert the actual request URL carries /api/...)." The new guard is a text scan of each method's relative path literal. It never reads client.ts and never exercises apiPath(), API_PREFIX or buildUrl(), and no test mocks fetch. Nothing proves the prefix reaches the wire, yet the PR closes #16495	Add a Jest test in libs/autobot-sdk-ts/tests/ that mocks global.fetch, calls a resource method, and asserts the captured URL starts with /api. Or, if the guard stays static, parse client.ts and assert every call routes through apiPath()
MEDIUM	test_the_table_covers_every_resource_file_that_exists	It reads with Path.glob rather than tools.lint._scan_helpers.tracked_paths. It also asserts pinned <= on_disk, which only checks that named files exist, so a new resource file with unpinned methods passes. Together with the hardcoded 4-file parametrize list, the guard can't catch the drift it's named for	Enumerate with tracked_paths(repo_root(), "libs/autobot-sdk-ts/src/resources/*.ts"), and assert that the files on disk are a subset of the pinned ones, or equal to them

Verified correct:

• Every sessions, knowledge, analytics and agents mapping matches its backend route and Pydantic schema.
• updateConfig is correctly removed: no PUT route exists.
• The setModel/setEnabled bodies match AgentModelUpdate and enable/disable.
• The README's known-defects note is correctly removed.

Non-blocking:

• The changelog fragment doesn't mention the removed agents.updateConfig or getConfig's new required agentId, which are the most visible breaking changes.
• The oracle check ignores the route's media type, which the Python sibling asserts.
• knowledge.search drops category, claiming the route has none, but SearchRequest.category exists. That mirrors the same wrong claim in the Python SDK, and is filed separately against both.

[mrveiss]

Both blocking items addressed, pushed at abed6aa:

• HIGH: added libs/autobot-sdk-ts/tests/apiPrefix.test.ts — mocks global.fetch, calls one method per resource (sessions/knowledge/agents/analytics) plus setEnabled's runtime-chosen trailing segment, and asserts the captured URL starts with /api. One more case proves apiPath() doesn't double-prefix a path that already carries it.
• MEDIUM: test_the_table_covers_every_resource_file_that_exists and the completeness test's parametrize list now both derive from tools.lint._scan_helpers.tracked_paths, not Path.glob or a hardcoded 4-file list. The coverage assertion is now on_disk == pinned (was pinned <= on_disk), so an unpinned new resource file fails instead of passing silently.

Also added a media-type assertion next to the existing field-name check (every POST/PUT row now asserts the route publishes application/json, the same defect class #15527 fixed) — flagged non-blocking but small enough to fold in here. Changelog fragment now names getConfig's new required agentId and the removed updateConfig. Left the category gap alone since #16543 already tracks it for both SDKs.

Re-ran the guard via the pre-push hook (this checker has no Node runtime, so the new Jest file couldn't be exercised locally the same way -- it's real for the first time in CI): pytest: all relevant tests pass.

[mrveiss]

Delta 6a9f103d8..abed6aa4d: verified, approved.

• tests/apiPrefix.test.ts mocks global.fetch and asserts the captured URL matches /^\/api\//. It covers one method per resource, both verbs, the dynamic ${agentId} segment in setEnabled, and apiPath() idempotence. Traced through get/post → buildUrl() → apiPath(): if apiPath() stopped prefixing, every case fails. Jest's testMatch collects the file.
• The guard now enumerates with tracked_paths, and on_disk == pinned drives the parametrize list. No hardcoded list or .glob remains.
• The media-type assertion matches the Python sibling's semantics against the same OpenAPI oracle.
• The changelog names the breaking changes.
• bug(sdk): the TypeScript SDK still sends the parameters and parses the envelopes the Python SDK stopped sending #15528's and bug(sdk): every TypeScript SDK request omits the /api prefix — 404 against a real backend #16495's ACs are all delivered. Closing refs are [15528, 16495]; bug(sdk): the TypeScript SDK still sends the parameters and parses the envelopes the Python SDK stopped sending #15528 is also linked through its branch.
  It merges on a settled green after chore(git): rename Dev_new_gui to main and main to release across the repo (#16479) #16487.

[mrveiss]

Two red-CI issues found and fixed at 406c76d:

• NPM Package Tests: apiPrefix.test.ts failed everywhere with ReferenceError: jest is not defined. This package's jest config uses the ESM preset (ts-jest/presets/default-esm + --experimental-vm-modules); under that preset describe/test/expect are ambient globals but the jest mock-utility object is not — it needs an explicit import { jest } from "@jest/globals", which no prior file in this package needed since none used jest.fn() before. Fixed, and retyped the mock as ReturnType<typeof jest.fn> instead of the CJS-only jest.Mock.
• python-suite shard 8/12: glob_declared_reads_15900_test.py failed because the new tracked_paths(_REPO, "libs/autobot-sdk-ts/src/resources/*.ts") call in the guard is a glob into a tree the python path-filter doesn't cover, and guard(ci): the filter-coverage checker ignores glob-declared reads, so its green over-claims #15900's guard requires that be recorded rather than silently invisible. Added the entry to GLOB_DECLARED_UNCOVERED.

Re-ran both via the pre-push hook where possible (the glob-coverage one for real; the Jest fix can't run locally here, no Node runtime — CI is its first real execution).

[mrveiss]

Delta abed6aa4d..406c76d08: verified, still approved. Two files, +12/−1:

• apiPrefix.test.ts imports jest from @jest/globals. Under this package's ESM preset (ts-jest/presets/default-esm), jest isn't an ambient global the way describe, test and expect are, which was the real cause of the red.
• The new libs/autobot-sdk-ts/src/resources/*.ts glob is registered in GLOB_DECLARED_UNCOVERED with its reader and reason, as guard(ci): the filter-coverage checker ignores glob-declared reads, so its green over-claims #15900's guard requires.
  No assertion changed. It merges on a settled green of this head after chore(git): rename Dev_new_gui to main and main to release across the repo (#16479) #16487.

[mrveiss]

Follow-up fix at c60eb2d: the ESM-globals fix cleared the ReferenceError, but then NPM Package Tests failed to compile -- TS2345, because jest.fn() called with no type argument infers Mock<never>, so mockResolvedValue(...) rejected the real response object. Spelled out the call signature explicitly (jest.fn<(...args: unknown[]) => Promise<FakeFetchResponse>>(impl)) and passed the implementation alongside it instead of chaining mockResolvedValue separately, so there's one generic instantiation to satisfy instead of an inferred one meeting a separate call.

[mrveiss]

Delta 406c76d08..c60eb2d50: still approved. Across the net diffs against main, the only file whose change differs is libs/autobot-sdk-ts/tests/apiPrefix.test.ts. There, c60eb2d50 gives the fetch mock an explicit jest.fn<(...args: unknown[]) => Promise<FakeFetchResponse>> signature, with the implementation passed inline. The earlier bare jest.fn() inferred Mock<never>, which is why it failed with TS2345. This is a test-typing change only; the SDK sources are identical to what I approved. cc3514448 in the range is main's commit, brought in by a merge. I did not re-check CI here.