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.

fix(cli): handle plugin setup errors gracefully

Kshitij Jhunjhunwala2b375b48552c
diff --git a/ts/e2e-tests/cli/setup-plugins/e2e.test.ts b/ts/e2e-tests/cli/setup-plugins/e2e.test.ts
index ff03fabc6..9f08751c8 100644
--- a/ts/e2e-tests/cli/setup-plugins/e2e.test.ts
+++ b/ts/e2e-tests/cli/setup-plugins/e2e.test.ts
@@ -53,6 +53,17 @@ export PATH=/tmp/bin:$PATH
composio setup --target auto --yes
`;
+const legacyClaudeFixture = `
+set -eu
+mkdir -p /tmp/bin /tmp/host-state
+cp fixtures/fake-agent-host.sh /tmp/bin/claude
+chmod +x /tmp/bin/claude
+touch /tmp/host-state/claude-without-json
+export HOST_STATE_DIR=/tmp/host-state
+export PATH=/tmp/bin:$PATH
+composio setup --target auto --yes
+`;
+
const claudeWithLegacyCodexFixture = `
set -eu
mkdir -p /tmp/bin /tmp/host-state
@@ -71,6 +82,31 @@ test -f /tmp/host-state/claude-plugin
test ! -f /tmp/host-state/codex-plugin
`;
+const codexWithLegacyClaudeFixture = `
+set -eu
+mkdir -p /tmp/bin /tmp/host-state
+cp fixtures/fake-agent-host.sh /tmp/bin/claude
+cp fixtures/fake-agent-host.sh /tmp/bin/codex
+chmod +x /tmp/bin/claude /tmp/bin/codex
+touch /tmp/host-state/claude-without-json
+export HOST_STATE_DIR=/tmp/host-state
+export PATH=/tmp/bin:$PATH
+composio setup --target auto --yes
+test ! -f /tmp/host-state/claude-plugin
+test -f /tmp/host-state/codex-plugin
+`;
+
+const failedClaudeInspectionFixture = `
+set -eu
+mkdir -p /tmp/bin /tmp/host-state
+cp fixtures/fake-agent-host.sh /tmp/bin/claude
+chmod +x /tmp/bin/claude
+touch /tmp/host-state/claude-inspection-fails
+export HOST_STATE_DIR=/tmp/host-state
+export PATH=/tmp/bin:$PATH
+composio setup --target auto --yes
+`;
+
e2e(import.meta.url, {
versions: {
cli: ['current'],
@@ -81,8 +117,11 @@ e2e(import.meta.url, {
let unavailable: E2ETestResult;
let skippedUnavailable: E2ETestResult;
let skippedUnavailableUninstall: E2ETestResult;
+ let legacyClaude: E2ETestResult;
let legacyCodex: E2ETestResult;
let claudeWithLegacyCodex: E2ETestResult;
+ let codexWithLegacyClaude: E2ETestResult;
+ let failedClaudeInspection: E2ETestResult;
beforeAll(async () => {
// The shared E2E runner derives container names from Date.now(), so keep
@@ -100,8 +139,11 @@ e2e(import.meta.url, {
skippedUnavailableUninstall = await runCmd(
'composio setup --uninstall --target auto --yes --if-present'
);
+ legacyClaude = await runCmd(legacyClaudeFixture);
legacyCodex = await runCmd(legacyCodexFixture);
claudeWithLegacyCodex = await runCmd(claudeWithLegacyCodexFixture);
+ codexWithLegacyClaude = await runCmd(codexWithLegacyClaudeFixture);
+ failedClaudeInspection = await runCmd(failedClaudeInspectionFixture);
}, TIMEOUTS.FIXTURE);
describe.each([
@@ -180,7 +222,14 @@ e2e(import.meta.url, {
});
});
- describe('Codex compatibility', () => {
+ describe('agent compatibility', () => {
+ it('exits with Claude update instructions when no supported host remains', () => {
+ expect(legacyClaude.exitCode).not.toBe(0);
+ expect(legacyClaude.stdout).toBe('');
+ expect(legacyClaude.stderr).toContain('requires JSON plugin inspection');
+ expect(legacyClaude.stderr).toContain('claude update');
+ });
+
it('exits with upgrade instructions when no supported host remains', () => {
expect(legacyCodex.exitCode).not.toBe(0);
expect(legacyCodex.stdout).toBe('');
@@ -194,6 +243,26 @@ e2e(import.meta.url, {
expect(claudeWithLegacyCodex.stdout).toBe('');
expect(claudeWithLegacyCodex.stderr).toBe('');
});
+
+ it('continues with Codex when Claude is unsupported', () => {
+ expect(codexWithLegacyClaude.exitCode).toBe(0);
+ expect(codexWithLegacyClaude.stdout).toBe('');
+ expect(codexWithLegacyClaude.stderr).toBe('');
+ });
+ });
+
+ describe('graceful failures', () => {
+ it('reports the failed host, recovery command, and no generic usage dump', () => {
+ expect(failedClaudeInspection.exitCode).not.toBe(0);
+ expect(failedClaudeInspection.stdout).toBe('');
+ expect(failedClaudeInspection.stderr).toContain('Composio setup was unsuccessful.');
+ expect(failedClaudeInspection.stderr).toContain(
+ 'Failed to inspect Claude Code plugins: native inspection failed.'
+ );
+ expect(failedClaudeInspection.stderr).toContain('composio setup --target claude');
+ expect(failedClaudeInspection.stderr).not.toContain('USAGE');
+ expect(failedClaudeInspection.stderr).not.toContain('effect-errors');
+ });
});
},
});
diff --git a/ts/e2e-tests/cli/setup-plugins/fixtures/fake-agent-host.sh b/ts/e2e-tests/cli/setup-plugins/fixtures/fake-agent-host.sh
index 44f51e47c..f7f8441fd 100644
--- a/ts/e2e-tests/cli/setup-plugins/fixtures/fake-agent-host.sh
+++ b/ts/e2e-tests/cli/setup-plugins/fixtures/fake-agent-host.sh
@@ -12,6 +12,12 @@ case "$host:$command" in
"claude:--version")
printf '%s\n' '2.1.207 (Claude Code)'
;;
+ "claude:plugin marketplace list --help"|"claude:plugin list --help")
+ printf '%s\n' "Usage: claude $command [OPTIONS]"
+ if [ ! -f "$state_dir/claude-without-json" ]; then
+ printf '%s\n' ' --json'
+ fi
+ ;;
"claude:plugin marketplace list --json")
if [ -f "$state_dir/claude-marketplace" ]; then
printf '%s\n' '[{"name":"composio","source":"git","url":"https://github.com/ComposioHQ/composio-plugin-cc.git"}]'
@@ -20,6 +26,10 @@ case "$host:$command" in
fi
;;
"claude:plugin list --json")
+ if [ -f "$state_dir/claude-inspection-fails" ]; then
+ printf '%s\n' 'native inspection failed' 'Usage: claude plugin list [options]' >&2
+ exit 2
+ fi
if [ -f "$state_dir/claude-plugin" ]; then
printf '%s\n' '[{"id":"composio@composio","scope":"user","enabled":true}]'
else
@@ -51,6 +61,12 @@ case "$host:$command" in
printf '%s\n' ' --json'
fi
;;
+ "codex:plugin list --help")
+ printf '%s\n' 'Usage: codex plugin list [OPTIONS]'
+ if [ ! -f "$state_dir/codex-without-json" ]; then
+ printf '%s\n' ' --json'
+ fi
+ ;;
"codex:plugin marketplace list --json")
if [ -f "$state_dir/codex-marketplace" ]; then
printf '%s\n' '{"marketplaces":[{"name":"composio","marketplaceSource":{"sourceType":"git","source":"ComposioHQ/composio-plugin-openai"}}]}'
diff --git a/ts/packages/cli/src/cli-main.ts b/ts/packages/cli/src/cli-main.ts
index af88bef70..c814e48f9 100644
--- a/ts/packages/cli/src/cli-main.ts
+++ b/ts/packages/cli/src/cli-main.ts
@@ -22,7 +22,7 @@ import { JsPackageManagerDetector } from 'src/services/js-package-manager-detect
import { ComposioCliUserConfigLive, ComposioCliUserConfig } from 'src/services/cli-user-config';
import { ComposioUserContextLive as _ComposioUserContextLive } from 'src/services/user-context';
import { UpgradeBinary } from 'src/services/upgrade-binary';
-import { TerminalUILive } from 'src/services/terminal-ui';
+import { TerminalUI, TerminalUILive } from 'src/services/terminal-ui';
import { TriggersRealtime } from 'src/services/triggers-realtime';
import { ToolsExecutorLive as _ToolsExecutorLive } from 'src/services/tools-executor';
import { ProjectContext } from 'src/services/project-context';
@@ -39,6 +39,8 @@ import {
import { trackCliEvent, trackCliEventEffect } from 'src/analytics/dispatch';
import { mapOnlyComposioOverrideError } from 'src/services/composio-error-overrides';
import { SetupSkillInstaller } from 'src/services/setup-skill-installer';
+import { SetupCommandError } from 'src/services/setup';
+import { canRenderTerminalDecoration } from 'src/utils/stdio';
// eslint-disable-next-line @typescript-eslint/no-explicit-any
type RequiredLayer = Layer.Layer<any, any, never>;
@@ -235,6 +237,24 @@ runWithArgs.pipe(
);
});
}),
+ Effect.catchIf(
+ (error): error is SetupCommandError => error instanceof SetupCommandError,
+ error =>
+ Effect.gen(function* () {
+ const ui = yield* TerminalUI;
+ const summary =
+ error.operation === 'uninstall'
+ ? 'Composio plugin uninstall was unsuccessful.'
+ : 'Composio setup was unsuccessful.';
+ if (canRenderTerminalDecoration()) {
+ yield* ui.log.error(error.message);
+ yield* ui.outro(summary);
+ } else {
+ yield* Console.error(`${summary} ${error.message}`);
+ }
+ process.exitCode = 1;
+ })
+ ),
Effect.withSpan('composio-cli', {
attributes: {
name: constants.APP_NAME,
diff --git a/ts/packages/cli/src/commands/setup.cmd.ts b/ts/packages/cli/src/commands/setup.cmd.ts
index 05a36eb36..dd36adc4c 100644
--- a/ts/packages/cli/src/commands/setup.cmd.ts
+++ b/ts/packages/cli/src/commands/setup.cmd.ts
@@ -7,6 +7,7 @@ import {
isSetupPluginReady,
isSetupReady,
SETUP_TARGETS,
+ SetupCommandError,
uninstallSetupTargets,
type AgentHost,
type SetupTarget,
@@ -44,6 +45,9 @@ const TARGET_LABELS: Readonly<Record<AgentHost, string>> = {
const formatTargets = (targets: ReadonlyArray<AgentHost>): string =>
targets.map(target => TARGET_LABELS[target]).join(' and ');
+const errorMessage = (error: unknown): string =>
+ error instanceof Error ? error.message : String(error);
+
const setupBaseCmd = Command.make(
'setup',
{ target, yes, ifPresent, uninstall },
@@ -108,6 +112,7 @@ const setupBaseCmd = Command.make(
const inspected = yield* inspectSetupTargets(detections, {
allowMarketplaceConflict: uninstall,
+ operation: uninstall ? 'uninstall' : 'setup',
});
if (uninstall) {
const installed = inspected.filter(status => status.plugin_installed);
@@ -203,7 +208,15 @@ const setupBaseCmd = Command.make(
}
yield* ui.outro('Composio setup complete.');
- })
+ }).pipe(
+ Effect.mapError(
+ error =>
+ new SetupCommandError({
+ message: errorMessage(error),
+ operation: uninstall ? 'uninstall' : 'setup',
+ })
+ )
+ )
);
export const setupCmd = setupBaseCmd.pipe(
diff --git a/ts/packages/cli/src/services/setup.ts b/ts/packages/cli/src/services/setup.ts
index 908027d43..156b2ecd7 100644
--- a/ts/packages/cli/src/services/setup.ts
+++ b/ts/packages/cli/src/services/setup.ts
@@ -1,5 +1,5 @@
import { Command } from '@effect/platform';
-import { Effect } from 'effect';
+import { Data, Effect } from 'effect';
import semver from 'semver';
import { CommandRunner, type CommandResult } from './command-runner';
import { SetupSkillInstaller } from './setup-skill-installer';
@@ -46,6 +46,7 @@ interface SetupTargetAdapter {
readonly pluginInstallArgs: ReadonlyArray<string>;
readonly pluginEnableArgs: ReadonlyArray<string>;
readonly pluginUninstallArgs: ReadonlyArray<string>;
+ readonly inspectionHelpArgs: ReadonlyArray<ReadonlyArray<string>>;
readonly marketplaceRecordsKey?: string;
readonly pluginRecordsKey?: string;
readonly pluginScope?: string;
@@ -82,6 +83,10 @@ const ADAPTERS: Readonly<Record<AgentHost, SetupTargetAdapter>> = {
'user',
'--yes',
],
+ inspectionHelpArgs: [
+ ['plugin', 'marketplace', 'list', '--help'],
+ ['plugin', 'list', '--help'],
+ ],
pluginScope: 'user',
marketplaceRemoveCommand: 'claude plugin marketplace remove composio --scope user',
skillSource: 'standalone',
@@ -97,6 +102,10 @@ const ADAPTERS: Readonly<Record<AgentHost, SetupTargetAdapter>> = {
// Codex has no separate enable command. Re-adding is its native install/repair path.
pluginEnableArgs: ['plugin', 'add', CODEX_PLUGIN_MARKETPLACE.plugin, '--json'],
pluginUninstallArgs: ['plugin', 'remove', CODEX_PLUGIN_MARKETPLACE.plugin, '--json'],
+ inspectionHelpArgs: [
+ ['plugin', 'marketplace', 'list', '--help'],
+ ['plugin', 'list', '--help'],
+ ],
marketplaceRecordsKey: 'marketplaces',
pluginRecordsKey: 'installed',
marketplaceRemoveCommand: 'codex plugin marketplace remove composio --json',
@@ -108,6 +117,11 @@ const ADAPTER_LIST = Object.values(ADAPTERS);
const SETUP_COMMAND_TIMEOUT = '2 minutes';
const MINIMUM_CODEX_SETUP_VERSION = '0.139.0';
+export class SetupCommandError extends Data.TaggedError('services/SetupCommandError')<{
+ readonly message: string;
+ readonly operation: 'setup' | 'uninstall';
+}> {}
+
const asRecord = (value: unknown): Record<string, unknown> | undefined => {
if (value === null || typeof value !== 'object' || Array.isArray(value)) return undefined;
return value as Record<string, unknown>;
@@ -228,61 +242,154 @@ const pluginState = (
return { installed: true, enabled: plugin.enabled !== false };
};
+const commandText = (executable: string, args: ReadonlyArray<string>) =>
+ [executable, ...args].join(' ');
+
const capture = (executable: string, args: ReadonlyArray<string>) =>
Effect.gen(function* () {
const runner = yield* CommandRunner;
return yield* runner.capture(Command.make(executable, ...args)).pipe(
- Effect.catchAll(() => Effect.succeed<CommandResult | undefined>(undefined)),
Effect.timeoutFail({
duration: SETUP_COMMAND_TIMEOUT,
- onTimeout: () => new Error(`${executable} command timed out.`),
+ onTimeout: () =>
+ new Error(
+ `The \`${commandText(executable, args)}\` command timed out after ${SETUP_COMMAND_TIMEOUT}.`
+ ),
})
);
});
-const unsupportedCodexInspectionMessage = () =>
- `This Codex installation does not support safe automatic plugin inspection. Composio setup requires Codex ${MINIMUM_CODEX_SETUP_VERSION} or newer with JSON plugin inspection. Run \`codex update\`, then rerun this command.`;
+const isCommandNotFound = (error: unknown): boolean => {
+ if (error === null || typeof error !== 'object') return false;
+ const record = error as Record<string, unknown>;
+ return record._tag === 'SystemError' && record.reason === 'NotFound';
+};
+
+const captureOptional = (executable: string, args: ReadonlyArray<string>) =>
+ capture(executable, args).pipe(
+ Effect.catchIf(isCommandNotFound, () => Effect.succeed<CommandResult | undefined>(undefined))
+ );
+
+const targetLabel = (target: AgentHost): string => (target === 'claude' ? 'Claude Code' : 'Codex');
+
+const hostUpdateCommand = (adapter: SetupTargetAdapter): string => `${adapter.executable} update`;
+
+const unsupportedInspectionMessage = (adapter: SetupTargetAdapter) => {
+ if (adapter.target === 'codex') {
+ return `This Codex installation does not support safe automatic plugin inspection. Composio setup requires Codex ${MINIMUM_CODEX_SETUP_VERSION} or newer with JSON plugin inspection. Run \`codex update\`, then rerun this command.`;
+ }
+ return 'This Claude Code installation does not support safe automatic plugin inspection. Composio setup requires JSON plugin inspection. Run `claude update`, then rerun this command.';
+};
+
+const compactCommandDetail = (value: string): string | undefined => {
+ const firstLine = value
+ .split(/\r?\n/u)
+ .map(line => line.trim())
+ .find(Boolean);
+ if (!firstLine) return undefined;
+ return firstLine.length > 300 ? `${firstLine.slice(0, 297)}...` : firstLine;
+};
+
+const commandResultDetail = (result: CommandResult): string => {
+ const detail = compactCommandDetail(result.stderr) ?? compactCommandDetail(result.stdout);
+ return detail ?? `exit ${result.exitCode}`;
+};
+
+const capabilityCheckFailureMessage = (
+ adapter: SetupTargetAdapter,
+ command: string,
+ detail: string
+) => {
+ const normalizedDetail = detail.trim().replace(/[.]+$/u, '');
+ return `Composio could not verify plugin support for ${targetLabel(adapter.target)} because \`${command}\` failed: ${normalizedDetail}. Run \`${hostUpdateCommand(adapter)}\`, then rerun this command.`;
+};
const supportsInspection = (adapter: SetupTargetAdapter, versionOutput?: string) =>
Effect.gen(function* () {
- if (adapter.target !== 'codex') return true;
-
- const version = versionOutput?.match(/\b\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?\b/)?.[0];
- if (!version || !semver.valid(version) || semver.lt(version, MINIMUM_CODEX_SETUP_VERSION)) {
- return false;
+ if (adapter.target === 'codex') {
+ const version = versionOutput?.match(/\b\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?\b/)?.[0];
+ if (!version || !semver.valid(version) || semver.lt(version, MINIMUM_CODEX_SETUP_VERSION)) {
+ return { supported: false, reason: unsupportedInspectionMessage(adapter) };
+ }
}
- const result = yield* capture(adapter.executable, ['plugin', 'marketplace', 'list', '--help']);
- const help = result ? `${result.stdout}\n${result.stderr}` : '';
- return result?.exitCode === 0 && /^\s*--json\b/m.test(help);
+ for (const args of adapter.inspectionHelpArgs) {
+ const command = commandText(adapter.executable, args);
+ const result = yield* capture(adapter.executable, args).pipe(
+ Effect.mapError(
+ error => new Error(capabilityCheckFailureMessage(adapter, command, errorMessage(error)))
+ )
+ );
+ if (result.exitCode !== 0) {
+ return {
+ supported: false,
+ reason: capabilityCheckFailureMessage(adapter, command, commandResultDetail(result)),
+ };
+ }
+ const help = `${result.stdout}\n${result.stderr}`;
+ if (!/^\s*--json\b/m.test(help)) {
+ return { supported: false, reason: unsupportedInspectionMessage(adapter) };
+ }
+ }
+ return { supported: true };
});
const detectAdapter = (adapter: SetupTargetAdapter) =>
Effect.gen(function* () {
- const result = yield* capture(adapter.executable, ['--version']);
- const available = result !== undefined && result.exitCode === 0;
- if (!available) return { available, supported: false };
+ const versionArgs = ['--version'] as const;
+ const versionCommand = commandText(adapter.executable, versionArgs);
+ const captureResult = yield* captureOptional(adapter.executable, versionArgs).pipe(
+ Effect.map(result => ({ result }) as const),
+ Effect.catchAll(error => Effect.succeed({ error } as const))
+ );
+ if ('error' in captureResult) {
+ return {
+ available: true,
+ supported: false,
+ unsupportedReason: capabilityCheckFailureMessage(
+ adapter,
+ versionCommand,
+ errorMessage(captureResult.error)
+ ),
+ };
+ }
+ const { result } = captureResult;
+ if (!result) return { available: false, supported: false };
+ if (result.exitCode === 127) return { available: false, supported: false };
+ if (result.exitCode !== 0) {
+ return {
+ available: true,
+ supported: false,
+ unsupportedReason: capabilityCheckFailureMessage(
+ adapter,
+ versionCommand,
+ commandResultDetail(result)
+ ),
+ };
+ }
const version = result.stdout.trim() || result.stderr.trim();
- const supported = yield* supportsInspection(adapter, version);
+ const support = yield* supportsInspection(adapter, version).pipe(
+ Effect.catchAll(error =>
+ Effect.succeed({ supported: false, reason: errorMessage(error) } as const)
+ )
+ );
return version
? {
- available,
- supported,
+ available: true,
+ supported: support.supported,
version,
- ...(supported ? {} : { unsupportedReason: unsupportedCodexInspectionMessage() }),
+ ...(support.supported ? {} : { unsupportedReason: support.reason }),
}
: {
- available,
- supported,
- ...(supported ? {} : { unsupportedReason: unsupportedCodexInspectionMessage() }),
+ available: true,
+ supported: support.supported,
+ ...(support.supported ? {} : { unsupportedReason: support.reason }),
};
});
const commandFailureSuffix = (result: CommandResult): string => {
- const detail = result.stderr.trim() || result.stdout.trim();
- if (detail) return `: ${detail}`;
- return ` (exit ${result.exitCode})`;
+ return `: ${commandResultDetail(result)}`;
};
const errorMessage = (error: unknown): string => {
@@ -290,23 +397,50 @@ const errorMessage = (error: unknown): string => {
return String(error);
};
+type SetupOperation = 'setup' | 'uninstall';
+
+const setupCommand = (adapter: SetupTargetAdapter, operation: SetupOperation): string =>
+ `composio setup${operation === 'uninstall' ? ' --uninstall' : ''} --target ${adapter.target}`;
+
+const recoveryHint = (adapter: SetupTargetAdapter, operation: SetupOperation): string =>
+ `Run \`${setupCommand(adapter, operation)}\` again. If the problem persists, run \`${hostUpdateCommand(adapter)}\` and retry.`;
+
+const captureInspection = (
+ adapter: SetupTargetAdapter,
+ args: ReadonlyArray<string>,
+ operation: string,
+ setupOperation: SetupOperation
+) =>
+ capture(adapter.executable, args).pipe(
+ Effect.mapError(
+ error =>
+ new Error(
+ `Failed to inspect ${targetLabel(adapter.target)} ${operation}: ${errorMessage(error)}. ${recoveryHint(adapter, setupOperation)}`
+ )
+ )
+ );
+
const requireInspection = <T>(
adapter: SetupTargetAdapter,
operation: string,
- result: CommandResult | undefined,
- parse: (output: string) => T | undefined
+ result: CommandResult,
+ parse: (output: string) => T | undefined,
+ setupOperation: SetupOperation
) => {
- if (!result) {
- return Effect.fail(new Error(`Failed to inspect ${adapter.target} ${operation}.`));
- }
if (result.exitCode !== 0) {
return Effect.fail(
- new Error(`Failed to inspect ${adapter.target} ${operation}${commandFailureSuffix(result)}.`)
+ new Error(
+ `Failed to inspect ${targetLabel(adapter.target)} ${operation}${commandFailureSuffix(result)}. ${recoveryHint(adapter, setupOperation)}`
+ )
);
}
const inspected = parse(result.stdout);
if (!inspected) {
- return Effect.fail(new Error(`${adapter.target} returned invalid JSON for ${operation}.`));
+ return Effect.fail(
+ new Error(
+ `${targetLabel(adapter.target)} returned invalid JSON while inspecting ${operation}. ${recoveryHint(adapter, setupOperation)}`
+ )
+ );
}
return Effect.succeed(inspected);
};
@@ -317,7 +451,8 @@ const inspectAdapter = (
readonly available: boolean;
readonly supported: boolean;
readonly version?: string;
- }
+ },
+ setupOperation: SetupOperation = 'setup'
) =>
Effect.gen(function* () {
const skillInstaller = yield* SetupSkillInstaller;
@@ -335,19 +470,27 @@ const inspectAdapter = (
}
if (!detection.supported) {
- return yield* Effect.fail(new Error(unsupportedCodexInspectionMessage()));
+ return yield* Effect.fail(new Error(unsupportedInspectionMessage(adapter)));
}
const [marketplaces, plugins] = yield* Effect.all([
- capture(adapter.executable, adapter.marketplaceListArgs),
- capture(adapter.executable, adapter.pluginListArgs),
+ captureInspection(adapter, adapter.marketplaceListArgs, 'marketplaces', setupOperation),
+ captureInspection(adapter, adapter.pluginListArgs, 'plugins', setupOperation),
]);
- const plugin = yield* requireInspection(adapter, 'plugins', plugins, output =>
- pluginState(adapter, output)
+ const plugin = yield* requireInspection(
+ adapter,
+ 'plugins',
+ plugins,
+ output => pluginState(adapter, output),
+ setupOperation
);
const pluginReady = plugin.installed && plugin.enabled;
- const marketplace = yield* requireInspection(adapter, 'marketplaces', marketplaces, output =>
- marketplaceState(adapter, output)
+ const marketplace = yield* requireInspection(
+ adapter,
+ 'marketplaces',
+ marketplaces,
+ output => marketplaceState(adapter, output),
+ setupOperation
);
let cliSkillReady = pluginReady;
if (adapter.skillSource === 'standalone') {
@@ -397,17 +540,32 @@ export const isSetupPluginReady = (status: SetupTargetStatus): boolean =>
export const isSetupReady = (status: SetupTargetStatus): boolean =>
isSetupPluginReady(status) && status.cli_skill_ready;
-const runRequired = (adapter: SetupTargetAdapter, args: ReadonlyArray<string>, operation: string) =>
+const runRequired = (
+ adapter: SetupTargetAdapter,
+ args: ReadonlyArray<string>,
+ operation: string,
+ setupOperation: SetupOperation
+) =>
Effect.gen(function* () {
const runner = yield* CommandRunner;
const result = yield* runner.capture(Command.make(adapter.executable, ...args)).pipe(
Effect.timeoutFail({
duration: SETUP_COMMAND_TIMEOUT,
onTimeout: () => new Error(`${operation} timed out after ${SETUP_COMMAND_TIMEOUT}.`),
- })
+ }),
+ Effect.mapError(
+ error =>
+ new Error(
+ `${operation} failed: ${errorMessage(error)}. ${recoveryHint(adapter, setupOperation)}`
+ )
+ )
);
if (result.exitCode !== 0) {
- return yield* Effect.fail(new Error(`${operation} failed${commandFailureSuffix(result)}`));
+ return yield* Effect.fail(
+ new Error(
+ `${operation} failed${commandFailureSuffix(result)}. ${recoveryHint(adapter, setupOperation)}`
+ )
+ );
}
});
@@ -441,14 +599,21 @@ const installAdapter = (adapter: SetupTargetAdapter, initial: InspectedSetupTarg
const repairStep = pluginRepairStep(adapter, initial);
if (repairStep) steps.push(repairStep);
for (const step of steps) {
- yield* runRequired(adapter, step.args, step.operation);
+ yield* runRequired(adapter, step.args, step.operation, 'setup');
}
const pluginChanged = steps.length > 0;
const skillInstaller = yield* SetupSkillInstaller;
let skillChanged = false;
if (adapter.skillSource === 'standalone' && !initial.cli_skill_ready) {
- skillChanged = yield* skillInstaller.ensureClaudeSkill;
+ skillChanged = yield* skillInstaller.ensureClaudeSkill.pipe(
+ Effect.mapError(
+ error =>
+ new Error(
+ `Installing the Claude Code CLI skill failed: ${errorMessage(error)}. ${recoveryHint(adapter, 'setup')}`
+ )
+ )
+ );
}
const final = yield* inspectAdapter(adapter);
@@ -480,7 +645,8 @@ const uninstallAdapter = (adapter: SetupTargetAdapter, initial: InspectedSetupTa
yield* runRequired(
adapter,
adapter.pluginUninstallArgs,
- `Uninstalling the ${adapter.target} plugin`
+ `Uninstalling the ${adapter.target} plugin`,
+ 'uninstall'
);
pluginChanged = true;
}
@@ -488,10 +654,17 @@ const uninstallAdapter = (adapter: SetupTargetAdapter, initial: InspectedSetupTa
const skillInstaller = yield* SetupSkillInstaller;
let skillChanged = false;
if (adapter.skillSource === 'standalone') {
- skillChanged = yield* skillInstaller.removeClaudeSkill;
+ skillChanged = yield* skillInstaller.removeClaudeSkill.pipe(
+ Effect.mapError(
+ error =>
+ new Error(
+ `Removing the Claude Code CLI skill failed: ${errorMessage(error)}. ${recoveryHint(adapter, 'uninstall')}`
+ )
+ )
+ );
}
- const final = yield* inspectAdapter(adapter);
+ const final = yield* inspectAdapter(adapter, undefined, 'uninstall');
if (final.plugin_installed) {
return yield* Effect.fail(
new Error(
@@ -541,12 +714,16 @@ export const detectSetupTargets = (target: SetupTarget) =>
export const inspectSetupTargets = (
detections: ReadonlyArray<SetupTargetDetection>,
- options: { readonly allowMarketplaceConflict?: boolean } = {}
+ options: {
+ readonly allowMarketplaceConflict?: boolean;
+ readonly operation?: SetupOperation;
+ } = {}
) =>
Effect.gen(function* () {
const inspected = yield* Effect.forEach(
detections.filter(detection => detection.available && detection.supported),
- detection => inspectAdapter(ADAPTERS[detection.target], detection)
+ detection =>
+ inspectAdapter(ADAPTERS[detection.target], detection, options.operation ?? 'setup')
);
if (!options.allowMarketplaceConflict) {
yield* Effect.forEach(inspected, status =>
diff --git a/ts/packages/cli/test/src/commands/setup.cmd.test.ts b/ts/packages/cli/test/src/commands/setup.cmd.test.ts
index 5519f0d0c..2f9db37a7 100644
--- a/ts/packages/cli/test/src/commands/setup.cmd.test.ts
+++ b/ts/packages/cli/test/src/commands/setup.cmd.test.ts
@@ -122,6 +122,7 @@ const makeFakeHosts = (
readonly noOp?: boolean;
readonly failOn?: string;
readonly malformedOn?: string;
+ readonly claudeJsonInspection?: boolean;
readonly codexJsonInspection?: boolean;
readonly codexVersion?: string;
readonly marketplaceSource?: Partial<Record<AgentHost, string>>;
@@ -164,12 +165,18 @@ const makeFakeHosts = (
: HOST_OUTPUT_FORMATTERS[host].version,
};
}
- if (command === 'codex plugin marketplace list --help') {
+ if (
+ command === `${host} plugin marketplace list --help` ||
+ command === `${host} plugin list --help`
+ ) {
+ const supportsJson =
+ host === 'claude'
+ ? options.claudeJsonInspection !== false
+ : options.codexJsonInspection !== false;
return {
- stdout:
- options.codexJsonInspection === false
- ? 'Usage: codex plugin marketplace list [OPTIONS]'
- : 'Usage: codex plugin marketplace list [OPTIONS]\n\n --json',
+ stdout: supportsJson
+ ? `Usage: ${command.replace(' --help', ' [OPTIONS]')}\n\n --json`
+ : `Usage: ${command.replace(' --help', ' [OPTIONS]')}`,
};
}
if (options.failOn && command.includes(options.failOn)) {
@@ -484,6 +491,46 @@ describe('CLI: composio setup', () => {
);
});
+ const autoCodexWithLegacyClaude = makeFakeHosts(
+ {
+ claude: { available: true },
+ codex: { available: true },
+ },
+ { claudeJsonInspection: false }
+ );
+ layer(TestLive({ commandRunner: autoCodexWithLegacyClaude.runner }))(
+ 'automatic setup with unsupported Claude and Codex',
+ it => {
+ it.scoped('installs Codex and reports that Claude was skipped', () =>
+ Effect.gen(function* () {
+ yield* cli(['setup', '--target', 'auto', '--yes']);
+
+ expect(autoCodexWithLegacyClaude.state.claude).toMatchObject({
+ marketplace: 'missing',
+ plugin: 'missing',
+ });
+ expect(autoCodexWithLegacyClaude.state.codex).toMatchObject({
+ marketplace: 'canonical',
+ plugin: 'enabled',
+ });
+ expect(
+ autoCodexWithLegacyClaude.commands.some(
+ parts => parts[0] === 'claude' && parts.includes('--json')
+ )
+ ).toBe(false);
+
+ const output = (yield* MockConsole.getLines()).join('\n');
+ expect(output).toContain('Claude Code and Codex detected.');
+ expect(output).toContain('Claude Code plugin setup skipped.');
+ expect(output).toContain('Run `claude update`');
+ expect(output).toContain(
+ 'Successfully installed and enabled the Composio plugin for Codex.'
+ );
+ })
+ );
+ }
+ );
+
const allTargets = makeFakeHosts({
claude: { available: true },
codex: { available: true },
@@ -525,7 +572,7 @@ describe('CLI: composio setup', () => {
});
expect(
partialAllTargets.commands.some(parts =>
- ['marketplace', 'install', 'enable'].some(operation => parts.includes(operation))
+ ['add', 'install', 'enable'].some(operation => parts.includes(operation))
)
).toBe(false);
})
@@ -914,6 +961,34 @@ describe('CLI: composio setup', () => {
{ codex: { available: true } },
{ codexJsonInspection: false, codexVersion: 'codex-cli 0.137.0' }
);
+
+ const legacyClaude = makeFakeHosts(
+ { claude: { available: true } },
+ { claudeJsonInspection: false }
+ );
+ layer(TestLive({ commandRunner: legacyClaude.runner }))(
+ 'Claude without JSON plugin inspection',
+ it => {
+ it.scoped('fails automatic setup with actionable update instructions', () =>
+ Effect.gen(function* () {
+ const exit = yield* Effect.exit(cli(['setup', '--target', 'auto', '--yes']));
+
+ expect(Exit.isFailure(exit)).toBe(true);
+ if (Exit.isFailure(exit)) {
+ const renderedCause = Cause.pretty(exit.cause);
+ expect(renderedCause).toContain('requires JSON plugin inspection');
+ expect(renderedCause).toContain('claude update');
+ }
+ expect(legacyClaude.commands.some(parts => parts.includes('--json'))).toBe(false);
+ expect(
+ legacyClaude.commands.some(parts =>
+ ['add', 'install', 'enable', 'uninstall'].some(operation => parts.includes(operation))
+ )
+ ).toBe(false);
+ })
+ );
+ }
+ );
layer(TestLive({ commandRunner: legacyCodex.runner }))(
'Codex without JSON marketplace inspection',
it => {
@@ -1053,7 +1128,9 @@ describe('CLI: composio setup', () => {
expect(Exit.isFailure(exit)).toBe(true);
if (Exit.isFailure(exit)) {
const renderedCause = Cause.pretty(exit.cause);
- expect(renderedCause).toContain('claude command timed out');
+ expect(renderedCause).toContain(
+ 'The `claude --version` command timed out after 2 minutes'
+ );
expect(renderedCause).not.toContain('not installed or not available on PATH');
}
})