norns-sdk 0.2.0 → 0.4.0

package/dist/index.d.cts

@@ -264,6 +264,12 @@ declare class NornsClient {
         delete: (agent: AgentRef, key: string) => Promise<void>;
     };
 }
+/**
+ * A key issued by `POST /api/v1/api_keys` with a worker scope (`nrnw_...`).
+ * It opens the worker socket and nothing else, so a worker holding one must
+ * not try the REST API.
+ */
+declare function isScopedKey(apiKey: string): boolean;
 
 /**
  * Where the SDK writes what it is doing. Anything with these four methods
@@ -301,7 +307,11 @@ interface NornsWorkerOptions {
     agents: AgentDefinition | AgentDefinition[];
     /** The Norns base URL. Defaults to `NORNS_URL`. */
     url?: string;
-    /** The tenant's bearer token. Defaults to `NORNS_API_KEY`. */
+    /**
+     * The bearer token. Defaults to `NORNS_API_KEY`. A scoped worker key
+     * (`nrnw_...`) joins without registering the agents, since it cannot reach
+     * the REST API; register the definitions with a tenant key.
+     */
     apiKey?: string;
     /**
      * How a model name on an LLM task becomes a model to call: a function, a
@@ -470,6 +480,7 @@ interface ToolDefinition<I = unknown> {
  */
 declare function tool<S extends ToolInputSchema>(options: ToolOptions<S>): ToolDefinition<InferToolInput<S>>;
 
+/** @deprecated Norns never read it; a conversation starts from a `conversationKey` on the message. */
 type AgentMode = "task" | "conversation";
 type CheckpointPolicy = "every_step" | "on_tool_call" | "manual";
 type ContextStrategy = "sliding_window" | "none";
@@ -500,6 +511,7 @@ interface AgentOptions {
     systemPrompt?: string;
     /** What this worker serves for the agent (see `allowedTools` for what it is offered). */
     tools?: ToolDefinition[];
+    /** @deprecated Ignored. Norns never read it; send a message with a `conversationKey` instead. */
     mode?: AgentMode;
     checkpointPolicy?: CheckpointPolicy;
     contextStrategy?: ContextStrategy;
@@ -530,7 +542,6 @@ interface AgentDefinition {
     readonly model: string;
     readonly systemPrompt: string;
     readonly tools: readonly ToolDefinition[];
-    readonly mode: AgentMode;
     readonly checkpointPolicy: CheckpointPolicy;
     readonly contextStrategy: ContextStrategy;
     readonly contextWindow: number;
@@ -582,6 +593,10 @@ declare class JoinError extends NornsError {
 declare class GardDestroyedError extends NornsError {
     constructor(gard: string | number | undefined);
 }
+/** The scoped key this worker joined on was revoked while it was connected. */
+declare class KeyRevokedError extends NornsError {
+    constructor();
+}
 /** A stream's socket closed before the run reached a terminal event. */
 declare class StreamClosedError extends NornsError {
     readonly reason: unknown;
@@ -675,5 +690,5 @@ type ToolResult = {
     error: string;
 };
 
-export { DEFAULT_MODEL, GardDestroyedError, JoinError, NornsApiError, NornsClient, NornsError, NornsTimeoutError, NornsWorker, NotFoundError, StreamClosedError, consoleLogger, defineAgent, inferProvider, silentLogger, tool };
+export { DEFAULT_MODEL, GardDestroyedError, JoinError, KeyRevokedError, NornsApiError, NornsClient, NornsError, NornsTimeoutError, NornsWorker, NotFoundError, StreamClosedError, consoleLogger, defineAgent, inferProvider, isScopedKey, silentLogger, tool };
 export type { AgentDefinition, AgentInfo, AgentMode, AgentOptions, AgentRef, Capability, CheckpointPolicy, ContextPolicy, ContextStrategy, Conversation, InferToolInput, ListRunsOptions, LlmResult, LlmTask, Logger, MessageResult, ModelResolver, ModelSource, ModelsOption, NeutralMessage, NeutralToolCall, NornsClientOptions, NornsWorkerOptions, OnFailure, RegisterPortOptions, RegisteredPort, Run, RunEvent, RunStatus, SendMessageOptions, StreamEvent, StreamOptions, SubagentConversation, SubagentPolicy, ToolContext, ToolDefinition, ToolInputSchema, ToolOptions, ToolResult, ToolTask, WaitingFor, WebSocketConstructor };

package/dist/index.d.ts

@@ -264,6 +264,12 @@ declare class NornsClient {
         delete: (agent: AgentRef, key: string) => Promise<void>;
     };
 }
+/**
+ * A key issued by `POST /api/v1/api_keys` with a worker scope (`nrnw_...`).
+ * It opens the worker socket and nothing else, so a worker holding one must
+ * not try the REST API.
+ */
+declare function isScopedKey(apiKey: string): boolean;
 
 /**
  * Where the SDK writes what it is doing. Anything with these four methods
@@ -301,7 +307,11 @@ interface NornsWorkerOptions {
     agents: AgentDefinition | AgentDefinition[];
     /** The Norns base URL. Defaults to `NORNS_URL`. */
     url?: string;
-    /** The tenant's bearer token. Defaults to `NORNS_API_KEY`. */
+    /**
+     * The bearer token. Defaults to `NORNS_API_KEY`. A scoped worker key
+     * (`nrnw_...`) joins without registering the agents, since it cannot reach
+     * the REST API; register the definitions with a tenant key.
+     */
     apiKey?: string;
     /**
      * How a model name on an LLM task becomes a model to call: a function, a
@@ -470,6 +480,7 @@ interface ToolDefinition<I = unknown> {
  */
 declare function tool<S extends ToolInputSchema>(options: ToolOptions<S>): ToolDefinition<InferToolInput<S>>;
 
+/** @deprecated Norns never read it; a conversation starts from a `conversationKey` on the message. */
 type AgentMode = "task" | "conversation";
 type CheckpointPolicy = "every_step" | "on_tool_call" | "manual";
 type ContextStrategy = "sliding_window" | "none";
@@ -500,6 +511,7 @@ interface AgentOptions {
     systemPrompt?: string;
     /** What this worker serves for the agent (see `allowedTools` for what it is offered). */
     tools?: ToolDefinition[];
+    /** @deprecated Ignored. Norns never read it; send a message with a `conversationKey` instead. */
     mode?: AgentMode;
     checkpointPolicy?: CheckpointPolicy;
     contextStrategy?: ContextStrategy;
@@ -530,7 +542,6 @@ interface AgentDefinition {
     readonly model: string;
     readonly systemPrompt: string;
     readonly tools: readonly ToolDefinition[];
-    readonly mode: AgentMode;
     readonly checkpointPolicy: CheckpointPolicy;
     readonly contextStrategy: ContextStrategy;
     readonly contextWindow: number;
@@ -582,6 +593,10 @@ declare class JoinError extends NornsError {
 declare class GardDestroyedError extends NornsError {
     constructor(gard: string | number | undefined);
 }
+/** The scoped key this worker joined on was revoked while it was connected. */
+declare class KeyRevokedError extends NornsError {
+    constructor();
+}
 /** A stream's socket closed before the run reached a terminal event. */
 declare class StreamClosedError extends NornsError {
     readonly reason: unknown;
@@ -675,5 +690,5 @@ type ToolResult = {
     error: string;
 };
 
-export { DEFAULT_MODEL, GardDestroyedError, JoinError, NornsApiError, NornsClient, NornsError, NornsTimeoutError, NornsWorker, NotFoundError, StreamClosedError, consoleLogger, defineAgent, inferProvider, silentLogger, tool };
+export { DEFAULT_MODEL, GardDestroyedError, JoinError, KeyRevokedError, NornsApiError, NornsClient, NornsError, NornsTimeoutError, NornsWorker, NotFoundError, StreamClosedError, consoleLogger, defineAgent, inferProvider, isScopedKey, silentLogger, tool };
 export type { AgentDefinition, AgentInfo, AgentMode, AgentOptions, AgentRef, Capability, CheckpointPolicy, ContextPolicy, ContextStrategy, Conversation, InferToolInput, ListRunsOptions, LlmResult, LlmTask, Logger, MessageResult, ModelResolver, ModelSource, ModelsOption, NeutralMessage, NeutralToolCall, NornsClientOptions, NornsWorkerOptions, OnFailure, RegisterPortOptions, RegisteredPort, Run, RunEvent, RunStatus, SendMessageOptions, StreamEvent, StreamOptions, SubagentConversation, SubagentPolicy, ToolContext, ToolDefinition, ToolInputSchema, ToolOptions, ToolResult, ToolTask, WaitingFor, WebSocketConstructor };

package/dist/index.js

@@ -34,7 +34,6 @@ function defineAgent(options) {
     model: options.model ?? DEFAULT_MODEL,
     systemPrompt: options.systemPrompt ?? "",
     tools: Object.freeze([...tools]),
-    mode: options.mode ?? "task",
     checkpointPolicy: options.checkpointPolicy ?? "on_tool_call",
     contextStrategy: options.contextStrategy ?? "sliding_window",
     contextWindow: options.contextWindow ?? 20,
@@ -49,7 +48,6 @@ function defineAgent(options) {
 }
 function agentBody(agent) {
   const modelConfig = {
-    mode: agent.mode,
     checkpoint_policy: agent.checkpointPolicy,
     context_strategy: agent.contextStrategy,
     context_window: agent.contextWindow,
@@ -206,6 +204,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) {
@@ -534,6 +538,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://");
 }
@@ -1247,9 +1254,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))) {
@@ -1300,6 +1313,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`);
@@ -1612,6 +1629,7 @@ export {
   DEFAULT_MODEL,
   GardDestroyedError,
   JoinError,
+  KeyRevokedError,
   NornsApiError,
   NornsClient,
   NornsError,
@@ -1622,6 +1640,7 @@ export {
   consoleLogger,
   defineAgent,
   inferProvider,
+  isScopedKey,
   jsonSchema3 as jsonSchema,
   silentLogger,
   tool