Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
docs(agents): require zod and effect/Schema at data boundaries (#3969)
Alberto Schiabel022ecf617659
diff --git a/docs/AGENTS.md b/docs/AGENTS.mdindex 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.mdindex 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.mdindex 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.mdindex 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.