@devries-cameron20 / composio Mirror · read-only
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, 07:15 UTC

next
md 76 lines 4.57 KB
Rendered Raw
1 ---
2 name: effect-v4
3 description: Write, review, or upgrade Effect v4 code in the Composio CLI, cli-keyring, and json-schema-to-effect-schema packages, all using the matching range effect@^4.1.0 — Context.Service and explicit layers, Schema.TaggedError and typed recovery, the effect/cli command surface, and the vendored effect source oracle. Use when writing or reviewing Effect v4 code, answering a v4 API question, working in effect/cli, defining a Context.Service service, modeling an error with Schema.TaggedError, bumping the Effect pins, or verifying an unfamiliar API against ts/vendor/effect. Do not use for CLI command UX/wiring design (use cli-command) or CLI E2E tests (use cli-e2e).
4 ---
5
6 # Effect v4
7
8 The CLI, `@composio/cli-keyring`, and `@composio/json-schema-to-effect-schema` run on
9 Effect v4. Every claim below is grounded in the migrated source, not memory of v3.
10
11 ## Version matrix
12
13 `effect`, `@effect/platform-bun`, and `@effect/vitest`
14 use the **same range** `^4.1.0`; keep their lockfile resolutions aligned. Do not use
15 `@next` or mismatched versions across packages. `@effect/cli` and `@effect/platform` no longer exist as
16 dependencies; their surfaces are consolidated into `effect` and `effect/*`.
17 See [versions.json](versions.json) for the exact example-check matrix (also `typescript`, `vitest`).
18
19 ## Read next
20
21 - [references/core-patterns.md](references/core-patterns.md) — services, layers, typed
22 errors, Schema, choosing between `Effect.gen` and `Effect.fn`, `Option` combinators in
23 place of `isSome` ternaries, driving time in tests with
24 `TestClock` (fork, adjust until the fiber settles, join) instead of `it.live`, and the v3→v4 rename table
25 (labeled historical, for recognizing stale patterns).
26 - [references/cli-surface.md](references/cli-surface.md) — `effect/cli`:
27 `Command`, `Flag`, `Argument`, `GlobalFlag`, `CliConfig`, the custom
28 `CliOutput.Formatter`, and the runner's double-print rule.
29 - [references/upgrade-workflow.md](references/upgrade-workflow.md) — procedure for
30 bumping to a newer release.
31
32 References label source excerpts and standalone framework examples separately. Repo-linked
33 excerpts name the file checked by `validate:cli-skills`. The cited source remains authoritative
34 when an excerpt or explanation disagrees with the implementation.
35
36 ## Non-negotiables
37
38 - `Effect.gen(function* () {...})` for effect values — the dominant form, including named
39 module consts — and `(params) => Effect.gen(...)` for parameterized helpers.
40 `Effect.fn(...)` is the function form whose effects carry stack-frame annotations (its
41 optional name string adds a per-call tracing span), worth it for service members and
42 combinator callbacks that should be attributable in error reports. All forms re-run
43 their body per execution. See "`Effect.gen` vs `Effect.fn`" in core-patterns.
44 - Define services with `Context.Service` and an explicit `static readonly Default`/`layer`
45 layer built with `Layer.succeed`/`Layer.effect`/`Layer.provide`. V4 does not generate a
46 layer for you.
47 - Model expected failures with `Schema.TaggedError` (or a plain `Data.TaggedError`
48 when no Schema fields are needed) and recover with `Effect.catchTag`/`catchTags`/`Match`,
49 never manual `_tag` string comparisons.
50 - Wrap fallible Promises with `Effect.tryPromise({ try, catch })`; `Effect.promise` turns
51 rejection into a defect. No `async`/`await` or `try`/`catch` inside Effect workflows.
52 oxlint rejects `try`/`catch` in `ts/packages/cli/src`. Nothing lints `async`/`await`, so review catches it.
53 - Treat every remembered v3 package name and API as wrong until verified against
54 `ts/vendor/effect` (read-only source oracle — never edit or import from it) and the
55 installed `effect@^4.1.0` typings. Source may be ahead of the published package;
56 the compiler is the compatibility gate.
57
58 ## Verification
59
60 ```bash
61 pnpm typecheck
62 pnpm --filter @composio/cli run lint:effect
63 pnpm --filter @composio/cli test
64 ```
65
66 Run `bun run validate:agent-skills` and `bun run validate:skill-routing` after editing this
67 skill or its descriptions, and compile the TypeScript blocks in this skill and in
68 `typescript-testing/references/effect-v4-cli.md` against the pinned packages with:
69
70 ```bash
71 node .agents/skills/effect-v4/scripts/check-examples.mjs
72 ```
73
74 Blocks that quote repo files with unresolvable imports carry a `no-check` fence info string.
75
76 `bun run validate:cli-skills` also verifies repo-linked command examples, their native Effect client requests, and the selected invocation contracts in Agent Substrate CI. Standalone snippet compilation and routing probes alone do not certify command behavior or agent task performance.