TS SDK redesign

[noise64]

• resolves Fluent TS SDK: Basic agent features #3449
• resolves Fluent TS SDK: Feature parity, finalized naming #3450
• resolves Fluent TS SDK: Switch to fluent API #3451
• resolves Fluent TS SDK: Docs #3453
• adds skills for migration from old SDK, but in a followup card will implement hinting on using that skill when detecting upgrades or compile errors around using the old SDK
• we should also do a follow-up later on TS bridges, if there is any naming that we should align

[netlify]

✅ Deploy Preview for golemcloud canceled.

Name	Link
🔨 Latest commit	451ce80
🔍 Latest deploy log	https://app.netlify.com/projects/golemcloud/deploys/6a4cefe90db5010008e6a8bc

[github-actions]

📖 Docs preview: https://docs-5eqzken7d-golem-cloud.vercel.app

Built from commit 451ce807217360a123f98602d832961fc95e43b6 by docs.yaml.

[vigoo]

A few gaps around compile-time safety and client ergonomics, left as inline comments.

[vigoo]

http stays optional even when one of the methods declares HTTP endpoints, so forgetting the mount only fails at runtime (the 'declares HTTP endpoint(s) but the agent has no HTTP mount' throw in runtime.ts). Since MethodSpec already carries its endpoints, we could track a "has HTTP" flag at the type level (e.g. a boolean phantom on MethodSpec, aggregated over Methods) and make http a required field of AgentSpec whenever any method declares endpoints. That turns a deploy-time error into a compile error, and we already do similar type-level work here with MountSpecCovering / WebhookVarsValid.

[vigoo]

optional and nullable are both collapsed into the same WIT option codec, and fromValue decodes the none case to undefined unconditionally. That breaks round-tripping for nullable fields: a field declared z.number().nullable() infers as number | null, but after a round trip the receiver gets undefined — a value that isn't even assignable to the schema's own inferred type. Same issue in the valibot walker (nullable / nullish / undefinedable all in one OPTIONAL set).

Suggest recording which wrapper produced the option and decoding none accordingly: undefined for optional, null for nullable, and picking one (or undefined) for nullish. The wire format doesn't change; only the decode side needs the distinction.

[vigoo]

In { policy, state }, state is an untyped StandardSchemaV1, so nothing connects it to the State object that init actually returns. A typo'd field name, or drift after a refactor of init, compiles fine and only surfaces when validateSnapshotState rejects the instance at the first snapshot save — on a deployed agent.

Since State is only known at implement(...) time, one way to get compile-time checking: thread the snapshot schema type through AgentSpec into AgentImplementation and constrain State against the schema's output type (e.g. State extends StandardSchemaV1.InferOutput<StateSchema>), so the schema-declared fields must exist on the state with matching types.

[vigoo]

A few ergonomics gaps on the client surface:

1. Fresh phantom clients. clientFor(def)(id, phantomId?) supports existing phantom ids, but there's no helper for "create a new phantom instance and give me its id" — callers must generate a Uuid themselves and thread it through. Consider something like client.newPhantom(id) returning the client with the generated phantomId exposed on it (mirroring how fork() returns ForkDetails).
2. Cancellation on awaited calls. The plain call method(input) can't be cancelled; you must switch to abortable(signal, input), which also reorders the arguments. An optional trailing options argument on the main call shape (method(input, { signal })) would keep one call shape and make cancellation compositional with existing AbortSignal-based code.
3. schedule vs scheduleCancelable. schedule() returns void while scheduleCancelable() returns a CancellationToken. Unless the non-cancelable host path is meaningfully cheaper, consider having schedule always return the token — one method, and cancellation doesn't require deciding upfront.

[vigoo]

defineAgent(...) throwing at module load means a single invalid agent definition takes down the whole component at instantiation: the guest never gets far enough for discover-agent-types to run, so the CLI/registry see a generic wasm trap instead of a structured, per-agent diagnostic. This also means one bad agent hides all the valid ones in the same component.

Consider capturing definition-validation failures at defineAgent/implement time and re-emitting them as typed AgentErrors from discoverAgentTypes (and from initialize for the affected agent type), so tooling can render "agent X is invalid because Y" while other agents in the component keep working. Eager throwing could stay as-is under a dev/test flag where fail-fast is preferable.