@devries-cameron20 / composio Mirror · read-only / commits / 022ecf617
Fork 0

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

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 18:30 UTC

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

This PR: - codifies the schema-parsing convention in agent guidance: parse untyped/external data once at the boundary with zod (`z.infer` downstream) in the docs site and SDK packages, and with `effect/Schema` in the CLI - bans hand-rolled structural guards (`'x' in obj` / `typeof` chains), `as`-casts of parsed JSON, and fake validators such as `z.custom(() => true)` - updates `docs/AGENTS.md`, `ts/AGENTS.md`, `ts/packages/core/AGENTS.md`, and the existing trust-boundary rule in `ts/packages/cli/AGENTS.md` ## Context Follow-up to the review feedback that led to the #3958 split (#3966 / #3967 / #3968): the docs type-safety work initially shipped a suite of conditional structural utility helpers instead of zod schemas. This records the convention so agents and contributors reach for schemas by default.

Alberto Schiabel committed Jul 28, 2026 at 18:44 UTC 022ecf6176590228041cdba4058c4cc8e0823b4a
4 files changed +4 -1
docs/AGENTS.md
+1
@@ -35,6 +35,7 @@ bun run generate:api-index
35 ## Rules
36
37 - TypeScript code blocks in MDX are checked during docs builds. Use `docs/agent-guidance/context/twoslash.md` before changing typed examples.
38 +- 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)`.
39 - Internal docs links must be relative site paths such as `/docs/...`, `/reference/...`, or `/assets/...`.
40 - API reference pages and toolkit/meta-tool data are generated. Do not hand-edit generated data unless the local generator owns it.
41 - Changelog entries require `title` and `date` frontmatter, and dates use `YYYY-MM-DD`.
ts/AGENTS.md
+1
@@ -36,3 +36,4 @@ pnpm test:e2e:cli
36 - Add changesets only for changes to published TypeScript packages.
37 - 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.
38 - Prefer focused package tests before broad workspace tests.
39 +- 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`.
ts/packages/cli/AGENTS.md
+1 -1
@@ -139,7 +139,7 @@ Key patterns: `Effect.all([...], { concurrency: 'unbounded' })` for parallel wor
139
140 - 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.
141 - 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.
142 -- 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.
142 +- 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).
143 - 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.
144 - Prefer `Effect.mapError`, `Effect.matchEffect`, and typed recovery over `catchAll` blocks that flatten distinct failures into one message-only error.
145
ts/packages/core/AGENTS.md
+1
@@ -27,3 +27,4 @@ pnpm test
27 - Add regression coverage for behavior changes.
28 - Do not hand-edit generated client code unless the generator output is explicitly in scope.
29 - Check Python parity before changing shared concepts such as tools, toolkits, sessions, auth configs, or connected accounts.
30 +- 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.