@granular-software/sdk 0.4.10 → 0.4.12

package/README.md

@@ -48,6 +48,8 @@ CLI overrides:
 - `granular --prod <command>`
 - `granular --env local|production <command>`
 
+When the resolved API URL points at `localhost` or `127.0.0.1`, the SDK and CLI automatically swap opaque `sk_...` WorkOS keys for the local dev key `gn_sk_tenant_default_principal_local_e2e_00000000` so local runs work without server-side WorkOS validation. Override with `GRANULAR_LOCAL_API_KEY=...` or disable with `GRANULAR_DISABLE_LOCAL_API_KEY_FALLBACK=true`.
+
 ## Agent documentation (CLI)
 
 Projects created with `granular init` can include Markdown for coding agents (optional `AGENTS.md` plus generated guides):

package/dist/cli/index.js

@@ -5388,6 +5388,7 @@ var import_dotenv = __toESM(require_main());
 // src/endpoints.ts
 var LOCAL_API_URL = "ws://localhost:8787/granular";
 var PRODUCTION_API_URL = "wss://cf-api-gateway.arthur6084.workers.dev/granular";
+var DEFAULT_LOCAL_API_KEY = "gn_sk_tenant_default_principal_local_e2e_00000000";
 var LOCAL_AUTH_URL = "http://localhost:3000";
 var PRODUCTION_AUTH_URL = "https://app.granular.software";
 function readEnv(name) {
@@ -5407,6 +5408,21 @@ function isTruthy(value) {
   const normalized = value.trim().toLowerCase();
   return normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on";
 }
+function isLocalApiUrl(url) {
+  try {
+    const parsed = new URL(url);
+    return parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1";
+  } catch {
+    return false;
+  }
+}
+function resolveAuthTokenForApiUrl(authToken, apiUrl) {
+  if (!authToken.startsWith("sk_") || !isLocalApiUrl(apiUrl) || isTruthy(readEnv("GRANULAR_DISABLE_LOCAL_API_KEY_FALLBACK"))) {
+    return authToken;
+  }
+  const override = readEnv("GRANULAR_LOCAL_API_KEY")?.trim();
+  return override || DEFAULT_LOCAL_API_KEY;
+}
 function resolveEndpointMode(explicitMode) {
   const explicit = normalizeMode(explicitMode);
   if (explicit === "local" || explicit === "production") {
@@ -6762,7 +6778,7 @@ var ApiClient = class {
   apiKey;
   baseUrl;
   constructor(apiKey, apiUrl) {
-    this.apiKey = apiKey;
+    this.apiKey = resolveAuthTokenForApiUrl(apiKey, apiUrl);
     this.baseUrl = apiUrl.replace("wss://", "https://").replace("ws://", "http://").replace(/\/ws$/, "");
   }
   async request(path4, options = {}) {
@@ -9722,7 +9738,7 @@ async function initCommand(projectName, options) {
   dim("  The seed script shows how records enter the graph. The effects script shows how external systems plug in.");
   console.log();
 }
-var DEFAULT_LOCAL_API_KEY = "gn_sk_tenant_default_principal_local_e2e_00000000";
+var DEFAULT_LOCAL_API_KEY2 = "gn_sk_tenant_default_principal_local_e2e_00000000";
 function promptSecret(question) {
   const rl = readline__namespace.createInterface({ input: process.stdin, output: process.stdout });
   return new Promise((resolve) => {
@@ -9748,7 +9764,7 @@ function maskApiKey(apiKey) {
   if (apiKey.length < 10) return `${apiKey}...`;
   return `${apiKey.substring(0, 10)}...`;
 }
-function isLocalApiUrl(apiUrl) {
+function isLocalApiUrl2(apiUrl) {
   return apiUrl.startsWith("ws://localhost:") || apiUrl.startsWith("wss://localhost:") || apiUrl.startsWith("ws://127.0.0.1:") || apiUrl.startsWith("wss://127.0.0.1:") || apiUrl.startsWith("http://localhost:") || apiUrl.startsWith("https://localhost:") || apiUrl.startsWith("http://127.0.0.1:") || apiUrl.startsWith("https://127.0.0.1:");
 }
 async function loginCommand(options = {}) {
@@ -9762,8 +9778,8 @@ async function loginCommand(options = {}) {
   const apiUrl = loadApiUrl();
   let apiKey = options.apiKey?.trim();
   if (!apiKey) {
-    if (!options.manual && isLocalApiUrl(apiUrl)) {
-      apiKey = existing?.trim() || process.env.GRANULAR_LOCAL_API_KEY?.trim() || DEFAULT_LOCAL_API_KEY;
+    if (!options.manual && isLocalApiUrl2(apiUrl)) {
+      apiKey = existing?.trim() || process.env.GRANULAR_LOCAL_API_KEY?.trim() || DEFAULT_LOCAL_API_KEY2;
       info("Using local Granular API key for localhost development.");
     } else if (options.manual) {
       dim("Get your API key at https://app.granular.software/w/default/api-keys");
@@ -10324,13 +10340,19 @@ function openUrl(url) {
   const cmd = platform === "darwin" ? "open" : platform === "win32" ? "start" : "xdg-open";
   child_process.spawn(cmd, [url], { stdio: "ignore", shell: platform === "win32" });
 }
-async function simulateCommand(sandboxIdArg) {
+async function simulateCommand(sandboxIdArg, options) {
   const sandboxId = sandboxIdArg ?? resolveConfig().sandboxId;
   if (!sandboxId) {
     error("No sandbox ID. Run from a project with `granular init` or pass a sandbox ID: granular simulate <sandbox-id>");
     process.exit(1);
   }
-  const url = `${SIMULATOR_BASE}?sandboxId=${encodeURIComponent(sandboxId)}`;
+  const params = new URLSearchParams({
+    sandboxId
+  });
+  if (options?.subjectId) {
+    params.set("subject_id", options.subjectId);
+  }
+  const url = `${SIMULATOR_BASE}?${params.toString()}`;
   info(`Opening simulator: ${url}`);
   openUrl(url);
 }
@@ -10470,9 +10492,9 @@ program2.command("document").description("Generate GRANULAR_SANDBOX.md (agent re
     process.exit(1);
   }
 });
-program2.command("simulate [sandbox-id]").description("Open the Granular simulator in the browser for the current (or given) sandbox").action(async (sandboxId) => {
+program2.command("simulate [sandbox-id]").description("Open the Granular simulator in the browser for the current (or given) sandbox").option("--subject-id <subjectId>", "Open the simulator preloaded for a specific subject").action(async (sandboxId, options) => {
   try {
-    await simulateCommand(sandboxId);
+    await simulateCommand(sandboxId, options);
   } catch (err) {
     error(err.message);
     process.exit(1);

package/dist/index.d.mts

@@ -457,7 +457,7 @@ interface EffectsChangedEvent extends ToolsChangedEvent {
 }
 type EffectHandler = ToolHandler;
 type InstanceEffectHandler = InstanceToolHandler;
-type JobStatus = 'queued' | 'running' | 'succeeded' | 'failed' | 'timeout' | 'canceled';
+type JobStatus = 'queued' | 'running' | 'awaitingTool' | 'awaitingHuman' | 'succeeded' | 'failed' | 'timeout' | 'canceled';
 type JobFeedbackSentiment = 'good' | 'bad';
 interface JobFeedbackToolCall {
     callId?: string;
@@ -529,8 +529,15 @@ interface Prompt {
     type: 'confirm' | 'choice' | 'input';
     title: string;
     message: string;
-    options?: string[];
+    options?: Array<string | {
+        value: string;
+        label: string;
+        description?: string;
+    }>;
     defaultValue?: unknown;
+    placeholder?: string;
+    allowEmpty?: boolean;
+    metadata?: Record<string, unknown>;
 }
 type SessionHeapFieldType = 'string' | 'number' | 'boolean' | 'null' | 'unknown';
 interface SessionHeapFieldValue {

package/dist/index.d.ts

@@ -457,7 +457,7 @@ interface EffectsChangedEvent extends ToolsChangedEvent {
 }
 type EffectHandler = ToolHandler;
 type InstanceEffectHandler = InstanceToolHandler;
-type JobStatus = 'queued' | 'running' | 'succeeded' | 'failed' | 'timeout' | 'canceled';
+type JobStatus = 'queued' | 'running' | 'awaitingTool' | 'awaitingHuman' | 'succeeded' | 'failed' | 'timeout' | 'canceled';
 type JobFeedbackSentiment = 'good' | 'bad';
 interface JobFeedbackToolCall {
     callId?: string;
@@ -529,8 +529,15 @@ interface Prompt {
     type: 'confirm' | 'choice' | 'input';
     title: string;
     message: string;
-    options?: string[];
+    options?: Array<string | {
+        value: string;
+        label: string;
+        description?: string;
+    }>;
     defaultValue?: unknown;
+    placeholder?: string;
+    allowEmpty?: boolean;
+    metadata?: Record<string, unknown>;
 }
 type SessionHeapFieldType = 'string' | 'number' | 'boolean' | 'null' | 'unknown';
 interface SessionHeapFieldValue {

package/dist/index.js

@@ -4650,7 +4650,7 @@ var Session = class {
    * Respond to a prompt request from the sandbox
    */
   async answerPrompt(promptId, answer) {
-    await this.client.call("prompt.answer", { promptId, value: answer });
+    await this.client.call("prompt.answer", { promptId, answer, value: answer });
   }
   /**
    * Get the current list of available effects.
@@ -4967,13 +4967,31 @@ import { ${allImports} } from "./sandbox-tools";
     });
   }
   setupEventHandlers() {
+    this.client.on("open", (payload) => this.emit("open", payload || {}));
     this.client.on("sync", (doc) => {
       this.currentDomainRevision = this.extractDomainRevisionFromDoc(doc);
       this.emit("sync", doc);
       this.checkForToolChanges();
     });
-    this.client.on("prompt", (prompt) => this.emit("prompt", prompt));
+    const emitPrompt = (payload) => {
+      const raw = payload;
+      const prompt = raw.prompt || {
+        id: typeof raw.id === "string" ? raw.id : String(raw.promptId || ""),
+        type: raw.type === "confirm" || raw.type === "choice" || raw.type === "input" ? raw.type : raw.promptType === "confirm" || raw.promptType === "choice" ? raw.promptType : "input",
+        title: typeof raw.title === "string" ? raw.title : "Input required",
+        message: typeof raw.message === "string" ? raw.message : "",
+        options: raw.options,
+        defaultValue: raw.defaultValue,
+        placeholder: raw.placeholder,
+        allowEmpty: raw.allowEmpty,
+        metadata: raw.metadata
+      };
+      this.emit("prompt", prompt);
+    };
+    this.client.on("prompt", emitPrompt);
+    this.client.on("prompt.request", emitPrompt);
     this.client.on("disconnect", (payload) => this.emit("disconnect", payload || {}));
+    this.client.on("reconnect_error", (payload) => this.emit("reconnect_error", payload || {}));
     this.client.on("job.status", (data) => {
       this.emit("job:status", data);
     });
@@ -5045,6 +5063,8 @@ function normalizeJobStatus(status) {
     case "failed":
     case "running":
     case "queued":
+    case "awaitingTool":
+    case "awaitingHuman":
     case "succeeded":
     case "timeout":
     case "canceled":
@@ -5179,6 +5199,19 @@ var JobImplementation = class {
     this.client.on(`job.${id}.error`, (error) => {
       this.finalize("failed", void 0, error);
     });
+    this.client.on("job.status", (data) => {
+      const jobData = data;
+      if (jobData.jobId !== id) {
+        return;
+      }
+      const normalizedStatus = normalizeJobStatus(jobData.status);
+      this.status = normalizedStatus;
+      this.metadata.status = normalizedStatus;
+      if (normalizedStatus === "running") {
+        this.markStarted();
+      }
+      this.emit("status", normalizedStatus);
+    });
     this.client.on("job.completed", (data) => {
       const jobData = data;
       if (jobData.jobId === id) {
@@ -5316,6 +5349,7 @@ var JobImplementation = class {
 // src/endpoints.ts
 var LOCAL_API_URL = "ws://localhost:8787/granular";
 var PRODUCTION_API_URL = "wss://cf-api-gateway.arthur6084.workers.dev/granular";
+var DEFAULT_LOCAL_API_KEY = "gn_sk_tenant_default_principal_local_e2e_00000000";
 function readEnv(name) {
   if (typeof process === "undefined" || !process.env) return void 0;
   return process.env[name];
@@ -5333,6 +5367,21 @@ function isTruthy(value) {
   const normalized = value.trim().toLowerCase();
   return normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on";
 }
+function isLocalApiUrl(url) {
+  try {
+    const parsed = new URL(url);
+    return parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1";
+  } catch {
+    return false;
+  }
+}
+function resolveAuthTokenForApiUrl(authToken, apiUrl) {
+  if (!authToken.startsWith("sk_") || !isLocalApiUrl(apiUrl) || isTruthy(readEnv("GRANULAR_DISABLE_LOCAL_API_KEY_FALLBACK"))) {
+    return authToken;
+  }
+  const override = readEnv("GRANULAR_LOCAL_API_KEY")?.trim();
+  return override || DEFAULT_LOCAL_API_KEY;
+}
 function resolveEndpointMode(explicitMode) {
   const explicit = normalizeMode(explicitMode);
   if (explicit === "local" || explicit === "production") {
@@ -6251,8 +6300,8 @@ var Granular = class {
     if (!auth) {
       throw new Error("Granular client requires either apiKey or token. Set GRANULAR_API_KEY or GRANULAR_TOKEN, or pass one in options.");
     }
-    this.apiKey = auth;
     this.apiUrl = resolveApiUrl(options.apiUrl, options.endpointMode);
+    this.apiKey = resolveAuthTokenForApiUrl(auth, this.apiUrl);
     this.tokenProvider = options.tokenProvider;
     this.WebSocketCtor = options.WebSocketCtor;
     this.onUnexpectedClose = options.onUnexpectedClose;