@devries-cameron20 / composio Mirror · read-only / commits / 259a75b4b
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, 06:00 UTC

docs(cli): correct the lint and test-clock guidance in agent skills (#5205)

This PR: - fixes the `effect-v4` skill and its `core-patterns` reference, which said ESLint bans `async`/`await` and `try`/`catch` in `ts/packages/cli/src`. oxlint rejects `try`/`catch` (`TryStatement` in `.oxlintrc.json`), and no rule covers `async`/`await` - reconciles the "Time in tests" guidance with the suite. The skill said never to use `it.live` for the client's retry backoff, while the client retry tests run on the live clock and answer with `retry-after-ms: 0`. Examples: `composio-clients.test.ts`, `composio-client-singleton.test.ts`, `tool-permissions.test.ts` (`it.live`), and `tools.execute.client.cmd.test.ts`, `proxy.client.cmd.test.ts` (`layer(..., { excludeTestServices: true })`) - documents that case in `core-patterns.md` and `typescript-testing/references/effect-v4-cli.md`, and names both live-clock forms in the `stubComposioClient` doc comment - `bun run validate:agent-skills`, `validate:skill-routing`, `bun test test/cli-skills.test.ts` and the skill TypeScript block compilation pass locally. The CLI typecheck step of `check-cli-skills.ts` was left to CI, since only a doc comment changed in code

Alberto Schiabel committed Nov 4, 2026 at 18:53 UTC 259a75b4b335543dd0185924feff45557f4eaed2
4 files changed +20 -10
.agents/skills/effect-v4/SKILL.md
+2 -2
@@ -48,8 +48,8 @@ when an excerpt or explanation disagrees with the implementation.
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 - ESLint bans them in `ts/packages/cli/src`.
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;
.agents/skills/effect-v4/references/core-patterns.md
+14 -7
@@ -116,8 +116,8 @@ Either way, recover with `Effect.catchTag`, `Effect.catchTags`, `Match.valueTags
116
117 `Effect.tryPromise({ try, catch })` for a Promise that can reject and needs a typed
118 error; `Effect.promise` turns rejection into a defect (only for Promises that are
119 -truly infallible). No `async`/`await` or `try`/`catch` inside Effect-hosted code — both
120 -are ESLint-banned in `ts/packages/cli/src`. From `@composio/cli-keyring`'s
119 +truly infallible). No `async`/`await` or `try`/`catch` inside Effect-hosted code. oxlint
120 +rejects `try`/`catch` in `ts/packages/cli/src`. Nothing lints `async`/`await`, so review catches it. From `@composio/cli-keyring`'s
121 `effect.ts`, both `Effect.tryPromise` and `Effect.promise` kept their v3 signatures
122 unchanged in v4.
123
@@ -249,8 +249,8 @@ export const isTelemetryDebugEnabled: Effect.Effect<boolean> = Effect.gen(functi
249 on Effect's clock inside the code under test (`Effect.sleep`, `Effect.retry` with a
250 `Schedule`, `Effect.timeout`, the API client's retry backoff) only completes when the test
251 moves that clock. Awaiting such an effect on the test's own fiber hangs until the vitest
252 -timeout, because nothing is left to advance time. Do not fix that with `it.live`: a live
253 -clock makes CI wait out the real backoff.
252 +timeout, because nothing is left to advance time. Do not fix that with `it.live` when the
253 +code waits out a real backoff, because CI would wait too.
254
255 The pattern is fork, then yield and adjust until the fiber settles, then join:
256
@@ -295,9 +295,16 @@ retry) and `ts/packages/cli/test/src/commands/setup.cmd.test.ts` (a two-minute c
295 timeout).
296
297 `it.live` is for code that sleeps outside Effect's clock, such as a spawned process or a
298 -`setTimeout` inside a non-Effect library, and even then the test should shorten the wait
299 -(the client retry tests pass a `retry-after-ms: 0` header). Nothing in the CLI suite waits on
300 -wall-clock time.
298 +`setTimeout` inside a non-Effect library, and even then the test should shorten the wait.
299 +
300 +One Effect-clock case also runs live: a test that answers the API client itself, through the
301 +recording stub (`ts/packages/cli/test/__utils__/services/stub-composio-client.ts`) or a mocked
302 +`fetch`, with a retryable response. Answer it with a `retry-after-ms: 0` header and run on the
303 +live clock, with `it.live` or `layer(..., { excludeTestServices: true })`. The client's retry
304 +then waits zero milliseconds, and a test that expects one request fails on the second instead
305 +of hanging. Real uses: `ts/packages/cli/test/src/services/composio-clients.test.ts` and
306 +`ts/packages/cli/test/src/commands/tools/execute/tools.execute.client.cmd.test.ts`. Nothing in the CLI suite
307 +waits on wall-clock time.
308
309 ## v3 → v4 rename table (historical — recognize stale patterns, don't copy them)
310
.agents/skills/typescript-testing/references/effect-v4-cli.md
+2
@@ -17,6 +17,8 @@ repo-local `effect-v4` skill.
17 under test sleeps outside Effect's clock; a retry, timeout, or `Effect.sleep` inside the code
18 under test is driven on `it.effect` by forking the effect, looping `Effect.yieldNow` and `TestClock.adjust`
19 until `fiber.pollUnsafe()` is set, and `Fiber.join` (see "Time in tests" in the `effect-v4` skill's core-patterns reference).
20 + The exception is a test that answers the API client itself with a retryable response. It answers
21 + with `retry-after-ms: 0` and runs on the live clock, as that section describes.
22 - Reusable service layers go through `layer(...)`, not manual `Effect.provide` scattered per test:
23
24 ```ts no-check
ts/packages/cli/test/__utils__/services/stub-composio-client.ts
+2 -1
@@ -19,7 +19,8 @@ export interface StubRequest {
19 * and the validation a call asks for are the client's own.
20 *
21 * A retried call sleeps on Effect's clock, so a test whose answer is retryable
22 - * runs under `it.live` and answers with a `retry-after-ms: 0` header.
22 + * runs on the live clock (`it.live`, or `layer(..., { excludeTestServices: true })`)
23 + * and answers with a `retry-after-ms: 0` header.
24 */
25 export const stubComposioClient = (
26 respond: (request: StubRequest) => Response