/update-libs

name: update-libs
description: Update the libs/ SDK submodules (openai-go, anthropic-sdk-go, go-genai) to new upstream/fork versions, adapt tingly-box to API changes, and verify with build + vet + tests. Use when asked to bump/update SDK submodules, sync libs to new tingly-dev/upstream tags, or fix breakage after a submodule bump.

Update libs/ SDK submodules

Wiring

• Submodules: `libs/openai-go`, `libs/anthropic-sdk-go`, `libs/go-genai`,

wired into `go.mod` via `replace`.

• Version source of truth: `OPENAI_GO_VERSION` / `ANTHROPIC_SDK_GO_VERSION` /

`GO_GENAI_VERSION` at the top of `Taskfile.yml` (branch or tag names).

• `task submodule:update` checks out those refs and rewrites `branch =` in

`.gitmodules` to match — never hand-edit `.gitmodules`.

Procedure

1. **Declare the target versions**: edit the three vars in `Taskfile.yml`, then run:

   task submodule:update

2. **Network fallback** if `git fetch` over HTTPS fails (SSH usually works):

   for d in libs/openai-go libs/anthropic-sdk-go libs/go-genai; do
     git -C $d config url."git@github.com:".insteadOf "https://github.com/"
   done

Set it per-submodule — submodule repos don't inherit superproject config.

3. **Review the fork patches.** The `tingly-dev-*` branches carry a small set of deliberate patches over upstream. Verify each still exists and still makes sense; a patch may have been deleted on purpose:

   git -C libs/<sdk> fetch origin
   git -C libs/<sdk> log --oneline origin/<upstream-ref>..<tingly-dev-ref>
   git -C libs/<sdk> diff --stat origin/<upstream-ref>..<tingly-dev-ref>

Fork patch commits are prefixed `tingly-dev` and explain their intent in the commit body — read it before deciding anything.

4. **Build-fix loop**:

   go build ./...

Typical SDK breakage: plain fields become `param.Opt[T]` (`packages/param`). Write with `param.NewOpt(x)`, read with `x.Value` (`Opt[T]` is a value struct; absent → zero value, no nil deref). Note that identically-named fields on different structs may differ — one may stay plain while another became `Opt` — so check the struct, not the field name.

5. **Verify**:

   go vet ./internal/... ./cli/... ./ai/... ./imbot/...
   go test ./internal/protocol/...

For any failure, first attribute it: SDK-related or environment? (Failing on network fetches, temp-HOME layout, etc. is unrelated to the bump.) Do not claim verification passed on failures you didn't triage.

6. **Evaluate behavior changes — do NOT blindly conform.** When a test fails on changed semantics (not just types):

• Read the fork/upstream commit that changed the behavior and its stated

intent.

• Search tingly-box for production call sites relying on the old behavior.
• Adapt our code/tests only if the product does not depend on the old

behavior; otherwise surface the conflict to the user before changing anything.

7. **Commit in stages** (never one big commit; the user's preferred order): 1. `chore(taskfile)`: Taskfile.yml version vars only. 2. `chore(libs)`: submodule pointers + `.gitmodules` (follows the Taskfile). 3. `refactor`/`fix`: API adaptation code + tests (always last). 4. Optional: doc updates.