fix(cli): bound, trace, and explain the requests the CLI makes (#6798)

* fix(cli): bound, trace, and explain the requests the CLI makes

Four transport gaps, all of which failed silently.

A request had no timeout, so a connection that was accepted and then never
answered hung the terminal indefinitely. `SIM_TIMEOUT_SECONDS` now bounds
one, defaulting to 3600s — deliberately above every timeout the server
itself applies, since a synchronous workflow run is allowed 3000s on a paid
plan and a tighter default would abort real work and report it as a
transport failure. `0` removes the bound, for a self-hosted deployment that
runs executions without one of its own. The caller's abort signal is
composed with the timeout rather than replaced, so neither masks the other.

Node ignores HTTP(S)_PROXY unless NODE_USE_ENV_PROXY opts in, and only from
v22.21 and v24.5, so on a network that reaches the API only through a proxy
every command failed to connect while the variable that would have fixed it
was already set. The CLI cannot enable that from inside the process — Node
reads it at startup — so it says what to do rather than bundling an HTTP
stack for a setting the platform now owns.

An API key was sent to any http:// endpoint with no signal. Now a warning,
not a refusal: http is the documented way to reach a local dev server, and
a deployment terminating TLS at a gateway is real. Loopback stays silent.

`SIM_DEBUG=1` traces method, URL, status and duration. Bodies and headers
are deliberately absent — the request carries the API key, and `secrets set`
carries the secret itself.

All four write to stderr, so a piped stdout stays parseable.

* fix(cli): make the request bound safe on every runtime it supports

Two ways the new timeout could fail before the request was made.

`AbortSignal.any` arrived in Node 20.3 and this package supports Node 20, so
composing a caller's abort signal with the timeout threw a bare TypeError on
the earliest 20.x releases. It is now used when present and composed through
an AbortController when not.

`AbortSignal.timeout` rejects a fractional millisecond outright, and past
2^31-1 ms it does not fail at all — it clamps to 1ms, so the longest timeout
anyone asked for became the shortest. The value is now rounded and refused
above what Node can actually wait, pointing at 0 for an unbounded wait.

Also unstubs env vars between tests: `stubEnv` is not undone by
`unstubAllGlobals`, so a SIM_TIMEOUT_SECONDS set for one test configured
every test after it.

* fix(cli): correct the proxy version table, and classify a timeout mid-body

`runtimeCanProxy` treated any release between 22 and 24 as capable, so on
Node 23 — which reached end of life before the backport — a configured proxy
was ignored and the CLI stayed silent about it, which is the exact failure
the warning exists to report. The table is now the two lines that shipped the
support, and anything after them.

`AbortSignal.timeout` keeps firing after `fetch` resolves, so a bound that
elapsed while the body was still being read — a large `files get` — escaped
the client's own handling and printed a raw TimeoutError stack. The top-level
handler now names it, which covers the streaming path as well as the JSON
one. A user's own Ctrl-C raises AbortError and is deliberately left alone.

* fix(cli): report a timed-out download as a timeout

`files get --output-file` streams the body to disk, and `streamToFile`
converted anything the stream threw into a write failure. So a request bound
elapsing mid-download read as `Could not write <path>: ...`, sending the
reader to check permissions and free space for a timeout they can raise, and
hiding the one instruction that resolves it.

The predicate and that instruction now live beside the timeout that raises
them, so the client, the top-level handler and the download path all say the
same thing. The wrapping stays where it is: the staged-download cleanup runs
off that failure, and rethrowing past it would leak the temporary directory.

* fix(cli): keep a sub-millisecond timeout bounded

Zero is how this function says "no bound", so rounding a positive
SIM_TIMEOUT_SECONDS down to zero inverted the request: anything under
0.0005s asked for the shortest possible timeout and got none at all, leaving
a stalled request to hang. Introduced by the rounding that fixed the
fractional-millisecond rejection.

Floored at 1ms for every positive value; only a literal 0 still disables.

Author: waleedlatif1

apps/docs/content/docs/en/cli/configuration.mdx

@@ -101,6 +101,12 @@ credentials. The `default` profile is `[default]` in both.
 | `SIM_CONFIG_DIR` | Relocate both files away from `~/.sim` |
 | `SIM_CONFIG_FILE` | Relocate only the config file |
 | `SIM_CREDENTIALS_FILE` | Relocate only the credentials file |
+| `SIM_TIMEOUT_SECONDS` | Per-request timeout; `0` waits indefinitely. Defaults to `3600`, above every timeout the server itself applies |
+| `SIM_DEBUG` | Trace each request's method, URL, status and duration to stderr |
+
+Node ignores `HTTPS_PROXY` unless you also set `NODE_USE_ENV_PROXY=1`, and only
+from Node 22.21 and 24.5. The CLI warns when a proxy is configured but will not
+be used.
 
 For CI, set `SIM_API_KEY` and `SIM_WORKSPACE` and nothing needs to touch the
 filesystem at all.

packages/sim-cli/README.md

@@ -57,6 +57,11 @@ Each setting resolves independently, first match wins:
 | --- | --- |
 | 1 | Command-line flag (`--endpoint`, `--workspace`, `--output`) |
 | 2 | Environment (`SIM_ENDPOINT`, `SIM_API_KEY`, `SIM_WORKSPACE`, `SIM_OUTPUT`) |
+
+`SIM_TIMEOUT_SECONDS` bounds each request (default `3600`, `0` waits
+indefinitely) and `SIM_DEBUG=1` traces requests to stderr. Node ignores
+`HTTPS_PROXY` unless `NODE_USE_ENV_PROXY=1` is also set, on Node 22.21+ or
+24.5+; the CLI warns when a proxy is configured but will not be used.
 | 3 | `~/.sim/config` / `~/.sim/credentials` for the selected profile |
 | 4 | Built-in default (`https://www.sim.ai`, `table`) |
 

packages/sim-cli/src/commands/protocol/files-get.test.ts

@@ -67,6 +67,16 @@ function failingBody(): ReadableStream<Uint8Array> {
   })
 }
 
+/** What `fetch` does to a body when the request's own timeout elapses. */
+function timedOutBody(): ReadableStream<Uint8Array> {
+  return new ReadableStream({
+    start(controller) {
+      controller.enqueue(new TextEncoder().encode('partial'))
+      controller.error(new DOMException('The operation was aborted due to timeout', 'TimeoutError'))
+    },
+  })
+}
+
 function program(): Command {
   const root = new Command('sim').exitOverride()
   for (const group of buildGeneratedCommands()) root.addCommand(group)
@@ -81,6 +91,23 @@ describe('streamToFile', () => {
     expect(existsSync(target)).toBe(true)
   })
 
+  it('reports an elapsed request bound as a timeout, not as a failed write', async () => {
+    // The stream is torn down by the request's own timeout, which is not a
+    // disk problem: calling it "could not write" sent the reader to check
+    // permissions and free space for a bound they can raise.
+    const target = join(dir, 'out.txt')
+    await expect(
+      streamToFile(timedOutBody(), createWriteStream(target, { flags: 'wx' }))
+    ).rejects.toThrow(/SIM_TIMEOUT_SECONDS/)
+  })
+
+  it('still reports a genuine write failure as one', async () => {
+    const target = join(dir, 'out.txt')
+    await expect(
+      streamToFile(failingBody(), createWriteStream(target, { flags: 'wx' }))
+    ).rejects.toThrow(/Could not write/)
+  })
+
   it('refuses to clobber an existing file, naming --force', async () => {
     const target = join(dir, 'out.txt')
     writeFileSync(target, 'precious')

packages/sim-cli/src/commands/protocol/files-get.ts

@@ -7,10 +7,17 @@ import { pipeline } from 'node:stream/promises'
 import type { Command } from 'commander'
 import { clientFrom } from '../../context'
 import { V2_OPERATIONS } from '../../generated/v2-api'
-import { resolvePath, SimApiError } from '../../http/client'
+import { isRequestTimeout, RAISE_TIMEOUT_HINT, resolvePath, SimApiError } from '../../http/client'
 import { printProtocolResult } from './result'
 
 function writeFailure(path: WriteStream['path'], error: unknown): SimApiError {
+  // A body torn down by the request's own bound is not a disk problem. Calling
+  // it "could not write" sent the reader to check permissions and free space
+  // for a timeout they can raise, and hid the one instruction that resolves it.
+  if (isRequestTimeout(error)) {
+    return new SimApiError(`Downloading ${path} timed out. ${RAISE_TIMEOUT_HINT}`, 0)
+  }
+
   const code = (error as NodeJS.ErrnoException).code
   if (code === 'EEXIST') {
     return new SimApiError(

packages/sim-cli/src/http/client.test.ts

@@ -1,6 +1,7 @@
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { CLI_CONTRACT } from '../contract/commands'
 import { V2_OPERATIONS, type V2OperationName } from '../generated/v2-api'
+import { sleep } from '../helpers'
 import { USER_AGENT } from '../version'
 import {
   formatApiErrorDetails,
@@ -13,6 +14,9 @@ import {
 
 afterEach(() => {
   vi.unstubAllGlobals()
+  // `stubEnv` is not undone by `unstubAllGlobals`, so a SIM_TIMEOUT_SECONDS or
+  // SIM_DEBUG set for one test would otherwise configure every test after it.
+  vi.unstubAllEnvs()
 })
 
 function client(options: { apiKey?: string } = { apiKey: 'key' }): SimClient {
@@ -314,6 +318,168 @@ describe('non-JSON responses', () => {
   })
 })
 
+describe('a request that never answers', () => {
+  it('bounds a request by default, above every timeout the server itself applies', async () => {
+    // A synchronous workflow run is allowed 3000s on a paid plan, so a tighter
+    // default would abort real work and report it as a transport failure. What
+    // this catches is a connection that is accepted and then never answers.
+    const fetchMock = vi.fn().mockResolvedValue(
+      new Response(JSON.stringify({ data: [] }), {
+        status: 200,
+        headers: { 'content-type': 'application/json' },
+      })
+    )
+    vi.stubGlobal('fetch', fetchMock)
+
+    await client().request('/api/v2/workflows')
+
+    const signal = fetchMock.mock.calls[0][1].signal as AbortSignal
+    expect(signal).toBeInstanceOf(AbortSignal)
+    expect(signal.aborted).toBe(false)
+  })
+
+  it('sends no signal at all when the bound is switched off', async () => {
+    // A self-hosted deployment can run executions without a timeout of its own,
+    // and there the client must not invent one.
+    vi.stubEnv('SIM_TIMEOUT_SECONDS', '0')
+    const fetchMock = vi.fn().mockResolvedValue(
+      new Response(JSON.stringify({ data: [] }), {
+        status: 200,
+        headers: { 'content-type': 'application/json' },
+      })
+    )
+    vi.stubGlobal('fetch', fetchMock)
+
+    await client().request('/api/v2/workflows')
+    expect(fetchMock.mock.calls[0][1].signal).toBeUndefined()
+  })
+
+  it('refuses a timeout that is not a number, naming the variable', async () => {
+    vi.stubEnv('SIM_TIMEOUT_SECONDS', 'soon')
+    vi.stubGlobal('fetch', vi.fn())
+
+    await expect(client().request('/api/v2/workflows')).rejects.toThrow(
+      /Invalid SIM_TIMEOUT_SECONDS "soon"/
+    )
+  })
+
+  it('rounds a fractional millisecond rather than letting the timer reject it', async () => {
+    // `AbortSignal.timeout` rejects a non-integer delay outright, so an
+    // unrounded 0.0005s threw ERR_OUT_OF_RANGE before the request was made.
+    vi.stubEnv('SIM_TIMEOUT_SECONDS', '0.0005')
+    const fetchMock = vi.fn().mockResolvedValue(
+      new Response(JSON.stringify({ data: [] }), {
+        status: 200,
+        headers: { 'content-type': 'application/json' },
+      })
+    )
+    vi.stubGlobal('fetch', fetchMock)
+
+    await expect(client().request('/api/v2/workflows')).resolves.toBeDefined()
+  })
+
+  it('keeps a bound below half a millisecond bounded, rather than disabling it', async () => {
+    // Zero means "no bound", so rounding a positive value down to zero inverted
+    // the request: the shortest timeout anyone could ask for became none.
+    vi.stubEnv('SIM_TIMEOUT_SECONDS', '0.0004')
+    const fetchMock = vi.fn().mockResolvedValue(
+      new Response(JSON.stringify({ data: [] }), {
+        status: 200,
+        headers: { 'content-type': 'application/json' },
+      })
+    )
+    vi.stubGlobal('fetch', fetchMock)
+
+    await client().request('/api/v2/workflows')
+    expect(fetchMock.mock.calls[0][1].signal).toBeInstanceOf(AbortSignal)
+  })
+
+  it('refuses a delay longer than Node can wait, which would silently become 1ms', async () => {
+    // Past 2^31-1 ms Node does not fail — it clamps to 1ms, so the request the
+    // caller asked to wait longest for would be the first one aborted.
+    vi.stubEnv('SIM_TIMEOUT_SECONDS', String(2 ** 31))
+    vi.stubGlobal('fetch', vi.fn())
+
+    await expect(client().request('/api/v2/workflows')).rejects.toThrow(/longer than Node can wait/)
+  })
+
+  it('composes the caller signal with the timeout without AbortSignal.any', async () => {
+    // `AbortSignal.any` arrived in Node 20.3 and this package supports Node 20,
+    // so the earliest 20.x releases would have thrown a bare TypeError here.
+    const original = AbortSignal.any
+    // biome-ignore lint/performance/noDelete: restoring the property is the point
+    delete (AbortSignal as { any?: unknown }).any
+    const controller = new AbortController()
+    const fetchMock = vi.fn().mockResolvedValue(
+      new Response(JSON.stringify({ data: [] }), {
+        status: 200,
+        headers: { 'content-type': 'application/json' },
+      })
+    )
+    vi.stubGlobal('fetch', fetchMock)
+
+    try {
+      await client().request('/api/v2/workflows', { signal: controller.signal })
+      const sent = fetchMock.mock.calls[0][1].signal as AbortSignal
+      expect(sent.aborted).toBe(false)
+      controller.abort()
+      expect(sent.aborted).toBe(true)
+    } finally {
+      ;(AbortSignal as { any?: unknown }).any = original
+    }
+  })
+
+  it('explains a timeout as a timeout, not as an unreachable endpoint', async () => {
+    vi.stubEnv('SIM_TIMEOUT_SECONDS', '0.001')
+    vi.stubGlobal(
+      'fetch',
+      vi.fn().mockImplementation(async (_url: string, init: RequestInit) => {
+        await sleep(20)
+        init.signal?.throwIfAborted()
+        return new Response('{}')
+      })
+    )
+
+    await expect(client().request('/api/v2/workflows')).rejects.toThrow(/did not answer within/)
+  })
+})
+
+describe('tracing a request', () => {
+  it('traces method, url, status and duration when asked, and nothing otherwise', async () => {
+    const response = () =>
+      new Response(JSON.stringify({ data: [] }), {
+        status: 200,
+        headers: { 'content-type': 'application/json' },
+      })
+
+    const quiet = stubStderr(false)
+    try {
+      vi.stubGlobal('fetch', vi.fn().mockResolvedValue(response()))
+      await client().request('/api/v2/workflows')
+    } finally {
+      quiet.restore()
+    }
+    expect(quiet.writes).toEqual([])
+
+    vi.stubEnv('SIM_DEBUG', '1')
+    const traced = stubStderr(false)
+    try {
+      vi.stubGlobal('fetch', vi.fn().mockResolvedValue(response()))
+      await client().request('/api/v2/workflows')
+    } finally {
+      traced.restore()
+    }
+
+    const line = traced.writes.join('')
+    expect(line).toContain('GET https://sim.example/api/v2/workflows')
+    expect(line).toContain('200')
+    expect(line).toMatch(/\d+ms/)
+    // The request carries the API key, and `secrets set` carries the secret
+    // itself, so a trace must never include headers or bodies.
+    expect(line).not.toContain('key')
+  })
+})
+
 describe('request identity', () => {
   it('identifies the CLI, its version and its runtime to the API', async () => {
     // Without a User-Agent a CLI request is indistinguishable from any other
@@ -597,14 +763,21 @@ describe('raw requests', () => {
       'https://sim.example/api/v2/chat',
       expect.objectContaining({
         method: 'POST',
-        signal: controller.signal,
         headers: expect.objectContaining({
           accept: 'text/event-stream',
           'content-type': 'application/json',
           'x-api-key': 'key',
         }),
       })
     )
+
+    // The signal is composed with the request timeout, so it is no longer the
+    // caller's object. What has to hold is the behaviour: aborting the
+    // caller's controller still aborts the request.
+    const sent = fetch.mock.calls[0][1].signal as AbortSignal
+    expect(sent.aborted).toBe(false)
+    controller.abort()
+    expect(sent.aborted).toBe(true)
   })
 
   it('turns an aborted fetch into a clean CLI error', async () => {