norns-sdk 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to `norns-sdk` are documented in this file.
 
+## [0.3.0] - 2026-10-22
+
+### Added
+- A worker holding a scoped key (`nrnw_...`, issued for one gard's worker)
+  skips the agent registration on `start()`, since the key cannot reach the
+  REST API; the definitions are registered with a tenant key instead.
+  `isScopedKey()` is exported.
+- `KeyRevokedError`: `worker.stopped` rejects with it when Norns revokes the
+  key the worker joined on.
+
 ## [0.2.0] - 2026-10-16
 
 ### Added

package/README.md

@@ -90,6 +90,12 @@ execute: async ({ port }, ctx) => {
 
 A fatally rejected claim (bad token, destroyed gard) rejects `start()` with `JoinError` instead of reconnect-looping. If the gard is destroyed while the worker is connected, `worker.stopped` rejects with `GardDestroyedError`.
 
+A worker inside a gard should hold a [scoped key](https://github.com/nornscode/norns/blob/main/docs/gards.md#scoped-worker-keys) (`nrnw_...`) rather than the tenant key: it can join the worker socket, claim its gard and serve tasks, and nothing else. With one, `start()` skips the agent registration, since the key cannot reach the REST API; register the definitions with a tenant key instead. Pass `capabilities: ["tools"]` for a worker with no LLM access, matching what the key allows. If the key is revoked while the worker is connected, `worker.stopped` rejects with `KeyRevokedError`.
+
+```ts
+const worker = new NornsWorker({ agents: [coder], gard: 3, claimToken: "tok_...", capabilities: ["tools"] });
+```
+
 ### Shutdown
 
 On SIGTERM or SIGINT the worker drains instead of dying mid-task: it tells Norns to stop sending it work, finishes the tasks it holds, reports their results, leaves the channel, and the process exits. Tasks still running after `shutdownTimeoutMs` (default 30 seconds, or `NORNS_SHUTDOWN_TIMEOUT` in seconds) are dropped and Norns re-dispatches them. A second signal exits at once.

package/dist/index.cjs

@@ -23,6 +23,7 @@ __export(index_exports, {
   DEFAULT_MODEL: () => DEFAULT_MODEL,
   GardDestroyedError: () => GardDestroyedError,
   JoinError: () => JoinError,
+  KeyRevokedError: () => KeyRevokedError,
   NornsApiError: () => NornsApiError,
   NornsClient: () => NornsClient,
   NornsError: () => NornsError,
@@ -33,6 +34,7 @@ __export(index_exports, {
   consoleLogger: () => consoleLogger,
   defineAgent: () => defineAgent,
   inferProvider: () => inferProvider,
+  isScopedKey: () => isScopedKey,
   jsonSchema: () => import_ai4.jsonSchema,
   silentLogger: () => silentLogger,
   tool: () => tool
@@ -245,6 +247,12 @@ var GardDestroyedError = class extends NornsError {
     this.name = "GardDestroyedError";
   }
 };
+var KeyRevokedError = class extends NornsError {
+  constructor() {
+    super("the worker's scoped key was revoked");
+    this.name = "KeyRevokedError";
+  }
+};
 var StreamClosedError = class extends NornsError {
   reason;
   constructor(reason) {
@@ -573,6 +581,9 @@ function resolveApiKey(apiKey) {
   if (!value) throw new NornsError("Norns API key missing: pass `apiKey` or set NORNS_API_KEY");
   return value;
 }
+function isScopedKey(apiKey) {
+  return apiKey.startsWith("nrnw_");
+}
 function wsBase(url) {
   return url.replace(/^http:\/\//, "ws://").replace(/^https:\/\//, "wss://");
 }
@@ -1283,9 +1294,15 @@ var NornsWorker = class {
     return this.#starting;
   }
   async #start() {
-    for (const agent of this.#agents) {
-      const info = await this.#client.agents.ensure(agent);
-      this.#logger.info(`Registered agent '${agent.name}' (id=${info.id})`);
+    if (isScopedKey(this.#apiKey)) {
+      this.#logger.info(
+        "Worker key is scoped (nrnw_): skipping agent registration. Register the agent definitions with a tenant key."
+      );
+    } else {
+      for (const agent of this.#agents) {
+        const info = await this.#client.agents.ensure(agent);
+        this.#logger.info(`Registered agent '${agent.name}' (id=${info.id})`);
+      }
     }
     if (this.#capabilities.includes("llm")) {
       for (const model of new Set(this.#agents.map((a) => a.model))) {
@@ -1336,6 +1353,10 @@ var NornsWorker = class {
       this.#logger.error("This worker's gard was destroyed; shutting down");
       this.#fail(new GardDestroyedError(this.gard));
     });
+    channel.on("key_revoked", () => {
+      this.#logger.error("This worker's key was revoked; shutting down");
+      this.#fail(new KeyRevokedError());
+    });
     channel.onError((reason) => {
       if (this.#state === "running")
         this.#logger.warn(`Channel error (${errorMessage(reason)}); rejoining`);
@@ -1649,6 +1670,7 @@ var NornsWorker = class {
   DEFAULT_MODEL,
   GardDestroyedError,
   JoinError,
+  KeyRevokedError,
   NornsApiError,
   NornsClient,
   NornsError,
@@ -1659,6 +1681,7 @@ var NornsWorker = class {
   consoleLogger,
   defineAgent,
   inferProvider,
+  isScopedKey,
   jsonSchema,
   silentLogger,
   tool