pi-commandcode-provider 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## Unreleased
+
+## 0.4.0 - 2026-06-02
+
+- Add retry mechanism for transient HTTP errors (429, 5xx) and stream-level errors, configurable via pi `settings.json` `retry.provider` fields (`timeoutMs`, `maxRetries`, `maxRetryDelayMs`). Supports exponential backoff with jitter and `Retry-After` header.
+
 ## 0.3.1 - 2026-05-29
 
 - Bump CLI version header to `0.29.0` for Command Code API parity.

package/RELEASE.md

@@ -7,7 +7,8 @@ Recommended flow:
 - publish prereleases with the `next` dist-tag
 - smoke-test the npm package directly in pi
 - publish stable releases with the `latest` dist-tag
-- commit and tag the stable release
+- commit the release on a branch, open a PR, and merge after CI passes
+- tag the stable release on `main` after merge
 - comment on the related PR or issue after shipping
 
 ## Prerelease flow
@@ -144,21 +145,41 @@ npm pack --dry-run
 git diff --check
 ```
 
-Commit and tag:
+Commit on a release branch and open a PR:
 
 ```sh
+git checkout -b release/0.1.1
 git add .
 git commit -m "Release 0.1.1"
+git push origin release/0.1.1
+gh pr create --title "chore(release): publish 0.1.1" --base main
+```
+
+`main` is branch-protected. The release must go through a PR with passing CI.
+
+Once CI passes, approve and merge:
+
+```sh
+gh pr review <number> --approve
+gh pr merge <number> --squash --delete-branch
+```
+
+After merge, pull `main` and tag locally:
+
+```sh
+git checkout main
+git pull origin main
 git tag -a v0.1.1 -m "Release 0.1.1"
+git push origin v0.1.1
 ```
 
-Publish stable:
+Publish stable locally:
 
 ```sh
 npm publish --tag latest --access public
 ```
 
-If npm asks for browser or OTP auth, run the publish command manually and complete the npm prompt.
+Publishing is intentionally manual/local; there is no GitHub Actions publish workflow. If npm asks for browser or OTP auth, complete the npm prompt locally.
 
 Verify npm:
 
@@ -172,13 +193,6 @@ Expected:
 - `latest` points to the stable version
 - the stable version exists on npm
 
-Push commit and tag:
-
-```sh
-git push origin main
-git push origin v0.1.1
-```
-
 ## GitHub follow-up
 
 Comment on the related PR and issue after publishing and pushing:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-commandcode-provider",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "pi custom provider for Command Code API (commandcode.ai)",
   "type": "module",
   "keywords": [
@@ -28,7 +28,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "npm run typecheck && tsx tests/test-pure-functions.ts && tsx tests/test-models.ts && tsx tests/test-pricing.ts && tsx tests/test-oauth.ts && tsx tests/test-abort.ts && tsx tests/test-stream.ts && node tests/test-pi-local.mjs && node tests/test-omp-compat.mjs",
+    "test": "npm run typecheck && tsx tests/test-pure-functions.ts && tsx tests/test-models.ts && tsx tests/test-pricing.ts && tsx tests/test-oauth.ts && tsx tests/test-abort.ts && tsx tests/test-stream.ts && tsx tests/test-retry.ts && node tests/test-pi-local.mjs && node tests/test-omp-compat.mjs",
     "typecheck": "tsc --noEmit",
     "format:check": "prettier --check '**/*.{ts,mjs,json,md}'",
     "format": "prettier --write '**/*.{ts,mjs,json,md}'",
@@ -38,6 +38,7 @@
     "test:oauth": "tsx tests/test-oauth.ts",
     "test:abort": "tsx tests/test-abort.ts",
     "test:stream": "tsx tests/test-stream.ts",
+    "test:retry": "tsx tests/test-retry.ts",
     "test:pi-local": "node tests/test-pi-local.mjs",
     "test:smoke": "node tests/test-smoke.mjs"
   },

package/src/core.ts

@@ -42,6 +42,43 @@ export const DEFAULT_API_BASE = "https://api.commandcode.ai"
 export const COMMAND_CODE_CLI_VERSION = "0.29.0"
 
 const DEFAULT_GENERATE_MAX_TOKENS = 64_000
+const DEFAULT_MAX_RETRIES = 0
+const DEFAULT_MAX_RETRY_DELAY_MS = 60_000
+const BASE_RETRY_DELAY_MS = 500
+
+function isRetryableStatus(status: number): boolean {
+  return status === 429 || (status >= 500 && status < 600)
+}
+
+function parseRetryAfterSeconds(value: string | null): number | undefined {
+  if (!value) return undefined
+  const seconds = Number(value)
+  if (Number.isFinite(seconds) && seconds >= 0) return seconds
+  const date = Date.parse(value)
+  if (!Number.isNaN(date)) return Math.max(0, (date - Date.now()) / 1000)
+  return undefined
+}
+
+function effectiveMaxRetryDelayMs(value: number | undefined): number {
+  if (value === undefined) return DEFAULT_MAX_RETRY_DELAY_MS
+  if (value === 0) return Number.POSITIVE_INFINITY
+  return value
+}
+
+function retryDelayMs(
+  attempt: number,
+  retryAfterHeader: string | null,
+  maxDelayMs: number,
+): number {
+  const retryAfterMs = parseRetryAfterSeconds(retryAfterHeader)
+  if (retryAfterMs !== undefined) {
+    if (retryAfterMs * 1000 > maxDelayMs) return -1
+    return retryAfterMs * 1000
+  }
+  const exponential = BASE_RETRY_DELAY_MS * 2 ** attempt
+  const jitter = exponential * 0.2 * Math.random()
+  return Math.min(exponential + jitter, maxDelayMs)
+}
 
 function defaultUsage(): Usage {
   return {
@@ -76,6 +113,14 @@ function abortError(message = "The operation was aborted"): DOMException {
   return new DOMException(message, "AbortError")
 }
 
+function timeoutError(timeoutMs: number | undefined): Error {
+  return new Error(
+    timeoutMs === undefined
+      ? "Command Code API request timed out"
+      : `Command Code API request timed out after ${timeoutMs}ms`,
+  )
+}
+
 function successStopReason(reason: TerminalReason): StopReason {
   if (reason === "length" || reason === "toolUse") return reason
   return "stop"
@@ -104,6 +149,22 @@ export function createStreamCommandCode(deps: CoreDependencies) {
   const cwd = deps.cwd ?? (() => process.cwd())
   const now = deps.now ?? (() => Date.now())
   const uuid = deps.uuid ?? (() => randomUUID())
+  const delay =
+    deps.delay ??
+    ((ms: number, signal: AbortSignal) => {
+      if (signal.aborted) return Promise.reject(abortError())
+      return new Promise<void>((resolve, reject) => {
+        const id = setTimeout(() => {
+          signal.removeEventListener("abort", onAbort)
+          resolve()
+        }, ms)
+        const onAbort = () => {
+          clearTimeout(id)
+          reject(abortError())
+        }
+        signal.addEventListener("abort", onAbort, { once: true })
+      })
+    })
 
   function raceAbort<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
     if (signal.aborted) return Promise.reject(abortError())
@@ -386,81 +447,170 @@ export function createStreamCommandCode(deps: CoreDependencies) {
         )
         if (nextBody !== undefined) body = nextBody
 
-        const response = await raceAbort(
-          fetchImpl(`${apiBase}/alpha/generate`, {
-            method: "POST",
-            headers: {
-              "Content-Type": "application/json",
-              Authorization: `Bearer ${apiKey}`,
-              "x-command-code-version": COMMAND_CODE_CLI_VERSION,
-              "x-cli-environment": "production",
-              "x-project-slug": projectSlugFromPath(workingDir),
-              "x-taste-learning": "true",
-              "x-co-flag": "false",
-              ...options?.headers,
-            },
-            body: JSON.stringify(body),
-            signal: controller.signal,
-          }),
-          controller.signal,
-        )
-
-        await raceAbort(
-          Promise.resolve(
-            options?.onResponse?.(
-              {
-                status: response.status,
-                headers: headersToRecord(response.headers),
-              },
-              model,
-            ),
-          ),
-          controller.signal,
-        )
-
-        if (!response.ok) {
-          const errBody = await raceAbort(
-            response.text().catch(() => ""),
-            controller.signal,
-          )
-          throw new Error(`Command Code API error ${response.status}: ${errBody.slice(0, 500)}`)
+        const maxRetries = options?.maxRetries ?? DEFAULT_MAX_RETRIES
+        const maxRetryDelayMs = effectiveMaxRetryDelayMs(options?.maxRetryDelayMs)
+        const timeoutMs = options?.timeoutMs
+        const requestHeaders = {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${apiKey}`,
+          "x-command-code-version": COMMAND_CODE_CLI_VERSION,
+          "x-cli-environment": "production",
+          "x-project-slug": projectSlugFromPath(workingDir),
+          "x-taste-learning": "true",
+          "x-co-flag": "false",
+          ...options?.headers,
         }
+        const bodyStr = JSON.stringify(body)
+
+        let response!: Response
+        retryLoop: for (let attempt = 0; ; attempt++) {
+          const attemptController = new AbortController()
+          let attemptTimedOut = false
+          let attemptTimeoutId: ReturnType<typeof setTimeout> | undefined
+
+          const clearAttemptTimeout = () => {
+            if (attemptTimeoutId !== undefined) {
+              clearTimeout(attemptTimeoutId)
+              attemptTimeoutId = undefined
+            }
+          }
 
-        reader = response.body?.getReader()
-        if (!reader) throw new Error("No response body")
+          if (timeoutMs !== undefined) {
+            attemptTimeoutId = setTimeout(() => {
+              attemptTimedOut = true
+              attemptController.abort()
+            }, timeoutMs)
+          }
+          const onOuterAbort = () => attemptController.abort()
+          controller.signal.addEventListener("abort", onOuterAbort, { once: true })
+
+          try {
+            try {
+              response = await fetchImpl(`${apiBase}/alpha/generate`, {
+                method: "POST",
+                headers: requestHeaders,
+                body: bodyStr,
+                signal: attemptController.signal,
+              })
+            } catch (fetchError: unknown) {
+              if (controller.signal.aborted) throw abortError("Aborted")
+              if (attemptTimedOut) {
+                if (attempt < maxRetries) continue retryLoop
+                throw timeoutError(timeoutMs)
+              }
+              throw fetchError
+            }
 
-        const decoder = new TextDecoder()
-        let buffer = ""
+            // --- HTTP-level retry ---
+            if (!response.ok && isRetryableStatus(response.status)) {
+              const retryAfter = response.headers.get("retry-after")
+              const waitMs = retryDelayMs(attempt, retryAfter, maxRetryDelayMs)
+              if (waitMs < 0) {
+                const requestedSeconds = parseRetryAfterSeconds(retryAfter) ?? 0
+                const capLabel =
+                  maxRetryDelayMs === Number.POSITIVE_INFINITY ? "disabled" : `${maxRetryDelayMs}ms`
+                throw new Error(`Retry-After delay ${requestedSeconds}s exceeds max ${capLabel}`)
+              }
+              if (attempt < maxRetries) {
+                await response.text().catch(() => "")
+                if (waitMs > 0) await delay(waitMs, controller.signal)
+                continue retryLoop
+              }
+            }
 
-        readLoop: for (;;) {
-          if (controller.signal.aborted) throw abortError("Aborted")
-          const { done, value } = await raceAbort(reader.read(), controller.signal)
-          if (done) {
-            if (buffer.trim()) handleEvent(parseStreamEventLine(buffer))
-            break
-          }
-          if (controller.signal.aborted) throw abortError("Aborted")
+            await raceAbort(
+              Promise.resolve(
+                options?.onResponse?.(
+                  {
+                    status: response.status,
+                    headers: headersToRecord(response.headers),
+                  },
+                  model,
+                ),
+              ),
+              controller.signal,
+            )
+
+            if (!response.ok) {
+              const errBody = await raceAbort(
+                response.text().catch(() => ""),
+                controller.signal,
+              )
+              throw new Error(`Command Code API error ${response.status}: ${errBody.slice(0, 500)}`)
+            }
 
-          buffer += decoder.decode(value, { stream: true })
-          const lines = buffer.split("\n")
-          buffer = lines.pop() ?? ""
+            // --- Read response stream ---
+            reader = response.body?.getReader()
+            if (!reader) throw new Error("No response body")
+
+            const decoder = new TextDecoder()
+            let buffer = ""
+
+            try {
+              readLoop: for (;;) {
+                if (controller.signal.aborted) throw abortError("Aborted")
+                const { done, value } = await raceAbort(reader.read(), attemptController.signal)
+                if (done) {
+                  if (buffer.trim()) handleEvent(parseStreamEventLine(buffer))
+                  break
+                }
+                if (controller.signal.aborted) throw abortError("Aborted")
+
+                buffer += decoder.decode(value, { stream: true })
+                const lines = buffer.split("\n")
+                buffer = lines.pop() ?? ""
+
+                for (const line of lines) {
+                  if (controller.signal.aborted) throw abortError("Aborted")
+                  handleEvent(parseStreamEventLine(line))
+                  if (finished) break readLoop
+                }
+              }
+            } catch (streamError: unknown) {
+              // Stream-level error (e.g. API returned 200 OK but sent an error event)
+              // or per-attempt timeout during stream reading.
+              await reader.cancel().catch(() => {})
+              try {
+                reader.releaseLock()
+              } catch {}
+              reader = undefined
+
+              if (controller.signal.aborted) throw streamError
+
+              // Never retry after visible content was emitted (including timeout mid-stream).
+              const canRetry = output.content.length === 0 && attempt < maxRetries
+              if (canRetry) {
+                output.content.length = 0
+                textBlock = undefined
+                currentTextIdx = -1
+                thinkingIdx = -1
+                output.stopReason = "stop"
+                output.errorMessage = undefined
+                finished = false
+                const waitMs = attemptTimedOut ? 0 : retryDelayMs(attempt, null, maxRetryDelayMs)
+                if (waitMs > 0) await delay(waitMs, controller.signal)
+                continue retryLoop
+              }
+              if (attemptTimedOut) throw timeoutError(timeoutMs)
+              throw streamError
+            }
+
+            // Stream completed successfully.
+            endTextBlock()
+            endThinking()
 
-          for (const line of lines) {
-            if (controller.signal.aborted) throw abortError("Aborted")
-            handleEvent(parseStreamEventLine(line))
-            if (finished) break readLoop
+            stream.push({
+              type: "done",
+              reason: successStopReason(output.stopReason),
+              message: output,
+            })
+            stream.end()
+            break retryLoop
+          } finally {
+            controller.signal.removeEventListener("abort", onOuterAbort)
+            clearAttemptTimeout()
           }
         }
-
-        endTextBlock()
-        endThinking()
-
-        stream.push({
-          type: "done",
-          reason: successStopReason(output.stopReason),
-          message: output,
-        })
-        stream.end()
       } catch (error: unknown) {
         const reason: ErrorReason = controller.signal.aborted ? "aborted" : "error"
         output.stopReason = reason

package/src/types.ts

@@ -89,6 +89,23 @@ export interface StreamOptions {
   maxTokens?: number
   onPayload?: (payload: unknown, model: ModelLike) => unknown | Promise<unknown>
   onResponse?: (response: ProviderResponseInfo, model: ModelLike) => void | Promise<void>
+  /**
+   * HTTP request timeout in milliseconds.
+   * Applied per-attempt; on timeout the request is retried if retries remain.
+   */
+  timeoutMs?: number
+  /**
+   * Maximum retry attempts for transient HTTP errors (429, 5xx).
+   * Default: 0 (pi agent-level retry handles visible retries when unset).
+   */
+  maxRetries?: number
+  /**
+   * Maximum delay in milliseconds to wait for a retry when the server requests
+   * a long wait via Retry-After. If the server's requested delay exceeds this
+   * value, the request fails immediately. Default: 60000 (60 seconds).
+   * Set to 0 to disable the cap.
+   */
+  maxRetryDelayMs?: number
 }
 
 export type AssistantMessageEvent =
@@ -153,4 +170,6 @@ export interface CoreDependencies {
   now?: () => number
   uuid?: () => string
   homeDir?: () => string
+  /** Injectable delay for retry backoff. Defaults to setTimeout. */
+  delay?: (ms: number, signal: AbortSignal) => Promise<void>
 }