@holokai/neuron-sdk 0.4.0 → 0.5.1

package/README.md

@@ -843,69 +843,75 @@ The `auth` callback isn't returning a valid token. If using a refresh flow, ensu
 
 ## Releasing (maintainers)
 
-`@holokai/neuron-sdk` is published to public npm. Releases are cut from a
-monorepo-scoped git tag, and CI does the publish — there is no npm token on
-anyone's laptop and none stored in the repo.
+`@holokai/neuron-sdk` is published to public npm by BigBrain's Release
+workflow (`.github/workflows/release.yml`). There is no npm token on anyone's
+laptop and none stored in the repo, and pushing a tag publishes nothing.
+
+### Pick the version
+
+Follow semver:
+
+- Pilot phase, we are in **`0.x`**. Because the protocol is still absorbing
+  pilot-developer feedback, a **breaking** change bumps the **minor**
+  (`0.2.0` to `0.3.0`); a backward-compatible change or fix bumps the
+  **patch** (`0.2.0` to `0.2.1`). This is the standard `0.x` convention and
+  is what buys us room to break things on feedback without a major bump.
+- Hold **`1.0.0`** until the public API has survived pilot feedback and we're
+  ready to commit to "breaking changes bump the major." Jumping to `1.0.0`
+  is a stability promise, not a milestone. Don't spend it early.
 
 ### Cut a release
 
-1. **Bump the version** in `packages/neuron-sdk/package.json`
-   (`version`). Follow semver:
-   - Pilot phase, we are in **`0.x`**. Because the protocol is still absorbing
-     pilot-developer feedback, a **breaking** change bumps the **minor**
-     (`0.2.0` → `0.3.0`); a backward-compatible change or fix bumps the
-     **patch** (`0.2.0` → `0.2.1`). This is the standard `0.x` convention and
-     is what buys us room to break things on feedback without a major bump.
-   - Hold **`1.0.0`** until the public API has survived pilot feedback and we're
-     ready to commit to "breaking changes bump the major." Jumping to `1.0.0`
-     is a stability promise, not a milestone — don't spend it early.
-2. **Commit** the bump (reference the Linear ticket) and merge to `main`.
-3. **Tag and push** from `main`:
-   ```sh
-   git tag neuron-sdk-v0.2.0        # must equal the package.json version
-   git push origin neuron-sdk-v0.2.0
-   ```
-   The tag is prefixed `neuron-sdk-v` (the Python SDK uses
-   `neuron-sdk-python-v`) so the two never collide.
-4. **`publish-neuron-sdk.yml`** fires on the tag: it asserts the tag version
-   matches `package.json`, runs the `prepublish` gate (`build` + `test`), and
-   publishes to npm. The `npm` GitHub Environment gates the publish behind a
-   **required-reviewer approval** — approve the run under Actions, and on success
-   the new version is live at
+1. Open **Actions, Release, Run workflow** on branch `main`.
+2. Fill **neuron-sdk** with the new version (`X.Y.Z`). Leave the other lines
+   (base, embedded, synapse) empty unless they are being released too; an
+   empty line is not touched. Tick **plan only** to read the plan without
+   cutting anything.
+3. The plan job checks the version (shaped `X.Y.Z`, not older than
+   `packages/neuron-sdk/package.json`, tag `neuron-sdk-vX.Y.Z` not taken) and
+   writes the plan to the run summary.
+4. A reviewer of the `release` environment approves the run. That is the only
+   approval.
+5. The cut writes the version into `packages/neuron-sdk/package.json`,
+   commits it to `main`, tags `neuron-sdk-vX.Y.Z` and pushes both. If the file
+   already carries the version (a bump merged by pull request), it only tags.
+6. From the commit the cut pushed, the run builds and tests the SDK (the
+   `prepublish` turbo task), packs it, and publishes the tarball to npm from a
+   GitHub-hosted runner. On success the new version is live at
    [`@holokai/neuron-sdk`](https://www.npmjs.com/package/@holokai/neuron-sdk).
 
-   > No `--provenance`: bigbrain is a private repo, so npm's provenance
-   > attestation (a public transparency-log link back to the source) adds little
-   > and has historically errored from private repos. Trusted-publishing auth is
-   > unaffected. Add the flag back if bigbrain ever goes public.
+The tag is prefixed `neuron-sdk-v` (the Python SDK uses `neuron-sdk-python-v`)
+so the two never collide. The workflow file's header comments describe every
+job and how to recover a failed run.
 
-The tag→`package.json` assertion means a mismatched tag fails **before** the
-registry is touched — npm refuses to re-upload an existing version, so there's
-no half-published state to clean up.
+> No `--provenance`: bigbrain is a private repo, so npm's provenance
+> attestation (a public transparency-log link back to the source) adds little
+> and has historically errored from private repos. Trusted-publishing auth is
+> unaffected. Add the flag back if bigbrain ever goes public.
 
 ### Publish auth: npm Trusted Publishing (one-time setup)
 
-CI authenticates to npm via **OIDC trusted publishing** — GitHub Actions
+CI authenticates to npm via **OIDC trusted publishing**: GitHub Actions
 exchanges a short-lived OIDC token for publish rights, so no long-lived
-`NPM_TOKEN` exists to leak. This mirrors the Python SDK's PyPI trusted
-publishing. It requires two one-time setups:
+`NPM_TOKEN` exists to leak. It requires two one-time setups:
 
 1. **On npmjs.com** (a package admin, once): open the
    [`@holokai/neuron-sdk`](https://www.npmjs.com/package/@holokai/neuron-sdk)
-   package → **Settings → Trusted Publisher → GitHub Actions**, and register:
+   package, **Settings, Trusted Publisher, GitHub Actions**, and register:
    - Organization / repository: `holok-ai/bigbrain`
-   - Workflow filename: `publish-neuron-sdk.yml`
+   - Workflow filename: `release.yml`
    - Environment: `npm`
-2. **In this repo** (once): create the **`npm`** GitHub Environment
-   (Settings → Environments). Add reviewers/branch protection here if you want a
-   manual approval gate before each publish.
+2. **In this repo** (once): the **`npm`** GitHub Environment (Settings,
+   Environments) with no required reviewer, because the Release run's one
+   approval is on its cut, and a deployment branch rule of `main` only, so a
+   copy of `release.yml` on another branch cannot publish to npm.
 
 Until the trusted publisher is registered, the `npm publish` step fails with an
-auth error — that's the expected "not set up yet" signal, not a code bug.
+auth error. That is the expected "not set up yet" signal, not a code bug.
 
 ### Manual publish (fallback / first bootstrap)
 
-The tag flow is the norm. If you ever need to publish by hand (e.g. to bootstrap
+The Release workflow is the norm. If you ever need to publish by hand (e.g. to bootstrap
 the very first version before trusted publishing is configured):
 
 ```sh
@@ -915,6 +921,6 @@ pnpm run publish:npm       # runs the prepublishOnly build+test gate, then publi
 ```
 
 This uses your own `npm login` credentials and skips the CI approval gate —
-prefer the tag flow for anything a developer will consume.
+prefer the Release workflow for anything a developer will consume.
 
 <!-- ci: force full build on the self-hosted runner (HOL-2028 verify); safe to remove -->

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { J as JsonSchema, C as Capability, a as CapabilityHandleOptions, S as ServerToNeuronFrame, N as NeuronLogger, T as Transport, A as AuthCallback, H as Handler, b as CapabilityRegistration, c as TransportCallbacks, d as ClientFrame, P as PostPath } from './transport-Cs5tY2IO.mjs';
-export { e as HandlerContext, f as HeartbeatInFlightEntry, L as LeasePayload, g as TaskPayload } from './transport-Cs5tY2IO.mjs';
+import { J as JsonSchema, C as Capability, a as CapabilityHandleOptions, S as ServerToNeuronFrame, N as NeuronLogger, T as Transport, A as AuthCallback, H as Handler, b as CapabilityRegistration, c as TransportCallbacks, d as ClientFrame, P as PostPath } from './transport-Ckcwj-Do.mjs';
+export { e as HandlerContext, f as HeartbeatInFlightEntry, L as LeasePayload, g as TaskPayload } from './transport-Ckcwj-Do.mjs';
 import { EventEmitter } from 'eventemitter3';
 import { z } from 'zod';
 import { ErrorObject } from 'ajv';

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { J as JsonSchema, C as Capability, a as CapabilityHandleOptions, S as ServerToNeuronFrame, N as NeuronLogger, T as Transport, A as AuthCallback, H as Handler, b as CapabilityRegistration, c as TransportCallbacks, d as ClientFrame, P as PostPath } from './transport-Cs5tY2IO.js';
-export { e as HandlerContext, f as HeartbeatInFlightEntry, L as LeasePayload, g as TaskPayload } from './transport-Cs5tY2IO.js';
+import { J as JsonSchema, C as Capability, a as CapabilityHandleOptions, S as ServerToNeuronFrame, N as NeuronLogger, T as Transport, A as AuthCallback, H as Handler, b as CapabilityRegistration, c as TransportCallbacks, d as ClientFrame, P as PostPath } from './transport-Ckcwj-Do.js';
+export { e as HandlerContext, f as HeartbeatInFlightEntry, L as LeasePayload, g as TaskPayload } from './transport-Ckcwj-Do.js';
 import { EventEmitter } from 'eventemitter3';
 import { z } from 'zod';
 import { ErrorObject } from 'ajv';

package/dist/index.js

@@ -558,6 +558,7 @@ var TerminalFailure = class extends Error {
     this.name = "TerminalFailure";
   }
 };
+var DEFAULT_PROGRESS_TIMEOUT_MS = 5e3;
 function validateInput(zod, validator, jsonSchema, data) {
   if (zod) {
     const result = zod.safeParse(data);
@@ -580,7 +581,8 @@ async function runLease(opts) {
     transport,
     validator,
     logger,
-    signal
+    signal,
+    progressTimeoutMs = DEFAULT_PROGRESS_TIMEOUT_MS
   } = opts;
   const inputCheck = validateInput(zodInput, validator, inputSchema, lease.task.input);
   if (!inputCheck.ok) {
@@ -595,13 +597,13 @@ async function runLease(opts) {
     return;
   }
   const parsedInput = inputCheck.value;
-  const progressFn = makeProgressFn(transport, lease.leaseId, logger);
+  const reporter = makeProgressReporter(transport, lease.leaseId, logger, signal, progressTimeoutMs);
   const ctx = {
     task: lease.task,
     leaseId: lease.leaseId,
     signal,
     log: scopedLogger(logger, lease),
-    progress: progressFn,
+    progress: reporter.progress,
     fail: (reason, opts2) => {
       throw new TerminalFailure(reason, opts2?.code);
     }
@@ -610,7 +612,9 @@ async function runLease(opts) {
   try {
     output = await handler(parsedInput, ctx);
   } catch (err) {
-    if (signal.aborted || err.name === "AbortError") {
+    const cancelled = signal.aborted || err.name === "AbortError";
+    if (!cancelled) await reporter.drained();
+    if (cancelled) {
       await sendNack(
         transport,
         lease.leaseId,
@@ -644,6 +648,7 @@ async function runLease(opts) {
     );
     return;
   }
+  await reporter.drained();
   const outputCheck = validateInput(zodOutput, validator, outputSchema, output);
   if (!outputCheck.ok) {
     await sendNack(
@@ -685,20 +690,37 @@ async function sendNack(transport, leaseId, kind, reason, extras = {}, logger) {
     );
   });
 }
-function makeProgressFn(transport, leaseId, logger) {
-  return (update) => {
-    void transport.post(POST_PATH.progress, {
-      type: "progress",
-      leaseId,
-      percent: update.percent,
-      message: update.message,
-      data: update.data,
-      sentAt: (/* @__PURE__ */ new Date()).toISOString()
-    }).catch((err) => {
-      logger.warn({ err, leaseId }, "progress POST failed; continuing");
-    });
+function makeProgressReporter(transport, leaseId, logger, signal, timeoutMs) {
+  let tail = Promise.resolve();
+  return {
+    progress: (update) => {
+      const frame = {
+        type: "progress",
+        leaseId,
+        percent: update.percent,
+        message: update.message,
+        data: update.data,
+        sentAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      tail = tail.then(async () => {
+        if (signal.aborted) return;
+        try {
+          await withTimeout(transport.post(POST_PATH.progress, frame), timeoutMs);
+        } catch (err) {
+          logger.warn({ err, leaseId }, "progress POST failed; continuing");
+        }
+      });
+    },
+    drained: () => tail
   };
 }
+function withTimeout(work, ms) {
+  let timer;
+  const timeout = new Promise((_resolve, reject) => {
+    timer = setTimeout(() => reject(new Error(`timed out after ${ms}ms`)), ms);
+  });
+  return Promise.race([work, timeout]).finally(() => clearTimeout(timer));
+}
 function scopedLogger(logger, lease) {
   const scope = { leaseId: lease.leaseId, taskId: lease.task.taskId };
   return {