Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

fix: onboarding feedback: stale CLI sign-in status, cloud machine choice (#987)

Laasya Bangalore5fd9e4fc481f
diff --git a/console/apps/switch-console-desktop/src/renderer/App.tsx b/console/apps/switch-console-desktop/src/renderer/App.tsx
index 4cc28fe8c..dc38bbdc5 100644
--- a/console/apps/switch-console-desktop/src/renderer/App.tsx
+++ b/console/apps/switch-console-desktop/src/renderer/App.tsx
@@ -2,6 +2,7 @@ import { QueryClientProvider } from '@tanstack/react-query';
import { BUILD_FEATURE_FLAGS } from '@shared/core/feature-flags/feature-flags';
import { AgentCrudEvents } from './app/agent-crud-events';
import { AppMenuEvents } from './app/app-menu-events';
+import { HostSetupEvents } from './app/host-setup-events';
import { Workspace } from './app/workspace';
import { ConsoleLinkListener } from './features/deeplinks/console-link-listener';
import { SessionDeeplinkListener } from './features/switch-rooms/session-deeplink-listener';
@@ -22,6 +23,7 @@ function AppContent() {
<WorkspaceViewProvider>
<AppMenuEvents />
<AgentCrudEvents />
+ <HostSetupEvents />
<SessionDeeplinkListener />
<ConsoleLinkListener />
<BridgePlatformsLoader />
diff --git a/console/apps/switch-console-desktop/src/renderer/app/host-setup-events.tsx b/console/apps/switch-console-desktop/src/renderer/app/host-setup-events.tsx
new file mode 100644
index 000000000..92b48d78d
--- /dev/null
+++ b/console/apps/switch-console-desktop/src/renderer/app/host-setup-events.tsx
@@ -0,0 +1,24 @@
+import { useQueryClient } from '@tanstack/react-query';
+import { useEffect } from 'react';
+import { SettledStepTracker } from '@renderer/features/remote-hosts/setup/settled-steps';
+import { invalidateHostProviderReadiness } from '@renderer/lib/components/provider-connection-status';
+import { events } from '@renderer/lib/ipc';
+import { hostSetupPlanEventChannel } from '@shared/core/remote-hosts/setup';
+
+/**
+ * Ask a host's providers' sign-in again when its setup finds something new.
+ * Setup runs from the host page, the hosts list and Add Agent's readiness
+ * probe; listening to the plan main pushes covers all of them.
+ */
+export function HostSetupEvents() {
+ const queryClient = useQueryClient();
+
+ useEffect(() => {
+ const tracker = new SettledStepTracker();
+ return events.on(hostSetupPlanEventChannel, (plan) => {
+ if (tracker.changed(plan)) void invalidateHostProviderReadiness(queryClient, plan.sshHost);
+ });
+ }, [queryClient]);
+
+ return null;
+}
diff --git a/console/apps/switch-console-desktop/src/renderer/features/cloud-agents/cloud-machine-state.test.ts b/console/apps/switch-console-desktop/src/renderer/features/cloud-agents/cloud-machine-state.test.ts
index 43a8dbf2b..ada4ac9b4 100644
--- a/console/apps/switch-console-desktop/src/renderer/features/cloud-agents/cloud-machine-state.test.ts
+++ b/console/apps/switch-console-desktop/src/renderer/features/cloud-agents/cloud-machine-state.test.ts
@@ -1,6 +1,6 @@
import { describe, expect, it } from 'vitest';
import type { CloudMachine } from '@shared/core/cloud-agents/cloud-agents';
-import { machinePresentation } from './cloud-machine-state';
+import { isMachineAsleep, machinePresentation } from './cloud-machine-state';
const sleepingMachine: CloudMachine = {
machine_id: '3f1c2b4a-0000-4000-8000-000000000001',
@@ -276,3 +276,15 @@ describe('machinePresentation actions', () => {
expect(present(input).actions).toEqual(actions);
});
});
+
+describe('isMachineAsleep', () => {
+ it.each([
+ ['sleeping stopped', machine({}), true],
+ ['error while sleeping', machine({ state: 'error', error_code: 'x' }), false],
+ ['retained while sleeping', machine({ desired_state: 'retained' }), false],
+ ['being deleted while sleeping', machine({ state: 'deleting' }), false],
+ ['running', machine(running), false],
+ ])('%s', (_name, input, asleep) => {
+ expect(isMachineAsleep(input, NOW)).toBe(asleep);
+ });
+});
diff --git a/console/apps/switch-console-desktop/src/renderer/features/cloud-agents/cloud-machine-state.ts b/console/apps/switch-console-desktop/src/renderer/features/cloud-agents/cloud-machine-state.ts
index f1c6435d9..8cc39090d 100644
--- a/console/apps/switch-console-desktop/src/renderer/features/cloud-agents/cloud-machine-state.ts
+++ b/console/apps/switch-console-desktop/src/renderer/features/cloud-agents/cloud-machine-state.ts
@@ -38,11 +38,24 @@ function isBeingDeleted(machine: CloudMachine, now: number): boolean {
);
}
+/**
+ * Asleep, as the machine card would say: a sleeping machine that is also being
+ * deleted, in error or retained is shown as that instead.
+ */
+export function isMachineAsleep(machine: CloudMachine, now: number): boolean {
+ return (
+ machine.sleeping &&
+ !isBeingDeleted(machine, now) &&
+ machine.state !== 'error' &&
+ !isRetained(machine)
+ );
+}
+
function machineLabel(machine: CloudMachine, now: number): string {
if (isBeingDeleted(machine, now)) return 'Deleting disk…';
if (machine.state === 'error') return 'Error';
if (isRetained(machine)) return 'Retained';
- if (machine.sleeping) return 'Sleeping';
+ if (isMachineAsleep(machine, now)) return 'Sleeping';
if (machine.desired_state === 'stopped')
return machine.state === 'stopped' ? 'Stopped' : 'Stopping…';
if (machine.state === 'ready') return 'Ready';
diff --git a/console/apps/switch-console-desktop/src/renderer/features/locations/components/add-agent-modal/managed-run-location-notice.tsx b/console/apps/switch-console-desktop/src/renderer/features/locations/components/add-agent-modal/managed-run-location-notice.tsx
index 1879b2fd6..680afb5ee 100644
--- a/console/apps/switch-console-desktop/src/renderer/features/locations/components/add-agent-modal/managed-run-location-notice.tsx
+++ b/console/apps/switch-console-desktop/src/renderer/features/locations/components/add-agent-modal/managed-run-location-notice.tsx
@@ -1,5 +1,5 @@
import type { AdvancedConfigValue } from '@switch-console/plugins/agents';
-import { useQuery } from '@tanstack/react-query';
+import { useQuery, useQueryClient } from '@tanstack/react-query';
import { CircleAlert, Server } from 'lucide-react';
import { useEffect, useMemo, useRef, useState } from 'react';
import {
@@ -8,6 +8,7 @@ import {
} from '@renderer/features/managed-agents/managed-agent-changes';
import { useAdvancedConfigSchema } from '@renderer/features/managed-agents/use-managed-agents';
import { InfoTooltip } from '@renderer/features/settings/components/InfoTooltip';
+import { invalidateHostProviderReadiness } from '@renderer/lib/components/provider-connection-status';
import { describeFailure, failureText } from '@renderer/lib/errors/describe-failure';
import { toast } from '@renderer/lib/hooks/use-toast';
import { rpc } from '@renderer/lib/ipc';
@@ -40,6 +41,7 @@ export function ManagedRunLocationNotice({
workspaceId: string;
onEnabled: () => void;
}) {
+ const queryClient = useQueryClient();
const [enabling, setEnabling] = useState(false);
const [autoTried, setAutoTried] = useState<string | null>(null);
const notice = newAgentMachineNotice(machine, { label, sshHost });
@@ -81,8 +83,12 @@ export function ManagedRunLocationNotice({
async function enable() {
setEnabling(true);
try {
- if (sshHost) await rpc.hostControllers.enable({ sshHost, serverId, workspaceId });
- else await rpc.embeddedController.enable({ serverId, workspaceId });
+ if (sshHost) {
+ await rpc.hostControllers.enable({ sshHost, serverId, workspaceId });
+ // Making it a machine puts Switch's shared host there, which is what
+ // checks a provider's sign-in on it.
+ void invalidateHostProviderReadiness(queryClient, sshHost);
+ } else await rpc.embeddedController.enable({ serverId, workspaceId });
onEnabled();
} catch (error) {
const { headline, detail } = describeFailure(
diff --git a/console/apps/switch-console-desktop/src/renderer/features/locations/components/add-agent-modal/new-agent-form.tsx b/console/apps/switch-console-desktop/src/renderer/features/locations/components/add-agent-modal/new-agent-form.tsx
index 50df38415..545e96e46 100644
--- a/console/apps/switch-console-desktop/src/renderer/features/locations/components/add-agent-modal/new-agent-form.tsx
+++ b/console/apps/switch-console-desktop/src/renderer/features/locations/components/add-agent-modal/new-agent-form.tsx
@@ -3,6 +3,7 @@ import { useQuery, useQueryClient } from '@tanstack/react-query';
import { Cloud, Monitor, Server } from 'lucide-react';
import { observer } from 'mobx-react-lite';
import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { isMachineAsleep } from '@renderer/features/cloud-agents/cloud-machine-state';
import { useCloudMachines } from '@renderer/features/cloud-agents/use-cloud-agents';
import { agentsStore } from '@renderer/features/locations/stores/agents-store';
import { getLocationManagerStore } from '@renderer/features/locations/stores/location-selectors';
@@ -148,6 +149,11 @@ export const NewAgentForm = observer(function NewAgentForm({
const cloudMachines = useCloudMachines(cloudOffered ? selectedServerId : null);
const cloudAvailable = cloudOffered && Array.isArray(cloudMachines.data);
const cloudNotSetUp = cloudOffered && cloudMachines.data === null;
+ // A sleeping machine is not listed as a machine of its own, so the Switch
+ // cloud entry says it is there: choosing it wakes it.
+ const cloudAsleep =
+ Array.isArray(cloudMachines.data) &&
+ cloudMachines.data.some((machine) => isMachineAsleep(machine, Date.now()));
const isCloudRun = runHost === 'cloud';
// Why the form moved off Switch cloud by itself, said under the picker.
const [cloudFallback, setCloudFallback] = useState<string | null>(null);
@@ -792,7 +798,9 @@ export const NewAgentForm = observer(function NewAgentForm({
<span className="flex-1">Switch cloud</span>
<span className="text-xs text-foreground-muted">
{cloudAvailable
- ? 'preview'
+ ? cloudAsleep
+ ? 'asleep, wakes when chosen'
+ : 'preview'
: cloudNotSetUp
? 'not set up on this server'
: 'checking…'}
diff --git a/console/apps/switch-console-desktop/src/renderer/features/remote-hosts/setup/settled-steps.test.ts b/console/apps/switch-console-desktop/src/renderer/features/remote-hosts/setup/settled-steps.test.ts
new file mode 100644
index 000000000..7f2def1eb
--- /dev/null
+++ b/console/apps/switch-console-desktop/src/renderer/features/remote-hosts/setup/settled-steps.test.ts
@@ -0,0 +1,76 @@
+import { describe, expect, it } from 'vitest';
+import type {
+ HostSetupPlan,
+ HostSetupStep,
+ HostSetupStepState,
+} from '@shared/core/remote-hosts/setup';
+import { SettledStepTracker } from './settled-steps';
+
+function step(id: string, state: HostSetupStepState, version: string | null = null): HostSetupStep {
+ return {
+ id,
+ kind: id === 'node' ? 'core-dependency' : 'agent-cli',
+ name: id,
+ state,
+ outcome: state === 'satisfied' ? 'satisfied' : state === 'pending' ? 'missing' : null,
+ version,
+ latestVersion: null,
+ updateAvailable: false,
+ error: null,
+ output: null,
+ optional: false,
+ dependsOn: [],
+ updatedAt: '2026-01-01T00:00:00.000Z',
+ };
+}
+
+function plan(sshHost: string, steps: HostSetupStep[]): HostSetupPlan {
+ return {
+ sshHost,
+ status: 'idle',
+ steps,
+ currentStepId: null,
+ createdAt: '2026-01-01T00:00:00.000Z',
+ updatedAt: '2026-01-01T00:00:00.000Z',
+ };
+}
+
+describe('SettledStepTracker', () => {
+ it('counts the first plan seen for a host, since nothing was known before it', () => {
+ const tracker = new SettledStepTracker();
+
+ expect(tracker.changed(plan('box', [step('node', 'satisfied', '22.0.0')]))).toBe(true);
+ });
+
+ it('counts an install that finished with the CLI in place', () => {
+ const tracker = new SettledStepTracker();
+ tracker.changed(plan('box', [step('claude', 'pending')]));
+
+ expect(tracker.changed(plan('box', [step('claude', 'installing')]))).toBe(false);
+ expect(tracker.changed(plan('box', [step('claude', 'satisfied', '2.1.0')]))).toBe(true);
+ });
+
+ it('ignores a re-check that found what was already known', () => {
+ const tracker = new SettledStepTracker();
+ const settled = [step('node', 'satisfied', '22.0.0'), step('claude', 'satisfied', '2.1.0')];
+ tracker.changed(plan('box', settled));
+
+ expect(tracker.changed(plan('box', [step('node', 'checking'), settled[1]!]))).toBe(false);
+ expect(tracker.changed(plan('box', settled))).toBe(false);
+ });
+
+ it('counts a new version as a change', () => {
+ const tracker = new SettledStepTracker();
+ tracker.changed(plan('box', [step('claude', 'satisfied', '2.1.0')]));
+
+ expect(tracker.changed(plan('box', [step('claude', 'satisfied', '2.2.0')]))).toBe(true);
+ });
+
+ it('keeps each host apart', () => {
+ const tracker = new SettledStepTracker();
+ tracker.changed(plan('box', [step('claude', 'satisfied', '2.1.0')]));
+
+ expect(tracker.changed(plan('other-box', [step('claude', 'satisfied', '2.1.0')]))).toBe(true);
+ expect(tracker.changed(plan('box', [step('claude', 'satisfied', '2.1.0')]))).toBe(false);
+ });
+});
diff --git a/console/apps/switch-console-desktop/src/renderer/features/remote-hosts/setup/settled-steps.ts b/console/apps/switch-console-desktop/src/renderer/features/remote-hosts/setup/settled-steps.ts
new file mode 100644
index 000000000..39846842e
--- /dev/null
+++ b/console/apps/switch-console-desktop/src/renderer/features/remote-hosts/setup/settled-steps.ts
@@ -0,0 +1,31 @@
+import { isStepInFlight, type HostSetupPlan } from '@shared/core/remote-hosts/setup';
+
+/**
+ * Remembers what each host's setup steps last settled on, and says when a
+ * plan settles one differently.
+ *
+ * A plan is pushed on every transition, "checking" and "installing" included,
+ * so reacting to each push would repeat whatever follows it several times per
+ * step. Only a finished check, install or update that found something new —
+ * Claude Code going from not installed to installed — counts.
+ */
+export class SettledStepTracker {
+ private readonly seen = new Map<string, Map<string, string>>();
+
+ /** Whether `plan` settles a step differently from the last plan seen for its host. */
+ changed(plan: HostSetupPlan): boolean {
+ let known = this.seen.get(plan.sshHost);
+ if (!known) {
+ known = new Map();
+ this.seen.set(plan.sshHost, known);
+ }
+ let changed = false;
+ for (const step of plan.steps) {
+ if (isStepInFlight(step)) continue;
+ const result = `${step.state}|${step.outcome ?? ''}|${step.version ?? ''}`;
+ if (known.get(step.id) !== result) changed = true;
+ known.set(step.id, result);
+ }
+ return changed;
+ }
+}
diff --git a/console/apps/switch-console-desktop/src/renderer/lib/components/provider-connection-status.test.ts b/console/apps/switch-console-desktop/src/renderer/lib/components/provider-connection-status.test.ts
new file mode 100644
index 000000000..0acd2e8ee
--- /dev/null
+++ b/console/apps/switch-console-desktop/src/renderer/lib/components/provider-connection-status.test.ts
@@ -0,0 +1,84 @@
+import type * as ReactQuery from '@tanstack/react-query';
+import React from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { beforeEach, expect, it, vi } from 'vitest';
+
+const query = vi.hoisted(() => ({ data: undefined as unknown, error: null as unknown }));
+vi.mock('@renderer/lib/ipc', () => ({ rpc: {} }));
+vi.mock('@tanstack/react-query', async (actual) => ({
+ ...(await actual<typeof ReactQuery>()),
+ useQuery: () => ({ data: query.data, error: query.error, isFetching: false }),
+ useMutation: () => ({ isSuccess: false, error: null, mutate: () => {} }),
+}));
+vi.mock('@shared/core/providers/agent-provider-registry', () => ({
+ getProvider: () => ({ name: 'Claude Code', loginCommand: 'claude auth login' }),
+}));
+
+const { QueryClient } = await import('@tanstack/react-query');
+const { ProviderConnectionStatus, invalidateHostProviderReadiness } =
+ await import('./provider-connection-status');
+
+const render = (compact: boolean) =>
+ renderToStaticMarkup(
+ React.createElement(ProviderConnectionStatus, {
+ providerId: 'claude',
+ sshHost: 'box',
+ dir: '',
+ compact,
+ })
+ );
+
+const NOT_SET_UP =
+ 'Switch is not set up on box yet, so Claude Code cannot be checked there. Start an agent on it.';
+
+beforeEach(() => {
+ query.data = undefined;
+ query.error = null;
+});
+
+it('gives the compact status the reason a sign-in could not be checked', () => {
+ query.data = { installed: true, status: 'unknown', message: NOT_SET_UP, models: [] };
+
+ const html = render(true);
+
+ expect(html).toContain('Sign-in not verified');
+ expect(html).toContain(`title="${NOT_SET_UP}"`);
+});
+
+it('does not suggest signing in when the check could not run', () => {
+ query.data = { installed: true, status: 'unknown', message: NOT_SET_UP, models: [] };
+
+ const html = render(false);
+
+ expect(html).toContain(NOT_SET_UP);
+ expect(html).not.toContain('claude auth login');
+});
+
+it('suggests signing in when the CLI says it is signed out', () => {
+ query.data = { installed: true, status: 'unauthenticated', message: 'Signed out', models: [] };
+
+ expect(render(false)).toContain('claude auth login');
+});
+
+it('gives no reason when signed in', () => {
+ query.data = { installed: true, status: 'authenticated', message: 'ok', models: [] };
+
+ const html = render(true);
+
+ expect(html).toContain('Signed in');
+ expect(html).not.toContain('title=');
+});
+
+it('asks again only the sign-in answers for the host whose setup changed', async () => {
+ const client = new QueryClient();
+ const box = ['provider-readiness', 'claude', 'box', ''];
+ const other = ['provider-readiness', 'claude', 'other-box', ''];
+ const local = ['provider-readiness', 'claude', null, '/home/me'];
+ for (const key of [box, other, local]) client.setQueryData(key, { status: 'unknown' });
+
+ await invalidateHostProviderReadiness(client, 'box');
+
+ expect(client.getQueryState(box)?.isInvalidated).toBe(true);
+ expect(client.getQueryState(other)?.isInvalidated).toBe(false);
+ expect(client.getQueryState(local)?.isInvalidated).toBe(false);
+});
diff --git a/console/apps/switch-console-desktop/src/renderer/lib/components/provider-connection-status.tsx b/console/apps/switch-console-desktop/src/renderer/lib/components/provider-connection-status.tsx
index 8b5b8b268..0fa5a158a 100644
--- a/console/apps/switch-console-desktop/src/renderer/lib/components/provider-connection-status.tsx
+++ b/console/apps/switch-console-desktop/src/renderer/lib/components/provider-connection-status.tsx
@@ -1,9 +1,28 @@
-import { useMutation, useQuery } from '@tanstack/react-query';
+import { useMutation, useQuery, type QueryClient } from '@tanstack/react-query';
import { Check, CheckCircle2, CircleAlert, Copy, Loader2, RefreshCw } from 'lucide-react';
import { rpc } from '@renderer/lib/ipc';
import { Button } from '@renderer/lib/ui/button';
import { getProvider, type AgentProviderId } from '@shared/core/providers/agent-provider-registry';
+function providerReadinessQueryKey(
+ providerId: AgentProviderId,
+ sshHost: string | null,
+ dir: string
+) {
+ return ['provider-readiness', providerId, sshHost, dir] as const;
+}
+
+/**
+ * Ask every provider's sign-in on one SSH host again: its setup changed, so an
+ * answer read before — "CLI not installed", "Switch is not set up there" —
+ * would otherwise stand for as long as it is cached.
+ */
+export function invalidateHostProviderReadiness(queryClient: QueryClient, sshHost: string) {
+ return queryClient.invalidateQueries({
+ predicate: ({ queryKey }) => queryKey[0] === 'provider-readiness' && queryKey[2] === sshHost,
+ });
+}
+
/**
* Whether a provider's CLI is installed and signed in on a machine. One check
* per provider, machine and directory, shared by every component that asks:
@@ -17,7 +36,7 @@ export function useProviderReadiness(
enabled: boolean
) {
return useQuery({
- queryKey: ['provider-readiness', providerId, sshHost, dir],
+ queryKey: providerReadinessQueryKey(providerId, sshHost, dir),
queryFn: () => rpc.agents.providerReadiness({ providerId, sshHost, dir }),
// Signing in is not something that changes minute to minute, and this is
// rendered once per provider tile and once per agent row — so a short
@@ -75,13 +94,29 @@ export function ProviderConnectionStatus({
? 'Backend connected'
: 'Signed in'
: 'Sign-in not verified';
+ const reason =
+ checking || ready
+ ? null
+ : query.error
+ ? 'Could not reach this host. Check the connection and try again.'
+ : data?.status === 'unauthenticated'
+ ? 'Sign in to use this provider.'
+ : (data?.message ?? null);
+ // Only a CLI that answered "signed out" (or "no backend") is fixed by its
+ // login command. An unknown status means the check itself could not run,
+ // and the reason says what to do instead.
+ const loginMayHelp = data?.status === 'unauthenticated' || data?.status === 'unconfigured';
const Icon = checking ? Loader2 : ready ? CheckCircle2 : CircleAlert;
const tone = checking || ready ? 'text-foreground-muted' : 'text-foreground-warning';
if (compact)
return (
- <span className={`inline-flex items-center gap-1.5 text-xs ${tone}`}>
+ <span
+ className={`inline-flex items-center gap-1.5 text-xs ${tone}`}
+ title={reason ?? undefined}
+ >
<Icon className={`size-3.5 ${checking ? 'animate-spin' : ''}`} />
{headline}
+ {reason && <span className="sr-only">: {reason}</span>}
</span>
);
return (
@@ -107,16 +142,8 @@ export function ProviderConnectionStatus({
{sshHost ? `On ${sshHost}` : 'On this computer'}
{data?.installed === true ? ' · CLI installed' : ''}
</p>
- {!checking && !ready && (
- <p className="mt-2 text-foreground-muted">
- {query.error
- ? 'Could not reach this host. Check the connection and try again.'
- : data?.status === 'unauthenticated'
- ? 'Sign in to use this provider.'
- : data?.message}
- </p>
- )}
- {!checking && data?.installed && !ready && provider && (
+ {reason && <p className="mt-2 text-foreground-muted">{reason}</p>}
+ {!checking && data?.installed && loginMayHelp && provider && (
<div className="mt-2 space-y-1">
<p>Run in a terminal {sshHost ? `on ${sshHost}` : 'on this computer'}, then Recheck:</p>
<div className="flex items-center gap-2 rounded bg-background px-2 py-1">
diff --git a/console/packages/plugins/src/switch-skill/SKILL.md b/console/packages/plugins/src/switch-skill/SKILL.md
index 515a9b3be..548532ce7 100644
--- a/console/packages/plugins/src/switch-skill/SKILL.md
+++ b/console/packages/plugins/src/switch-skill/SKILL.md
@@ -841,10 +841,22 @@ sentence saying so: relay it to the person asking ("ask my owner to enable
**Use it when you are asked for a new agent**, or when a job needs one that
does not exist yet and the person agrees. Before calling `create_agent`,
-check `list_machines` for a machine that is `online` with the provider
-installed and `auth` not `missing` or `expired`, then **propose the name,
-machine, provider and what the agent is for, and get explicit confirmation**:
-it starts a real agent on someone's computer.
+check `list_machines` for a machine that is `online` (or a sleeping cloud
+machine, below) with the provider installed and `auth` not `missing` or
+`expired`, then **propose the name, machine, provider and what the agent is
+for, and get explicit confirmation**: it starts a real agent on someone's
+computer. Ask which machine rather than picking one: an agent on a person's
+computer answers only while it is on, and a cloud machine (`kind` "ec2") keeps
+running when that computer is off.
+
+A cloud machine sleeps when nothing has used it for a while, and then shows
+`offline`. It can still take the agent: `create_agent` wakes it, judging the
+provider by the machine's last report, and the agent starts once the machine
+is up. Say in the proposal that this takes a few minutes, and when checking
+that it came up (below), allow up to ten. A cloud machine its owner stopped is
+not woken: `create_agent` is refused with `controller_offline`. A workspace
+that never used a cloud machine has none listed; the person sets one up by
+choosing Switch cloud in Switch Console's New agent.
**Relay a refusal as it is.** When the machine cannot take the agent, nothing
is created and the error says why, with a reason code: `controller_offline`
diff --git a/core/switch_core/connections/catalog/atlassian/connection.yaml b/core/switch_core/connections/catalog/atlassian/connection.yaml
index 8201eeacd..202d3dcb9 100644
--- a/core/switch_core/connections/catalog/atlassian/connection.yaml
+++ b/core/switch_core/connections/catalog/atlassian/connection.yaml
@@ -29,11 +29,13 @@ mcp:
- { name: atlassian, url: "https://mcp.atlassian.com/v2/mcp" }
access:
# The identity scopes are needed for consent; search:jira carries JQL search
- # and search:confluence CQL search. Atlassian hides the write tools from a
- # read-only sign-in. Not asked for: Rovo's cross-product search
- # (search:rovo) and Teamwork Graph (read:all:twg), whose every call spends
- # the organization's Rovo credits. Four Confluence write tools (infographics
- # and apps on a page) spend them too, 15-30 credits a request.
+ # and search:confluence CQL search. A read-only sign-in still lists
+ # executeWrite and executeDestructive; Atlassian leaves write operations out
+ # of discover and reports the products read-only. Not asked for: Rovo's
+ # cross-product search (search:rovo) and Teamwork Graph (read:all:twg),
+ # whose every call spends the organization's Rovo credits. Four Confluence
+ # write tools (infographics and apps on a page) spend them too, 15-30
+ # credits a request.
read:
scopes:
- read:me
diff --git a/core/switch_core/connections/catalog/atlassian/skill/SKILL.md b/core/switch_core/connections/catalog/atlassian/skill/SKILL.md
index fabf426e9..770b05a5c 100644
--- a/core/switch_core/connections/catalog/atlassian/skill/SKILL.md
+++ b/core/switch_core/connections/catalog/atlassian/skill/SKILL.md
@@ -17,9 +17,11 @@ set up or renew.
- **Jira and Confluence only.** Atlassian's other apps are not part of this
connection. If Confluence tools are missing, your owner connected before
Confluence was added and has to connect Atlassian again.
-- **Read or write is your owner's choice, made when they connected.** If they
- connected for reading only, Atlassian hides the write tools and refuses
- writes: tell the user that, rather than looking for another way.
+- **Read or write is your owner's choice, made when they connected.**
+ `getAccessibleAtlassianResources` reports each product's access, read-only or
+ not. On a read-only connection `executeWrite` and `executeDestructive` are
+ still listed, but `discover` returns no write operations: tell the user you
+ can only read, rather than looking for another way.
- When a tool is refused, tell the user what you could not do. If Switch says
the grant was removed or the connection must be reconnected, your owner has
to do that.
diff --git a/core/switch_core/official_templates/switch-buddy/AGENT.md b/core/switch_core/official_templates/switch-buddy/AGENT.md
index 057328665..a705222bb 100644
--- a/core/switch_core/official_templates/switch-buddy/AGENT.md
+++ b/core/switch_core/official_templates/switch-buddy/AGENT.md
@@ -112,9 +112,33 @@ you can, once they say yes:
**Always propose first and wait for a yes.** Say what you will create: the name, where it
runs and in which folder, which AI provider, what it is for, who can talk to it, and
-whether it asks before acting (below). Creating an agent starts a real process on their computer; creating a room
+whether it asks before acting (below). Creating an agent starts a real process on the machine it runs on; creating a room
may create a channel in their team's chat. Never do either off your own judgement.
+### Where it runs (which machine)
+
+Don't choose the machine for them. On Switch Cloud they usually have two: their own
+computer and their cloud machine (`kind` "ec2" in `list_machines`). Ask in the proposal,
+in plain words: "Should it run on your computer, or on Switch Cloud so it keeps working
+when your computer is off?" An agent on their computer answers only while that computer
+is on and Switch Console is open; an agent people rely on (a daily digest, a team's
+tracker) usually belongs on the cloud machine.
+
+- **The cloud machine shows `offline`:** it sleeps when nothing has used it for a while.
+ You can still create the agent there: creating it wakes the machine, and the agent starts
+ once the machine is up, which takes a few minutes. Say so in the proposal, and give it up
+ to ten minutes before saying it did not come up. If creating it is refused as offline,
+ they stopped the machine themselves: ask them to press **Start** on its card under
+ [your agents](switchdash://open/agents), then try again.
+- **No cloud machine is listed:** a workspace that never used one has none yet. Ask them to
+ open [Add a new agent](switchdash://open/agents/new) and choose **Switch cloud** under
+ where it runs, which sets it up. Then ask again, and create the agent once `list_machines`
+ shows it.
+- **Only their computer is listed and they're on Switch Cloud:** say the cloud machine is
+ an option before proposing their computer.
+- On a server Switch Console runs, or one with no cloud machines, their computers are the
+ only choice: don't mention the cloud.
+
### Where it works (its folder)
An agent on their own computer can work in a folder they already have: a codebase, their
diff --git a/docs/design/service-connections-v2.md b/docs/design/service-connections-v2.md
index 8e875847b..5e5f5e553 100644
--- a/docs/design/service-connections-v2.md
+++ b/docs/design/service-connections-v2.md
@@ -437,7 +437,9 @@ settings:
Atlassian matches the loopback port exactly, hence the five fixed ports.
- Consenting to Jira's scopes alone fails after Accept unless the request also
carries the identity scopes, `offline_access` and `prompt=consent`. Atlassian
- enforces the result: a read-only sign-in hides the write tools.
+ reflects the result: a read-only sign-in still lists `executeWrite` and
+ `executeDestructive`, but `discover` returns no write operations and
+ `getAccessibleAtlassianResources` reports each product as read-only.
- Access tokens live 8 hours; refresh tokens rotate.
- The default server lists a few tools, `discover`, and `executeRead`,
`executeWrite` and `executeDestructive`; those pass through unchanged.