Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

docs(agents): require zod and effect/Schema at data boundaries (#3969)

Alberto Schiabel022ecf617659
diff --git a/docs/AGENTS.md b/docs/AGENTS.md
index cc5fe6c42..b8131be3e 100644
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@@ -35,6 +35,7 @@ bun run generate:api-index
## Rules
- TypeScript code blocks in MDX are checked during docs builds. Use `docs/agent-guidance/context/twoslash.md` before changing typed examples.
+- Parse untyped or external data (JSON files, fetched payloads, framework page data) once at the boundary with zod schemas and let `z.infer` types flow downstream. Never hand-roll structural guards (`'x' in obj` / `typeof` chains), cast parsed JSON with `as`, or fake validation with `z.custom(() => true)`.
- Internal docs links must be relative site paths such as `/docs/...`, `/reference/...`, or `/assets/...`.
- API reference pages and toolkit/meta-tool data are generated. Do not hand-edit generated data unless the local generator owns it.
- Changelog entries require `title` and `date` frontmatter, and dates use `YYYY-MM-DD`.
diff --git a/ts/AGENTS.md b/ts/AGENTS.md
index 202886d44..485315d94 100644
--- a/ts/AGENTS.md
+++ b/ts/AGENTS.md
@@ -36,3 +36,4 @@ pnpm test:e2e:cli
- Add changesets only for changes to published TypeScript packages.
- Never add changesets for `@composio/cli` or `@composio/cli-local-tools` while `.changeset/config.json` ignores them; record CLI notes in `ts/packages/cli/CHANGELOG.md` instead.
- Prefer focused package tests before broad workspace tests.
+- Parse untyped or external data (API payloads, JSON, `unknown`) at the boundary with schemas and let inferred types flow downstream: zod in SDK packages (`@composio/core`, providers, shared packages), `effect/Schema` in `ts/packages/cli/`. Never hand-roll structural guards (`'x' in obj` / `typeof` chains) or cast parsed JSON with `as`.
diff --git a/ts/packages/cli/AGENTS.md b/ts/packages/cli/AGENTS.md
index 526d043b9..9d1637363 100644
--- a/ts/packages/cli/AGENTS.md
+++ b/ts/packages/cli/AGENTS.md
@@ -139,7 +139,7 @@ Key patterns: `Effect.all([...], { concurrency: 'unbounded' })` for parallel wor
- Never branch on an Effect value's internal tag field directly. Use the owning module's public refinement or matcher (`Option`, `Either`, `Exit`, `Cause`, `ValidationError`), `Match.valueTags` for exhaustive unions, or `Predicate.isTagged` for a single narrowing guard.
- Do not wrap a plain `Error` in `Effect.fail` for expected failures. Give the failure a meaningful `Data.TaggedError` type with structured fields and a preserved cause, then recover with `catchTag` / `catchTags`. Reserve `Effect.die` and `Effect.dieMessage` for impossible invariants.
-- Treat `unknown`, JSON, persisted state, and API payloads as trust boundaries. Decode them with `Schema` or narrow them with `Predicate`; an `as` assertion is not validation.
+- Treat `unknown`, JSON, persisted state, and API payloads as trust boundaries. Decode them with `effect/Schema` or narrow them with `Predicate`; an `as` assertion is not validation, and hand-rolled structural guards (`'x' in obj` / `typeof` chains) are not a substitute for a schema. `effect/Schema` is the CLI's schema tool — do not introduce zod here (zod is the convention in the SDK packages and docs).
- Do not inspect private `@effect/cli` descriptor shapes. Use public `CommandDescriptor` operations or keep declarative command metadata that can move to Effect v4's public command tree.
- Prefer `Effect.mapError`, `Effect.matchEffect`, and typed recovery over `catchAll` blocks that flatten distinct failures into one message-only error.
diff --git a/ts/packages/core/AGENTS.md b/ts/packages/core/AGENTS.md
index cfeaebf70..9f3994c54 100644
--- a/ts/packages/core/AGENTS.md
+++ b/ts/packages/core/AGENTS.md
@@ -27,3 +27,4 @@ pnpm test
- Add regression coverage for behavior changes.
- Do not hand-edit generated client code unless the generator output is explicitly in scope.
- Check Python parity before changing shared concepts such as tools, toolkits, sessions, auth configs, or connected accounts.
+- Parse untyped or external data (API payloads, JSON, `unknown`) at the boundary with zod schemas and let `z.infer` types flow downstream. Never hand-roll structural guards (`'x' in obj` / `typeof` chains) or cast parsed JSON with `as` — an assertion is not validation.