feat(sdk): ship TypeScript SDK with deterministic method naming by lan17 · Pull Request #32 · agentcontrol/agent-control

lan17 · 2026-02-17T21:31:58Z

Tested in OpenClaw integration PR: lan17/openclaw#1

Summary

This PR delivers the TypeScript SDK in this repo from scaffold to production-ready client, then layers deterministic client-surface naming improvements on top.

What’s Included

Added and wired sdks/typescript/ package structure, build/test/lint/typecheck flow, and npm publish workflow.
Added Speakeasy generation against committed server/openapi.json with committed generated SDK sources.
Wired AgentControlClient to generated Speakeasy runtime and exposed endpoint namespaces (agents, controls, evaluation, evaluatorConfigs, evaluators, observability, policies, system).
Added client wiring tests (URL/query/body/auth headers and pre-init guard behavior).
Added monorepo TypeScript example app (examples/typescript_sdk) that demonstrates consuming agent-control via npm-compatible setup.

Deterministic Method Naming (follow-up in this PR)

Replaced ad-hoc method overrides with a deterministic rule-generated overlay.
Added generator: sdks/typescript/scripts/generate-method-names-overlay.py.
Updated generation flow so generate-sdk.sh regenerates overlays/method-names.overlay.yaml from OpenAPI before speakeasy overlay apply --strict.
Added semantic exception for clarity:
- PATCH /api/v1/controls/{control_id} -> controls.updateMetadata
- PUT /api/v1/controls/{control_id}/data -> controls.updateData
Updated SDK/docs/tests/examples to the shorter method surface (list, get, create, update*, delete, evaluate, etc.).

Guardrails and CI

Added make sdk-ts-name-check heuristic for verbose fallback names.
Added Python unit tests for naming generator: sdks/typescript/tests/test_generate_method_names_overlay.py.
Added make sdk-ts-overlay-test and wired it into CI.
Tightened generate-check to verify both generated SDK code and overlay drift:
- src/generated
- overlays/method-names.overlay.yaml

Validation

make sdk-ts-overlay-test
make sdk-ts-name-check
make sdk-ts-lint
make sdk-ts-typecheck
make sdk-ts-test
make sdk-ts-build
make sdk-ts-generate-check

Notes

TypeScript SDK package version moved to 0.2.0 due to method-surface changes.
sdk-ts-ci includes naming generator tests and generated/overlay drift checks.

codecov · 2026-02-17T21:53:31Z

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

siddhant-galileo · 2026-02-20T17:15:04Z

should we add an example with typescript sdk ?

lan17 · 2026-02-20T22:36:55Z

should we add an example with typescript sdk ?

done

siddhant-galileo · 2026-02-23T04:38:32Z

LGTM !

just couple of concerns

The controls.ts exports a placeholder right now. So we expect users to imperatively call the evaluate method for now i guess ?
The example does not show how to use it against an agent. It shows how to create and delete a control. I think it would be cool if we can add a similar example to python like customer_support_agent .

lan17 · 2026-02-23T04:42:29Z

LGTM !

just couple of concerns

1. The `controls.ts` exports a placeholder right now. So we expect users to imperatively call the `evaluate` method for now i guess ?

2. The example does not show how to use it against an agent. It shows how to create and delete a control. I think it would be cool if we can add a similar example to python like `customer_support_agent` .

yea, i am delegating @control for later, and thats when I would also make an example that actually uses a real agentic framework.

siddhant-galileo · 2026-02-23T04:51:56Z

🚢

## 1.0.0 (2026-03-04) ### ⚠ BREAKING CHANGES * **server:** Feature/56688 fix image bug (#48) * **sdk:** a bug in docker file (#46) * **server:** Feature/56688 fix docker and create bash (#45) * **evaluators:** Evaluator reorganization with new package structure Package Structure: - agent-control-evaluators (v3.0.0): core + regex, list, json, sql - agent-control-evaluator-galileo (v3.0.0): Luna2 evaluator Key Changes: - Entry points for evaluator discovery (agent_control.evaluators) - Dot notation for external evaluators (galileo.luna2 not galileo/luna2) - Dynamic __version__ via importlib.metadata - Server uses evaluators as runtime dep (no longer vendored) - Release workflow publishes both packages to PyPI Bug Fixes: - JSON evaluator: field_constraints/field_patterns in extra-fields allow-list - SQL evaluator: LIMIT/OFFSET bypass fix Migration: - Import: agent_control_evaluator_galileo.luna2 (not agent_control_evaluators.galileo_luna2) - DB: UPDATE controls SET evaluator.name replace('/', '.') * **server:** add time-series stats and split API endpoints (#6) * **evaluators:** rename plugin to evaluator throughout (#81) * **models:** simplify step model and schema (#70) ### Features * Add plugin auto-discovery via Python entry points ([#49](#49)) ([1521182](1521182)) * **docs:** add GitHub badges and CI coverage reporting ([#90](#90)) ([be1fa14](be1fa14)) * **evaluators:** add required_column_values for multi-tenant SQL validation ([#30](#30)) ([532386c](532386c)) * **sdk-ts:** automate semantic-release for npm publishing ([#52](#52)) ([2b43958](2b43958)) * **sdk:** Add PyPI packaging with semantic release ([#52](#52)) ([7c24f7f](7c24f7f)) * **sdk:** Auto-populate init() steps from [@control](https://github.com/control)() decorators ([#23](#23)) ([dc0f2a4](dc0f2a4)) * **sdk:** export ControlScope, ControlMatch, and EvaluatorResult models ([#18](#18)) ([0d49cad](0d49cad)) * **sdk:** Get Agent Controls from SDK Init ([#15](#15)) ([a485f93](a485f93)) * **sdk:** Refresh controls in a background loop ([#43](#43)) ([03f826d](03f826d)) * **sdk:** ship TypeScript SDK with deterministic method naming ([#32](#32)) ([a76e9b0](a76e9b0)) * **server:** add evaluator config store ([#78](#78)) ([cc14aa6](cc14aa6)) * **server:** add initAgent conflict_mode overwrite mode with SDK defaults ([#40](#40)) ([f3ed2b8](f3ed2b8)) * **server:** Add observability system for control execution tracking ([#44](#44)) ([fd0bddc](fd0bddc)) * **server:** add prometheus metrics for endpoints ([#68](#68)) ([775612c](775612c)) * **server:** add time-series stats and split API endpoints ([#6](#6)) ([a0fa597](a0fa597)) * **server:** hard-cut migrate to remove agent UUID ([#44](#44)) ([ee322c9](ee322c9)) * **server:** Optional Policy and many to many relationships ([#41](#41)) ([1a62746](1a62746)) * **ui:** add sql, luna2, json control forms and restructure the code ([#54](#54)) ([c4c1d4a](c4c1d4a)) * **ui:** allow to delete control ([#39](#39)) ([7dc4ca3](7dc4ca3)) * **ui:** Control Store Flow Updated ([#4](#4)) ([dda9f70](dda9f70)) * **ui:** stats dashboard ([#80](#80)) ([4cbb7fe](4cbb7fe)) * **ui:** Steps dropdown rendered based on api return values ([#36](#36)) ([a2aca43](a2aca43)) * **ui:** tests added and some minor ui changes, added error boundaries ([#61](#61)) ([009852b](009852b)) * **ui:** update agent control icon and favicon ([#42](#42)) ([19af8fa](19af8fa)) ### Bug Fixes * **ci:** Add ui scope to PR title validation ([#59](#59)) ([e0fdb52](e0fdb52)) * **ci:** correct galileo contrib path in release build script ([#51](#51)) ([2de6013](2de6013)) * **ci:** Enable pr title on prs ([#56](#56)) ([3d8b5fe](3d8b5fe)) * **ci:** Fix release ([#11](#11)) ([9dd3dd7](9dd3dd7)) * **ci:** Use galileo-automation bot for releases ([#57](#57)) ([bc8eea0](bc8eea0)) * **docs:** Add Example for Evaluator Extension ([#3](#3)) ([c2a70b3](c2a70b3)) * **docs:** add setup script ([#49](#49)) ([7a212c3](7a212c3)) * **docs:** Clean up Protect ([#76](#76)) ([99c16fd](99c16fd)) * **docs:** Fix Examples for LangGraph ([#64](#64)) ([23b30ae](23b30ae)) * **docs:** Improve documentation for open source release ([#47](#47)) ([9018fb3](9018fb3)) * **docs:** Remove old/unused examples ([#66](#66)) ([f417781](f417781)) * **docs:** Update Contributing Guide ([#8](#8)) ([10b34c8](10b34c8)) * **docs:** Update readme ([#37](#37)) ([7531d83](7531d83)) * **docs:** Update README ([#2](#2)) ([379bb15](379bb15)) * **examples:** Control sets cleanup with signed ([#65](#65)) ([af7b5fb](af7b5fb)) * **examples:** Update crew ai example to use evaluator ([#93](#93)) ([1c65084](1c65084)) * **infra:** Add plugins directory to Dockerfile ([#58](#58)) ([171d459](171d459)) * **infra:** install engine/evaluators in server image ([#14](#14)) ([d5ae157](d5ae157)) * **models:** use StrEnum for error enums ([#12](#12)) ([3f41c9f](3f41c9f)) * **sdk-ts:** add conventional commits preset dependency ([#55](#55)) ([540fe9d](540fe9d)) * **sdk-ts:** export npm token for semantic-release npm auth ([#54](#54)) ([1b6b993](1b6b993)) * **sdk:** 54253 add steer action and example ([#38](#38)) ([bf2380a](bf2380a)) * **sdk:** a bug in docker file ([#46](#46)) ([12d1794](12d1794)) * **sdk:** Add step_name as parameter to control ([#25](#25)) ([19ade9d](19ade9d)) * **sdk:** emit observability events for SDK-evaluated controls and fix non_matches propagation ([#24](#24)) ([6a9da69](6a9da69)) * **sdk:** enforce UUID agent IDs ([#9](#9)) ([5ccdbd0](5ccdbd0)) * **sdk:** Fix logging ([#77](#77)) ([b1f078c](b1f078c)) * **sdk:** plugin to evaluator.. agent_protect to agent_control ([#88](#88)) ([fc9b088](fc9b088)) * **server:** enforce public-safe API error responses ([#20](#20)) ([e50d817](e50d817)) * **server:** Feature/56688 fix docker and create bash ([#45](#45)) ([7277e27](7277e27)) * **server:** Feature/56688 fix image bug ([#48](#48)) ([71e6b44](71e6b44)) * **server:** fix alembic migrations ([#47](#47)) ([c19c17c](c19c17c)) * **server:** reject initAgent UUID/name mismatch ([#13](#13)) ([19d61ff](19d61ff)) * tighten evaluation error handling and preserve control data ([52a1ef8](52a1ef8)) * **ui:** Fix UI and clients for simplified step schema ([#75](#75)) ([be2aaf0](be2aaf0)) * **ui:** json validation ([#10](#10)) ([a0cd5af](a0cd5af)) * **ui:** selector subpaths issue ([#34](#34)) ([79cb776](79cb776)) * **ui:** UI feedback fixes ([#27](#27)) ([6004761](6004761)) ### Code Refactoring * **evaluators:** rename plugin to evaluator throughout ([#81](#81)) ([0134682](0134682)) * **evaluators:** split into builtin + extra packages for PyPI ([#5](#5)) ([0e0a78a](0e0a78a)) * **models:** simplify step model and schema ([#70](#70)) ([4c1d637](4c1d637))

lan17 added 6 commits February 17, 2026 15:56

feat(ts-sdk): scaffold typescript sdk and speakeasy generation workflow

dc461ec

chore(ts-sdk): align speakeasy config and ci install flow

960a524

chore(ts-sdk): add npm publish readiness workflow and runbook

5099f82

fix(ts-sdk): make generated smoke test CI-safe

a4e3406

fix(ts-sdk): stabilize generated smoke test paths

0a06d4b

fix(ts-sdk): commit generated runtime lib sources

e03e3b3

lan17 changed the title ~~Lev/typescriptsdk~~ feat(ts-sdk): scaffold TypeScript SDK and publish workflow Feb 17, 2026

lan17 changed the title ~~feat(ts-sdk): scaffold TypeScript SDK and publish workflow~~ feat(sdk): scaffold TypeScript SDK and publish workflow Feb 17, 2026

fix(ci): provide speakeasy auth and explicit python setup

f0c8514

docs(sdk): add TypeScript SDK usage guide for npm consumers

7347209

lan17 marked this pull request as ready for review February 19, 2026 00:08

lan17 added 2 commits February 18, 2026 20:39

feat(ts-sdk): wire AgentControlClient to generated API client

1a6899d

fix(ts-sdk): normalize generated hooks registration comment

2faba87

lan17 requested a review from siddhant-galileo February 19, 2026 23:07

lan17 added 5 commits February 20, 2026 14:58

feat(examples): add npm-consumer TypeScript SDK quickstart

7b60cb2

fix(sdk-ts): sync control event docs in OpenAPI and generated TS model

79a96ae

feat(ts-sdk): add deterministic speakeasy method naming

5e6b871

refactor(ts-sdk): generate method-name overlay from openapi rules

a49d7a1

test(ts-sdk): add naming-generator tests and overlay drift checks

13e494d

lan17 changed the title ~~feat(sdk): scaffold TypeScript SDK and publish workflow~~ feat(ts-sdk): ship TypeScript SDK with deterministic method naming Feb 20, 2026

lan17 added 3 commits February 20, 2026 17:44

ci(sdk): generate openapi from server code in ts checks

a3efee9

ci(sdk): remove duplicate openapi generation in release flow

3319d50

refactor(openapi): stop tracking generated server spec artifact

9a22e56

lan17 changed the title ~~feat(ts-sdk): ship TypeScript SDK with deterministic method naming~~ feat(sdk): ship TypeScript SDK with deterministic method naming Feb 20, 2026

siddhant-galileo approved these changes Feb 23, 2026

View reviewed changes

lan17 merged commit a76e9b0 into main Feb 23, 2026
6 of 7 checks passed

lan17 deleted the lev/typescriptsdk branch February 23, 2026 05:04

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(sdk): ship TypeScript SDK with deterministic method naming#32

feat(sdk): ship TypeScript SDK with deterministic method naming#32
lan17 merged 18 commits intomainfrom
lev/typescriptsdk

lan17 commented Feb 17, 2026 •

edited

Loading

Uh oh!

codecov bot commented Feb 17, 2026

Uh oh!

siddhant-galileo commented Feb 20, 2026

Uh oh!

lan17 commented Feb 20, 2026

Uh oh!

siddhant-galileo commented Feb 23, 2026

Uh oh!

lan17 commented Feb 23, 2026

Uh oh!

siddhant-galileo commented Feb 23, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

lan17 commented Feb 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What’s Included

Deterministic Method Naming (follow-up in this PR)

Guardrails and CI

Validation

Notes

Uh oh!

codecov bot commented Feb 17, 2026

Codecov Report

Uh oh!

siddhant-galileo commented Feb 20, 2026

Uh oh!

lan17 commented Feb 20, 2026

Uh oh!

siddhant-galileo commented Feb 23, 2026

Uh oh!

lan17 commented Feb 23, 2026

Uh oh!

siddhant-galileo commented Feb 23, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

lan17 commented Feb 17, 2026 •

edited

Loading