nuabase 3.0.1 → 3.1.0

package/dist/local-agent.d.cts

@@ -1,5 +1,5 @@
-import { c as AgentEffort, d as Logger, b as LocalAgentId, a as LocalAgent, e as SessionApproval } from './chunks/local-agent-Bj-QKikS.cjs';
-export { f as LOCAL_AGENT_IDS, g as LocalAgentCallOptions, i as isLocalAgentId } from './chunks/local-agent-Bj-QKikS.cjs';
+import { c as LocalAgentCallOptions, d as Logger, b as LocalAgentId, a as LocalAgent, e as SessionApproval } from './chunks/local-agent-CPIXKS41.cjs';
+export { f as AgentEffort, g as LOCAL_AGENT_IDS, i as isLocalAgentId } from './chunks/local-agent-CPIXKS41.cjs';
 
 /**
  * - subscription: removes API-key env vars (ANTHROPIC_API_KEY, OPENAI_API_KEY, ...) from the
@@ -7,13 +7,7 @@ export { f as LOCAL_AGENT_IDS, g as LocalAgentCallOptions, i as isLocalAgentId }
  * - inherit: passes the environment through unchanged.
  */
 type LocalAgentAuthMode = "subscription" | "inherit";
-type LocalAgentOptions = {
-    /** The agent's own model name (e.g. "haiku" for Claude Code) for calls that name no model. Defaults to the agent's default. */
-    model?: string;
-    /** How hard the model thinks, as the CLI's own reasoning or effort setting. Defaults to the CLI's default. */
-    effort?: AgentEffort;
-    /** Per-call limit in milliseconds. Defaults to 180000. */
-    timeoutMs?: number;
+type LocalAgentOptions = LocalAgentCallOptions & {
     /** Maximum agent processes running at once. Defaults to 2. */
     concurrency?: number;
     /** Defaults to "subscription". */
@@ -57,6 +51,40 @@ type LocalAgentStatus = {
  */
 declare function detectLocalAgents(binaryPaths?: Partial<Record<LocalAgentId, string>>): Promise<LocalAgentStatus[]>;
 
+/** How to install one supported coding-agent CLI and sign in to it. */
+type LocalAgentSetup = {
+    agent: LocalAgentId;
+    /** The agent's product name: "Claude Code". */
+    name: string;
+    /** The accounts it works with, short enough for a table cell. */
+    worksWith: string;
+    /** A shell command that installs the CLI. */
+    install: string;
+    /** How to sign in once, after installing, in a few words. Commands are in backticks. */
+    signIn: string;
+    docsUrl: string;
+};
+/**
+ * What an app tells a user who has no coding agent set up: that one is
+ * missing, how to install each supported one, and a prompt that has a
+ * desktop or browser agent do it for them. Plain text, ready to show as it is.
+ */
+type LocalAgentSetupGuide = {
+    /** One line saying no supported agent is set up. */
+    missing: string;
+    /** Why a desktop or browser app isn't enough: Nuabase runs the CLI. */
+    cliOnly: string;
+    /** In preference order, as findLocalAgent() tries them. */
+    agents: LocalAgentSetup[];
+    /**
+     * For the user to paste into a desktop or browser agent, such as the Claude
+     * or ChatGPT app, which can install a CLI though it can't be run as one.
+     */
+    setupPrompt: string;
+};
+/** Pure: how to set up a supported coding agent, for people who have none. */
+declare function localAgentSetupGuide(): LocalAgentSetupGuide;
+
 /**
  * How a session can be started on this platform:
  * - terminal: in a new terminal window.
@@ -85,6 +113,17 @@ type AgentSessionConfig = {
     name?: string;
     /** Defaults to process.platform. */
     platform?: NodeJS.Platform;
+    /**
+     * The environment `open` runs in on macOS. A terminal app it launches keeps
+     * it for every window, so leave out what other sessions shouldn't see.
+     * Defaults to process.env.
+     */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * Variables the launcher unsets before starting the agent, for a terminal
+     * that already holds them. Each must be a shell variable name.
+     */
+    unsetEnv?: readonly string[];
 };
 type AgentSessionFiles = {
     promptPath: string;
@@ -132,8 +171,8 @@ declare function agentSessionMode(platform?: NodeJS.Platform): AgentSessionMode;
 /**
  * Writes the prompt and a launcher that starts the agent on it, and where the
  * platform can, opens a terminal window running it. Expected failures come
- * back as the result; it throws only for an unknown agent or a `name` already
- * used. Node.js only.
+ * back as the result; it throws only for an unknown agent, an `unsetEnv` entry that
+ * isn't a variable name or a `name` already used. Node.js only.
  */
 declare function startAgentSession(config: AgentSessionConfig): Promise<AgentSessionStart>;
 type SessionLauncherTarget = {
@@ -142,9 +181,11 @@ type SessionLauncherTarget = {
     /** The agent's own options, which go before the prompt. */
     agentArgs: readonly string[];
     promptPath: string;
+    /** Variable names, unset before the agent starts. */
+    unsetEnv?: readonly string[];
 };
 /** Pure: the shell script that starts the agent on the prompt in `promptPath`. */
-declare function sessionLauncher({ cwd, binaryPath, agentArgs, promptPath }: SessionLauncherTarget): string;
+declare function sessionLauncher({ cwd, binaryPath, agentArgs, promptPath, unsetEnv, }: SessionLauncherTarget): string;
 
-export { AgentEffort, LocalAgent, LocalAgentId, Logger, SessionApproval, agentSessionMode, detectLocalAgents, findLocalAgent, localAgent, sessionLauncher, startAgentSession };
-export type { AgentSessionConfig, AgentSessionFiles, AgentSessionMode, AgentSessionRefusal, AgentSessionStart, LocalAgentAuthMode, LocalAgentConfig, LocalAgentOptions, LocalAgentStatus, SessionLauncherTarget };
+export { LocalAgent, LocalAgentCallOptions, LocalAgentId, Logger, SessionApproval, agentSessionMode, detectLocalAgents, findLocalAgent, localAgent, localAgentSetupGuide, sessionLauncher, startAgentSession };
+export type { AgentSessionConfig, AgentSessionFiles, AgentSessionMode, AgentSessionRefusal, AgentSessionStart, LocalAgentAuthMode, LocalAgentConfig, LocalAgentOptions, LocalAgentSetup, LocalAgentSetupGuide, LocalAgentStatus, SessionLauncherTarget };

package/dist/local-agent.d.mts

@@ -1,5 +1,5 @@
-import { c as AgentEffort, d as Logger, b as LocalAgentId, a as LocalAgent, e as SessionApproval } from './chunks/local-agent-Bj-QKikS.mjs';
-export { f as LOCAL_AGENT_IDS, g as LocalAgentCallOptions, i as isLocalAgentId } from './chunks/local-agent-Bj-QKikS.mjs';
+import { c as LocalAgentCallOptions, d as Logger, b as LocalAgentId, a as LocalAgent, e as SessionApproval } from './chunks/local-agent-CPIXKS41.mjs';
+export { f as AgentEffort, g as LOCAL_AGENT_IDS, i as isLocalAgentId } from './chunks/local-agent-CPIXKS41.mjs';
 
 /**
  * - subscription: removes API-key env vars (ANTHROPIC_API_KEY, OPENAI_API_KEY, ...) from the
@@ -7,13 +7,7 @@ export { f as LOCAL_AGENT_IDS, g as LocalAgentCallOptions, i as isLocalAgentId }
  * - inherit: passes the environment through unchanged.
  */
 type LocalAgentAuthMode = "subscription" | "inherit";
-type LocalAgentOptions = {
-    /** The agent's own model name (e.g. "haiku" for Claude Code) for calls that name no model. Defaults to the agent's default. */
-    model?: string;
-    /** How hard the model thinks, as the CLI's own reasoning or effort setting. Defaults to the CLI's default. */
-    effort?: AgentEffort;
-    /** Per-call limit in milliseconds. Defaults to 180000. */
-    timeoutMs?: number;
+type LocalAgentOptions = LocalAgentCallOptions & {
     /** Maximum agent processes running at once. Defaults to 2. */
     concurrency?: number;
     /** Defaults to "subscription". */
@@ -57,6 +51,40 @@ type LocalAgentStatus = {
  */
 declare function detectLocalAgents(binaryPaths?: Partial<Record<LocalAgentId, string>>): Promise<LocalAgentStatus[]>;
 
+/** How to install one supported coding-agent CLI and sign in to it. */
+type LocalAgentSetup = {
+    agent: LocalAgentId;
+    /** The agent's product name: "Claude Code". */
+    name: string;
+    /** The accounts it works with, short enough for a table cell. */
+    worksWith: string;
+    /** A shell command that installs the CLI. */
+    install: string;
+    /** How to sign in once, after installing, in a few words. Commands are in backticks. */
+    signIn: string;
+    docsUrl: string;
+};
+/**
+ * What an app tells a user who has no coding agent set up: that one is
+ * missing, how to install each supported one, and a prompt that has a
+ * desktop or browser agent do it for them. Plain text, ready to show as it is.
+ */
+type LocalAgentSetupGuide = {
+    /** One line saying no supported agent is set up. */
+    missing: string;
+    /** Why a desktop or browser app isn't enough: Nuabase runs the CLI. */
+    cliOnly: string;
+    /** In preference order, as findLocalAgent() tries them. */
+    agents: LocalAgentSetup[];
+    /**
+     * For the user to paste into a desktop or browser agent, such as the Claude
+     * or ChatGPT app, which can install a CLI though it can't be run as one.
+     */
+    setupPrompt: string;
+};
+/** Pure: how to set up a supported coding agent, for people who have none. */
+declare function localAgentSetupGuide(): LocalAgentSetupGuide;
+
 /**
  * How a session can be started on this platform:
  * - terminal: in a new terminal window.
@@ -85,6 +113,17 @@ type AgentSessionConfig = {
     name?: string;
     /** Defaults to process.platform. */
     platform?: NodeJS.Platform;
+    /**
+     * The environment `open` runs in on macOS. A terminal app it launches keeps
+     * it for every window, so leave out what other sessions shouldn't see.
+     * Defaults to process.env.
+     */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * Variables the launcher unsets before starting the agent, for a terminal
+     * that already holds them. Each must be a shell variable name.
+     */
+    unsetEnv?: readonly string[];
 };
 type AgentSessionFiles = {
     promptPath: string;
@@ -132,8 +171,8 @@ declare function agentSessionMode(platform?: NodeJS.Platform): AgentSessionMode;
 /**
  * Writes the prompt and a launcher that starts the agent on it, and where the
  * platform can, opens a terminal window running it. Expected failures come
- * back as the result; it throws only for an unknown agent or a `name` already
- * used. Node.js only.
+ * back as the result; it throws only for an unknown agent, an `unsetEnv` entry that
+ * isn't a variable name or a `name` already used. Node.js only.
  */
 declare function startAgentSession(config: AgentSessionConfig): Promise<AgentSessionStart>;
 type SessionLauncherTarget = {
@@ -142,9 +181,11 @@ type SessionLauncherTarget = {
     /** The agent's own options, which go before the prompt. */
     agentArgs: readonly string[];
     promptPath: string;
+    /** Variable names, unset before the agent starts. */
+    unsetEnv?: readonly string[];
 };
 /** Pure: the shell script that starts the agent on the prompt in `promptPath`. */
-declare function sessionLauncher({ cwd, binaryPath, agentArgs, promptPath }: SessionLauncherTarget): string;
+declare function sessionLauncher({ cwd, binaryPath, agentArgs, promptPath, unsetEnv, }: SessionLauncherTarget): string;
 
-export { AgentEffort, LocalAgent, LocalAgentId, Logger, SessionApproval, agentSessionMode, detectLocalAgents, findLocalAgent, localAgent, sessionLauncher, startAgentSession };
-export type { AgentSessionConfig, AgentSessionFiles, AgentSessionMode, AgentSessionRefusal, AgentSessionStart, LocalAgentAuthMode, LocalAgentConfig, LocalAgentOptions, LocalAgentStatus, SessionLauncherTarget };
+export { LocalAgent, LocalAgentCallOptions, LocalAgentId, Logger, SessionApproval, agentSessionMode, detectLocalAgents, findLocalAgent, localAgent, localAgentSetupGuide, sessionLauncher, startAgentSession };
+export type { AgentSessionConfig, AgentSessionFiles, AgentSessionMode, AgentSessionRefusal, AgentSessionStart, LocalAgentAuthMode, LocalAgentConfig, LocalAgentOptions, LocalAgentSetup, LocalAgentSetupGuide, LocalAgentStatus, SessionLauncherTarget };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nuabase",
   "description": "Nuabase TypeScript client to create typed functions from LLM prompts",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "type": "module",
   "author": "Jasim A Basheer <jasim@nuabase.com>",
   "engines": {