Skip to content

relayburn-sdk-node: napi-rs bindings skeleton (#247 part a) #306

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
willwashburn merged 6 commits into from
May 6, 2026
+1,282 −4
Merged

relayburn-sdk-node: napi-rs bindings skeleton (#247 part a) #306

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
ac0d53d
relayburn-sdk-node: napi-rs bindings skeleton (#247 part a)
willwashburn May 6, 2026
290b970
relayburn-sdk-node: typed BurnError + kebab-case enum values + typed …
willwashburn May 6, 2026
7ce35bf
Merge origin/main into rust-port/sdk-node-skeleton (resolve CHANGELOG…
Copilot May 6, 2026
a3e2f01
Merge remote-tracking branch 'origin/main' into pr306-fixups-2
willwashburn May 6, 2026
e5fcf8e
relayburn-sdk-node: tighten ingest() typed-error contract docs (revie…
willwashburn May 6, 2026
8eccecd
relayburn-sdk-node: BigInt promotion on export verbs (review fix roun…
willwashburn May 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ Cross-package release notes for relayburn. Package changelogs contain package-le

## [Unreleased]

- `relayburn-sdk-node` (Rust): napi-rs bindings skeleton — `#[napi]` shims for every public verb in `relayburn-sdk` (`summary`, `sessionCost`, `overhead`, `overheadTrim`, `hotspots`, `search`, `exportLedger`, `exportStamps`, async `ingest`, plus `ledgerOpen`), with u64 token counts surfaced as JS `BigInt`, ISO-8601 timestamps as `String`, async verbs returning `Promise<T>`, and a typed `BurnError` mapping for SDK failures. (#247)
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot May 6, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Move this note out of the root changelog.

This PR adds an internal relayburn-sdk-node crate skeleton, while the cross-package packaging and published npm surface are explicitly deferred. Keeping this in the root [Unreleased] block overstates what is actually shipping from this change.

As per coding guidelines, CHANGELOG.md: Update the root \CHANGELOG.md` `[Unreleased]` block only for work that spans packages or warrants top-level summary; single-package work belongs only in that package's CHANGELOG`.

🤖 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 `@CHANGELOG.md` at line 7, The release note about the new internal
relayburn-sdk-node crate should not live in the root CHANGELOG.md [Unreleased]
block; remove the bullet referencing `relayburn-sdk-node` from the root
changelog and add the same entry to the package-level changelog for the
relayburn-sdk-node crate (e.g., relayburn-sdk-node/CHANGELOG.md) under its
[Unreleased] section, keeping the original wording about napi-rs shims,
BigInt/ISO-8601 mappings, async verbs, and typed BurnError so the note is scoped
to that single-package change.

Copy link
Copy Markdown
Member Author

@willwashburn willwashburn May 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pushing back on this one — keeping the entry in the root CHANGELOG. Per CLAUDE.md, the root file is the cross-package narrative for the rewrite, and relayburn-sdk-node is intentionally an internal crate (publish = false in Cargo.toml; not on crates.io and not in the per-package list of eight published TS packages). There's no per-crate CHANGELOG.md to move it to — the npm publish workflow only touches the eight packages/* files. The root [Unreleased] block is exactly where port-progress notes belong for anyone watching the 2.0 cutover, and the publish workflow will promote that block verbatim when the next release runs.

Copy link
Copy Markdown

@coderabbitai coderabbitai Bot May 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@willwashburn, that makes sense — thank you for the context. The root CHANGELOG.md serving as the unified port-progress narrative for the 2.0 cutover (with relayburn-sdk-node being publish = false and outside the eight packages/* TS packages) is a meaningful distinction I missed. The entry belongs where it is. I'll stand down on this one.

✏️ Learnings added 
Learnt from: willwashburn
Repo: AgentWorkforce/burn PR: 306
File: CHANGELOG.md:7-7
Timestamp: 2026-05-06T12:38:47.974Z
Learning: In the relayburn monorepo, the root `CHANGELOG.md` `[Unreleased]` block is the canonical cross-package narrative for the 2.0 rewrite. Internal Rust crates (e.g., `relayburn-sdk-node`, which is `publish = false` and not on crates.io) do not have their own per-crate `CHANGELOG.md` and are tracked here instead. The npm publish workflow only touches the eight `packages/*` files. Port-progress notes for internal crates belong in the root `[Unreleased]` block, not in a separate package-level changelog.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.

- `relayburn-cli` (Rust): introduce the harness substrate — `HarnessAdapter` trait, lazy compile-time `phf` registry (`lookup` / `list_harness_names`), and the shared `pending_stamp::adapter` factory codex + opencode will reuse. Adapter slots in the registry are reserved but empty pending the Wave 2 PRs (#248-d/e/f). `relayburn-sdk` re-exports `start_watch_loop`, `WatchController`, `write_pending_stamp`, `PendingStampHarness`, and friends so the CLI doesn't have to reach into private SDK modules. (#248)
- `relayburn-ingest` (Rust): port the per-process gap-warning state machine (`gap` module — `record_session_gap`, `emit_gap_warning`, `count_tool_call_gaps`, `reset_ingest_gap_warnings`, `set_ingest_gap_writer`) and `reingest_missing_content` (`reingest` module). Suppression mirrors the TS surface: one warning per fresh affected session, silent on steady-state, re-fires after the affected set decays back to empty. `relayburn-ledger` adds `Ledger::list_user_turn_session_ids` to power the `reingest_missing_content` skip filter alongside `list_content_session_ids`. (#278)
- `relayburn-analyze` (Rust): port the behavioral-pattern detectors (`patterns` module). `detect_patterns` runs retry-loop, failure-run, cancellation-run, compaction-loss, edit-revert, OpenCode skill-recall-dup, OpenCode skill-pruning-protection, OpenCode system-prompt-tax, and edit-heavy detectors against an ordered turn stream, with optional content-sidecar / tool-result-event / user-turn enrichment. Public surface: `detect_patterns`, `DetectPatternsOptions`; per-pattern result structs are re-exported from `findings` (`RetryLoop`, `FailureRun`, `CancellationRun`, `CompactionLoss`, `EditRevertCycle`, `SkillRecallDup`, `SkillPruningProtection`, `SystemPromptTax`, `EditHeavySession`, `SessionPatternSummary`, `PatternsResult`, `PatternEventSource`). (#275)
Expand Down
102 changes: 102 additions & 0 deletions Cargo.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

20 changes: 17 additions & 3 deletions crates/relayburn-sdk-node/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,22 @@ repository.workspace = true
description = "napi-rs bindings over relayburn-sdk — built in CI to produce the @relayburn/sdk npm artifacts. Not published to crates.io."
publish = false

[lib]
crate-type = ["cdylib", "rlib"]

[dependencies]
# napi-rs glue lands in #247; this crate's only direct dep is the SDK.
# Not published to crates.io, so the version pin is loose by design — it
# just keeps `cargo metadata` and the workspace resolver happy.
# napi-rs glue. The Node bindings sit on top of the SDK and expose
# `#[napi]` shims for every public verb. Not published to crates.io —
# this crate is consumed exclusively by the napi-rs CI matrix in #247-b
# to produce the per-platform `.node` artifacts under
# `packages/sdk-node/`.
relayburn-sdk = { path = "../relayburn-sdk", version = "0.0" }
napi = { version = "2", default-features = false, features = ["napi6", "tokio_rt", "serde-json"] }
napi-derive = "2"
serde = { workspace = true }
serde_json = { workspace = true }
anyhow = { workspace = true }
tokio = { workspace = true }

[build-dependencies]
napi-build = "2"
7 changes: 7 additions & 0 deletions crates/relayburn-sdk-node/build.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
// napi-rs build script. Generates the symbol-export table the Node loader
// needs. See https://napi.rs/docs/cli/build for details.
extern crate napi_build;

fn main() {
napi_build::setup();
}
Loading
Loading