fix(amp): harden nmem thread sync (pagination, canonical append, long uploads)

[IceCodeNew]

Summary

Hardens the Amp nmem thread sync path so long transcripts are complete, existing canonical threads append safely, and large uploads have enough time to finish. It also documents account-wide installation through Amp Personal Plugins.

Changes

• Paginate Amp thread messages in ordered pages of 20 until the complete transcript is loaded.
• Append after 409 Conflict or a qualifying 422 response. The 422 check normalizes the complete payload, including string and nested-object bodies, and recognizes already exists and thread exists case-insensitively.
• Use a 120-second default HTTP timeout for large thread uploads.
• Document Personal Plugins installation alongside the existing one-machine install script, and record the account-wide option in integrations.json.
• Add regression coverage for pagination, canonical append behavior, timeout scheduling, and failure-safe spy cleanup.

Summary by CodeRabbit

• Bug Fixes

  • Improved retrieval of long Amp transcripts by loading messages in pages while preserving their order.
  • Existing-thread conflicts now fall back to appending messages when recognized; unrelated errors remain unchanged.
  • Increased the default request timeout to 120 seconds for larger uploads and slower connections.

• Documentation

  • Added guidance for installing and reloading the integration through Amp Personal Plugins.
  • Clarified account-wide and single-machine installation options.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: a48eac5e-ab13-4c40-b857-a0d16417e95d

📥 Commits

Reviewing files that changed from the base of the PR and between 655f47d and dd3a226.

📒 Files selected for processing (3)

• nowledge-mem-amp-plugin/src/sync.ts
• nowledge-mem-amp-plugin/tests/http.test.ts
• nowledge-mem-amp-plugin/tests/sync.test.ts

🚧 Files skipped from review as they are similar to previous changes (3)

• nowledge-mem-amp-plugin/src/sync.ts
• nowledge-mem-amp-plugin/tests/sync.test.ts
• nowledge-mem-amp-plugin/tests/http.test.ts

---

📝 Walkthrough

Walkthrough

The Amp plugin now retrieves complete transcripts through paginated SDK requests, handles existing-thread conflicts reported by 409 and matching 422 responses, and uses a 120-second default HTTP timeout. Amp Personal Plugins installation guidance and related tests were added.

Changes

Amp plugin updates

Layer / File(s)	Summary
Paginated transcript retrieval nowledge-mem-amp-plugin/src/index.ts, nowledge-mem-amp-plugin/tests/index.test.ts	readThreadMessagesViaSdk is publicly exported and reads messages in ordered pages of 20 until the final partial page. Tests cover a 45-message transcript and paginated SDK parameters.
Existing-thread conflict fallback nowledge-mem-amp-plugin/src/sync.ts, nowledge-mem-amp-plugin/tests/sync.test.ts	persistThread appends after 409 responses or matching 422 responses that indicate an existing thread. Unrelated 422 responses remain errors. Append assertions require deduplicate: true.
HTTP timeout update nowledge-mem-amp-plugin/src/http.ts, nowledge-mem-amp-plugin/tests/http.test.ts, nowledge-mem-amp-plugin/CHANGELOG.md	The default request timeout is 120,000 milliseconds. Tests restore mocks and verify the timeout. The Unreleased changelog documents the update.
Personal Plugins installation guidance integrations.json, nowledge-mem-amp-plugin/README.md	Amp guidance now documents account-wide Personal Plugins installation, synchronization, reloads, prerequisites, and the retained one-machine script option.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant readThreadMessagesViaSdk
  participant AmpThreadsMessages
  participant TranscriptConverter
  readThreadMessagesViaSdk->>AmpThreadsMessages: Request pages with offset and limit 20
  AmpThreadsMessages-->>readThreadMessagesViaSdk: Return message pages
  readThreadMessagesViaSdk->>TranscriptConverter: Convert the complete transcript

Loading

Possibly related PRs

• nowledge-co/community#480: Directly extends the Amp plugin’s HTTP, transcript, and thread persistence behavior.
• nowledge-co/community#482: Directly relates to existing-thread conflict detection and append fallback in src/sync.ts.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main synchronization fixes: pagination, append handling, and longer upload timeouts.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

nowledge-mem-amp-plugin/tests/http.test.ts (1)

123-131: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick win

Make the timeout spy cleanup failure-safe.

If nmemApi rejects or the assertion on Line 130 fails, mockRestore() on Line 131 does not run. This can affect later tests unless the file already has a shared mock-cleanup hook. Move cleanup to afterEach, or wrap the request and assertion in try/finally.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@nowledge-mem-amp-plugin/tests/http.test.ts` around lines 123 - 131, Make the
setTimeout spy cleanup failure-safe in the “allows two minutes for a request by
default” test by moving mockRestore into an afterEach hook or a try/finally
block surrounding the request and assertion. Ensure cleanup runs when nmemApi
rejects or the expectation fails, and avoid leaving the spy active for later
tests.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@nowledge-mem-amp-plugin/src/sync.ts`:
- Around line 299-312: Update the conflict detection around responseData and
threadAlreadyExists to normalize the complete response payload, including string
and nested-object bodies, before matching. Lowercase the normalized content and
recognize both “already exists” and “thread exists” while retaining status 409
handling, so all qualifying 422 conflicts use the append fallback.

---

Nitpick comments:
In `@nowledge-mem-amp-plugin/tests/http.test.ts`:
- Around line 123-131: Make the setTimeout spy cleanup failure-safe in the
“allows two minutes for a request by default” test by moving mockRestore into an
afterEach hook or a try/finally block surrounding the request and assertion.
Ensure cleanup runs when nmemApi rejects or the expectation fails, and avoid
leaving the spy active for later tests.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 749480c9-70d5-4f5b-bbe7-54b681f2bf11

📥 Commits

Reviewing files that changed from the base of the PR and between d6d5d66 and 4dd58cc.

📒 Files selected for processing (7)

• nowledge-mem-amp-plugin/CHANGELOG.md
• nowledge-mem-amp-plugin/src/http.ts
• nowledge-mem-amp-plugin/src/index.ts
• nowledge-mem-amp-plugin/src/sync.ts
• nowledge-mem-amp-plugin/tests/http.test.ts
• nowledge-mem-amp-plugin/tests/index.test.ts
• nowledge-mem-amp-plugin/tests/sync.test.ts

[IceCodeNew]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.