@robota-sdk/agent-sdk 3.0.0-beta.3 → 3.0.0-beta.4

package/dist/node/index.cjs

@@ -30,43 +30,184 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  FileSessionLogger: () => import_agent_sessions5.FileSessionLogger,
-  Session: () => import_agent_sessions.Session,
-  SessionStore: () => import_agent_sessions2.SessionStore,
-  SilentSessionLogger: () => import_agent_sessions5.SilentSessionLogger,
+  DEFAULT_TOOL_DESCRIPTIONS: () => DEFAULT_TOOL_DESCRIPTIONS,
+  FileSessionLogger: () => import_agent_sessions3.FileSessionLogger,
+  Session: () => import_agent_sessions2.Session,
+  SessionStore: () => import_agent_sessions4.SessionStore,
+  SilentSessionLogger: () => import_agent_sessions3.SilentSessionLogger,
   TRUST_TO_MODE: () => import_agent_core.TRUST_TO_MODE,
   agentTool: () => agentTool,
-  bashTool: () => import_agent_tools.bashTool,
+  bashTool: () => import_agent_tools3.bashTool,
   buildSystemPrompt: () => buildSystemPrompt,
+  createDefaultTools: () => createDefaultTools,
+  createProvider: () => createProvider,
+  createSession: () => createSession,
   detectProject: () => detectProject,
-  editTool: () => import_agent_tools4.editTool,
+  editTool: () => import_agent_tools6.editTool,
   evaluatePermission: () => import_agent_core2.evaluatePermission,
-  globTool: () => import_agent_tools5.globTool,
-  grepTool: () => import_agent_tools6.grepTool,
+  globTool: () => import_agent_tools7.globTool,
+  grepTool: () => import_agent_tools8.grepTool,
   loadConfig: () => loadConfig,
   loadContext: () => loadContext,
   projectPaths: () => projectPaths,
   promptForApproval: () => promptForApproval,
   query: () => query,
-  readTool: () => import_agent_tools2.readTool,
+  readTool: () => import_agent_tools4.readTool,
   runHooks: () => import_agent_core3.runHooks,
   setAgentToolDeps: () => setAgentToolDeps,
   userPaths: () => userPaths,
-  writeTool: () => import_agent_tools3.writeTool
+  writeTool: () => import_agent_tools5.writeTool
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/types.ts
 var import_agent_core = require("@robota-sdk/agent-core");
 
-// src/session.ts
+// src/assembly/create-session.ts
 var import_agent_sessions = require("@robota-sdk/agent-sessions");
 
-// src/index.ts
-var import_agent_sessions5 = require("@robota-sdk/agent-sessions");
+// src/context/system-prompt-builder.ts
+var TRUST_LEVEL_DESCRIPTIONS = {
+  safe: "safe (read-only / plan mode \u2014 only read-access tools are available)",
+  moderate: "moderate (default mode \u2014 write and bash tools require approval)",
+  full: "full (acceptEdits mode \u2014 file writes are auto-approved; bash requires approval)"
+};
+function buildProjectSection(info) {
+  const lines = ["## Current Project"];
+  if (info.name !== void 0) {
+    lines.push(`- **Name:** ${info.name}`);
+  }
+  if (info.type !== "unknown") {
+    lines.push(`- **Type:** ${info.type}`);
+  }
+  if (info.language !== "unknown") {
+    lines.push(`- **Language:** ${info.language}`);
+  }
+  if (info.packageManager !== void 0) {
+    lines.push(`- **Package manager:** ${info.packageManager}`);
+  }
+  return lines.join("\n");
+}
+function buildToolsSection(descriptions) {
+  if (descriptions.length === 0) {
+    return "";
+  }
+  const lines = ["## Available Tools", ...descriptions.map((d) => `- ${d}`)];
+  return lines.join("\n");
+}
+function buildSystemPrompt(params) {
+  const { agentsMd, claudeMd, toolDescriptions, trustLevel, projectInfo } = params;
+  const sections = [];
+  sections.push(
+    [
+      "## Role",
+      "You are an AI coding assistant with access to tools that let you read and modify code.",
+      "You help developers understand, write, and improve their codebase.",
+      "Always be precise, follow existing code conventions, and prefer minimal changes."
+    ].join("\n")
+  );
+  sections.push(buildProjectSection(projectInfo));
+  sections.push(
+    [
+      "## Permission Mode",
+      `Your current trust level is **${TRUST_LEVEL_DESCRIPTIONS[trustLevel]}**.`
+    ].join("\n")
+  );
+  if (agentsMd.trim().length > 0) {
+    sections.push(["## Agent Instructions", agentsMd].join("\n"));
+  }
+  if (claudeMd.trim().length > 0) {
+    sections.push(["## Project Notes", claudeMd].join("\n"));
+  }
+  sections.push(
+    [
+      "## Web Search",
+      "You have access to web search. When the user asks to search, look up, or find current/latest information,",
+      "you MUST use the web_search tool. Do NOT answer from training data when the user explicitly asks to search.",
+      "Always prefer web search for: news, latest versions, current events, live documentation."
+    ].join("\n")
+  );
+  const toolsSection = buildToolsSection(toolDescriptions);
+  if (toolsSection.length > 0) {
+    sections.push(toolsSection);
+  }
+  return sections.join("\n\n");
+}
+
+// src/assembly/create-tools.ts
+var import_agent_tools = require("@robota-sdk/agent-tools");
+var DEFAULT_TOOL_DESCRIPTIONS = [
+  "Bash \u2014 execute shell commands",
+  "Read \u2014 read file contents with line numbers",
+  "Write \u2014 write content to a file",
+  "Edit \u2014 replace a string in a file",
+  "Glob \u2014 find files matching a pattern",
+  "Grep \u2014 search file contents with regex",
+  "WebSearch \u2014 search the internet (Anthropic built-in)"
+];
+function createDefaultTools() {
+  return [
+    import_agent_tools.bashTool,
+    import_agent_tools.readTool,
+    import_agent_tools.writeTool,
+    import_agent_tools.editTool,
+    import_agent_tools.globTool,
+    import_agent_tools.grepTool,
+    import_agent_tools.webFetchTool,
+    import_agent_tools.webSearchTool
+  ];
+}
+
+// src/assembly/create-provider.ts
+var import_agent_provider_anthropic = require("@robota-sdk/agent-provider-anthropic");
+function createProvider(config) {
+  const apiKey = config.provider.apiKey ?? process.env["ANTHROPIC_API_KEY"];
+  if (!apiKey) {
+    throw new Error(
+      "ANTHROPIC_API_KEY is not set. Set the environment variable or configure provider.apiKey in ~/.robota/settings.json"
+    );
+  }
+  return new import_agent_provider_anthropic.AnthropicProvider({ apiKey });
+}
+
+// src/assembly/create-session.ts
+function createSession(options) {
+  const provider = options.provider ?? createProvider(options.config);
+  const defaultTools = createDefaultTools();
+  const tools = [...defaultTools, ...options.additionalTools ?? []];
+  const buildPrompt = options.systemPromptBuilder ?? buildSystemPrompt;
+  const systemMessage = buildPrompt({
+    agentsMd: options.context.agentsMd,
+    claudeMd: options.context.claudeMd,
+    toolDescriptions: options.toolDescriptions ?? DEFAULT_TOOL_DESCRIPTIONS,
+    trustLevel: options.config.defaultTrustLevel,
+    projectInfo: options.projectInfo ?? { type: "unknown", language: "unknown" }
+  });
+  return new import_agent_sessions.Session({
+    tools,
+    provider,
+    systemMessage,
+    terminal: options.terminal,
+    permissions: options.config.permissions,
+    hooks: options.config.hooks,
+    permissionMode: options.permissionMode,
+    defaultTrustLevel: options.config.defaultTrustLevel,
+    model: options.config.provider.model,
+    maxTurns: options.maxTurns,
+    sessionStore: options.sessionStore,
+    permissionHandler: options.permissionHandler,
+    onTextDelta: options.onTextDelta,
+    promptForApproval: options.promptForApproval,
+    onCompact: options.onCompact,
+    compactInstructions: options.compactInstructions ?? options.context.compactInstructions,
+    sessionLogger: options.sessionLogger
+  });
+}
 
-// src/session-store.ts
+// src/index.ts
 var import_agent_sessions2 = require("@robota-sdk/agent-sessions");
+var import_agent_sessions3 = require("@robota-sdk/agent-sessions");
+var import_agent_sessions4 = require("@robota-sdk/agent-sessions");
 
 // src/config/config-loader.ts
 var import_fs = require("fs");
@@ -331,77 +472,6 @@ async function detectProject(cwd) {
   };
 }
 
-// src/context/system-prompt-builder.ts
-var TRUST_LEVEL_DESCRIPTIONS = {
-  safe: "safe (read-only / plan mode \u2014 only read-access tools are available)",
-  moderate: "moderate (default mode \u2014 write and bash tools require approval)",
-  full: "full (acceptEdits mode \u2014 file writes are auto-approved; bash requires approval)"
-};
-function buildProjectSection(info) {
-  const lines = ["## Current Project"];
-  if (info.name !== void 0) {
-    lines.push(`- **Name:** ${info.name}`);
-  }
-  if (info.type !== "unknown") {
-    lines.push(`- **Type:** ${info.type}`);
-  }
-  if (info.language !== "unknown") {
-    lines.push(`- **Language:** ${info.language}`);
-  }
-  if (info.packageManager !== void 0) {
-    lines.push(`- **Package manager:** ${info.packageManager}`);
-  }
-  return lines.join("\n");
-}
-function buildToolsSection(descriptions) {
-  if (descriptions.length === 0) {
-    return "";
-  }
-  const lines = ["## Available Tools", ...descriptions.map((d) => `- ${d}`)];
-  return lines.join("\n");
-}
-function buildSystemPrompt(params) {
-  const { agentsMd, claudeMd, toolDescriptions, trustLevel, projectInfo } = params;
-  const sections = [];
-  sections.push(
-    [
-      "## Role",
-      "You are an AI coding assistant with access to tools that let you read and modify code.",
-      "You help developers understand, write, and improve their codebase.",
-      "Always be precise, follow existing code conventions, and prefer minimal changes."
-    ].join("\n")
-  );
-  sections.push(buildProjectSection(projectInfo));
-  sections.push(
-    [
-      "## Permission Mode",
-      `Your current trust level is **${TRUST_LEVEL_DESCRIPTIONS[trustLevel]}**.`
-    ].join("\n")
-  );
-  if (agentsMd.trim().length > 0) {
-    sections.push(["## Agent Instructions", agentsMd].join("\n"));
-  }
-  if (claudeMd.trim().length > 0) {
-    sections.push(["## Project Notes", claudeMd].join("\n"));
-  }
-  sections.push(
-    [
-      "## Web Search",
-      "You have access to web search. When the user asks to search, look up, or find current/latest information,",
-      "you MUST use the web_search tool. Do NOT answer from training data when the user explicitly asks to search.",
-      "Always prefer web search for: news, latest versions, current events, live documentation."
-    ].join("\n")
-  );
-  const toolsSection = buildToolsSection(toolDescriptions);
-  if (toolsSection.length > 0) {
-    sections.push(toolsSection);
-  }
-  return sections.join("\n\n");
-}
-
-// src/query.ts
-var import_agent_sessions3 = require("@robota-sdk/agent-sessions");
-
 // src/permissions/permission-prompt.ts
 var import_chalk = __toESM(require("chalk"), 1);
 var PERMISSION_OPTIONS = ["Allow", "Deny"];
@@ -445,7 +515,7 @@ async function query(prompt, options) {
     }, update: () => {
     } })
   };
-  const session = new import_agent_sessions3.Session({
+  const session = createSession({
     config,
     context,
     terminal: noopTerminal,
@@ -457,16 +527,13 @@ async function query(prompt, options) {
     onTextDelta: options?.onTextDelta,
     onCompact: options?.onCompact,
     compactInstructions: context.compactInstructions,
-    systemPromptBuilder: buildSystemPrompt,
     promptForApproval
   });
   return session.run(prompt);
 }
 
-// src/permissions/permission-gate.ts
+// src/index.ts
 var import_agent_core2 = require("@robota-sdk/agent-core");
-
-// src/hooks/hook-runner.ts
 var import_agent_core3 = require("@robota-sdk/agent-core");
 
 // src/paths.ts
@@ -489,28 +556,9 @@ function userPaths() {
   };
 }
 
-// src/tools/bash-tool.ts
-var import_agent_tools = require("@robota-sdk/agent-tools");
-
-// src/tools/read-tool.ts
-var import_agent_tools2 = require("@robota-sdk/agent-tools");
-
-// src/tools/write-tool.ts
-var import_agent_tools3 = require("@robota-sdk/agent-tools");
-
-// src/tools/edit-tool.ts
-var import_agent_tools4 = require("@robota-sdk/agent-tools");
-
-// src/tools/glob-tool.ts
-var import_agent_tools5 = require("@robota-sdk/agent-tools");
-
-// src/tools/grep-tool.ts
-var import_agent_tools6 = require("@robota-sdk/agent-tools");
-
 // src/tools/agent-tool.ts
 var import_zod2 = require("zod");
-var import_agent_tools7 = require("@robota-sdk/agent-tools");
-var import_agent_sessions4 = require("@robota-sdk/agent-sessions");
+var import_agent_tools2 = require("@robota-sdk/agent-tools");
 function asZodSchema(schema) {
   return schema;
 }
@@ -531,26 +579,26 @@ async function runAgent(args) {
     };
     return JSON.stringify(result);
   }
-  const subSession = new import_agent_sessions4.Session({
+  const noopTerminal = {
+    write: () => {
+    },
+    writeLine: () => {
+    },
+    writeMarkdown: () => {
+    },
+    writeError: () => {
+    },
+    prompt: () => Promise.resolve(""),
+    select: () => Promise.resolve(0),
+    spinner: () => ({ stop: () => {
+    }, update: () => {
+    } })
+  };
+  const subSession = createSession({
     config: agentToolDeps.config,
     context: agentToolDeps.context,
     projectInfo: agentToolDeps.projectInfo,
-    // No terminal needed — sub-agents don't prompt for permissions
-    terminal: {
-      write: () => {
-      },
-      writeLine: () => {
-      },
-      writeMarkdown: () => {
-      },
-      writeError: () => {
-      },
-      prompt: () => Promise.resolve(""),
-      select: () => Promise.resolve(0),
-      spinner: () => ({ stop: () => {
-      }, update: () => {
-      } })
-    },
+    terminal: noopTerminal,
     // Sub-agents bypass permissions — they inherit parent's trust
     permissionMode: "bypassPermissions"
   });
@@ -571,7 +619,7 @@ async function runAgent(args) {
     return JSON.stringify(result);
   }
 }
-var agentTool = (0, import_agent_tools7.createZodFunctionTool)(
+var agentTool = (0, import_agent_tools2.createZodFunctionTool)(
   "Agent",
   "Spawn a sub-agent with isolated context to handle a task. The sub-agent has its own conversation history and can use all tools.",
   asZodSchema(AgentSchema),
@@ -579,8 +627,17 @@ var agentTool = (0, import_agent_tools7.createZodFunctionTool)(
     return runAgent(params);
   }
 );
+
+// src/index.ts
+var import_agent_tools3 = require("@robota-sdk/agent-tools");
+var import_agent_tools4 = require("@robota-sdk/agent-tools");
+var import_agent_tools5 = require("@robota-sdk/agent-tools");
+var import_agent_tools6 = require("@robota-sdk/agent-tools");
+var import_agent_tools7 = require("@robota-sdk/agent-tools");
+var import_agent_tools8 = require("@robota-sdk/agent-tools");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  DEFAULT_TOOL_DESCRIPTIONS,
   FileSessionLogger,
   Session,
   SessionStore,
@@ -589,6 +646,9 @@ var agentTool = (0, import_agent_tools7.createZodFunctionTool)(
   agentTool,
   bashTool,
   buildSystemPrompt,
+  createDefaultTools,
+  createProvider,
+  createSession,
   detectProject,
   editTool,
   evaluatePermission,

package/dist/node/index.d.cts

@@ -1,33 +1,11 @@
-import { TPermissionMode, IAIProvider, TToolArgs, TTrustLevel } from '@robota-sdk/agent-core';
+import { TTrustLevel, TPermissionMode, IAIProvider, TToolArgs, IToolWithEventService } from '@robota-sdk/agent-core';
 export { IContextTokenUsage, IContextWindowState, IHookInput, IPermissionLists, THookEvent, THooksConfig, TPermissionDecision, TPermissionMode, TRUST_TO_MODE, TToolArgs, TTrustLevel, evaluatePermission, runHooks } from '@robota-sdk/agent-core';
 import * as _robota_sdk_agent_tools from '@robota-sdk/agent-tools';
 export { TToolResult, bashTool, editTool, globTool, grepTool, readTool, writeTool } from '@robota-sdk/agent-tools';
-import { ITerminalOutput, IResolvedConfig as IResolvedConfig$1, ILoadedContext as ILoadedContext$1, IProjectInfo as IProjectInfo$1 } from '@robota-sdk/agent-sessions';
+import { ITerminalOutput, SessionStore, TPermissionHandler, ISessionLogger, Session } from '@robota-sdk/agent-sessions';
 export { FileSessionLogger, ISessionLogger, ISessionOptions, ISessionRecord, ISpinner, ITerminalOutput, Session, SessionStore, SilentSessionLogger, TPermissionHandler, TPermissionResult, TSessionLogData } from '@robota-sdk/agent-sessions';
 import { z } from 'zod';
 
-/**
- * query() — single entry point for running an AI agent conversation.
- * Automatically loads config, context, and project info.
- */
-
-interface IQueryOptions {
-    cwd?: string;
-    permissionMode?: TPermissionMode;
-    maxTurns?: number;
-    provider?: IAIProvider;
-    permissionHandler?: (toolName: string, toolArgs: TToolArgs) => Promise<boolean>;
-    onTextDelta?: (delta: string) => void;
-    /** Callback when context is compacted */
-    onCompact?: (summary: string) => void;
-}
-/**
- * query() — single entry point for running an AI agent conversation.
- * Equivalent to Claude Agent SDK's query() function.
- * Automatically loads config, context, and project info.
- */
-declare function query(prompt: string, options?: IQueryOptions): Promise<string>;
-
 /**
  * Zod schemas and TypeScript types for Robota CLI settings
  */
@@ -210,13 +188,6 @@ interface IResolvedConfig {
     hooks?: z.infer<typeof HooksSchema>;
 }
 
-/**
- * Load and merge all settings files, validate with Zod, return resolved config.
- *
- * @param cwd - The working directory (project root) to search for .robota/
- */
-declare function loadConfig(cwd: string): Promise<IResolvedConfig>;
-
 interface ILoadedContext {
     /** Concatenated content of all AGENTS.md files found (root-first) */
     agentsMd: string;
@@ -270,6 +241,111 @@ interface ISystemPromptParams {
  */
 declare function buildSystemPrompt(params: ISystemPromptParams): string;
 
+/**
+ * Session factory — assembles a fully-configured Session from config, context,
+ * tools, and provider.
+ *
+ * This is the main entry point for creating sessions. It wires together
+ * the provider, tools, system prompt, and configuration that Session now
+ * expects as pre-constructed dependencies.
+ */
+
+/** Options for the createSession factory */
+interface ICreateSessionOptions {
+    /** Resolved CLI configuration (model, API key, permissions) */
+    config: IResolvedConfig;
+    /** Loaded AGENTS.md / CLAUDE.md context */
+    context: ILoadedContext;
+    /** Terminal I/O for permission prompts */
+    terminal: ITerminalOutput;
+    /** Project metadata for system prompt */
+    projectInfo?: IProjectInfo;
+    /** Initial permission mode (defaults to config.defaultTrustLevel → mode mapping) */
+    permissionMode?: TPermissionMode;
+    /** Maximum number of agentic turns per run() call. Undefined = unlimited. */
+    maxTurns?: number;
+    /** Optional session store for persistence */
+    sessionStore?: SessionStore;
+    /** Inject a pre-constructed AI provider (used by tests to avoid real API calls) */
+    provider?: IAIProvider;
+    /** Custom permission handler (overrides terminal-based prompts, used by Ink UI) */
+    permissionHandler?: TPermissionHandler;
+    /** Callback for text deltas — enables streaming text to the UI in real-time */
+    onTextDelta?: (delta: string) => void;
+    /** Custom prompt-for-approval function (injected from CLI) */
+    promptForApproval?: (terminal: ITerminalOutput, toolName: string, toolArgs: TToolArgs) => Promise<boolean>;
+    /** Additional tools to register beyond the defaults (e.g. agent-tool) */
+    additionalTools?: IToolWithEventService[];
+    /** Callback when context is compacted */
+    onCompact?: (summary: string) => void;
+    /** Instructions to include in the compaction prompt (e.g. from CLAUDE.md) */
+    compactInstructions?: string;
+    /** Custom system prompt builder function */
+    systemPromptBuilder?: (params: ISystemPromptParams) => string;
+    /** Custom tool descriptions for the system prompt */
+    toolDescriptions?: string[];
+    /** Session logger — injected for pluggable session event logging. */
+    sessionLogger?: ISessionLogger;
+}
+/**
+ * Create a fully-configured Session instance.
+ *
+ * Assembles provider, tools, and system prompt, then passes them
+ * to Session as pre-constructed dependencies.
+ */
+declare function createSession(options: ICreateSessionOptions): Session;
+
+/**
+ * Default tool set factory — creates the standard set of CLI tools.
+ */
+
+/** Human-readable descriptions of the built-in tools (for system prompt) */
+declare const DEFAULT_TOOL_DESCRIPTIONS: string[];
+/**
+ * Create the default set of CLI tools.
+ * Returns the 8 standard tools as IToolWithEventService[].
+ */
+declare function createDefaultTools(): IToolWithEventService[];
+
+/**
+ * Provider factory — creates an AI provider from resolved config.
+ */
+
+/**
+ * Create an AI provider from the resolved config.
+ * Currently supports Anthropic only. Throws if no API key is available.
+ */
+declare function createProvider(config: IResolvedConfig): IAIProvider;
+
+/**
+ * query() — single entry point for running an AI agent conversation.
+ * Automatically loads config, context, and project info.
+ */
+
+interface IQueryOptions {
+    cwd?: string;
+    permissionMode?: TPermissionMode;
+    maxTurns?: number;
+    provider?: IAIProvider;
+    permissionHandler?: (toolName: string, toolArgs: TToolArgs) => Promise<boolean>;
+    onTextDelta?: (delta: string) => void;
+    /** Callback when context is compacted */
+    onCompact?: (summary: string) => void;
+}
+/**
+ * query() — single entry point for running an AI agent conversation.
+ * Equivalent to Claude Agent SDK's query() function.
+ * Automatically loads config, context, and project info.
+ */
+declare function query(prompt: string, options?: IQueryOptions): Promise<string>;
+
+/**
+ * Load and merge all settings files, validate with Zod, return resolved config.
+ *
+ * @param cwd - The working directory (project root) to search for .robota/
+ */
+declare function loadConfig(cwd: string): Promise<IResolvedConfig>;
+
 /**
  * Permission prompt — this is now CLI-specific.
  * Re-exported here for backward compatibility.
@@ -302,12 +378,12 @@ declare function userPaths(): {
 
 /** Dependencies injected at registration time */
 interface IAgentToolDeps {
-    config: IResolvedConfig$1;
-    context: ILoadedContext$1;
-    projectInfo?: IProjectInfo$1;
+    config: IResolvedConfig;
+    context: ILoadedContext;
+    projectInfo?: IProjectInfo;
 }
 /** Set dependencies for the agent tool. Must be called before tool is used. */
 declare function setAgentToolDeps(deps: IAgentToolDeps): void;
 declare const agentTool: _robota_sdk_agent_tools.FunctionTool;
 
-export { type ILoadedContext, type IProjectInfo, type IQueryOptions, type IResolvedConfig, type ISystemPromptParams, agentTool, buildSystemPrompt, detectProject, loadConfig, loadContext, projectPaths, promptForApproval, query, setAgentToolDeps, userPaths };
+export { DEFAULT_TOOL_DESCRIPTIONS, type ICreateSessionOptions, type ILoadedContext, type IProjectInfo, type IQueryOptions, type IResolvedConfig, type ISystemPromptParams, agentTool, buildSystemPrompt, createDefaultTools, createProvider, createSession, detectProject, loadConfig, loadContext, projectPaths, promptForApproval, query, setAgentToolDeps, userPaths };

package/dist/node/index.d.ts

@@ -1,33 +1,11 @@
-import { TPermissionMode, IAIProvider, TToolArgs, TTrustLevel } from '@robota-sdk/agent-core';
+import { TTrustLevel, TPermissionMode, IAIProvider, TToolArgs, IToolWithEventService } from '@robota-sdk/agent-core';
 export { IContextTokenUsage, IContextWindowState, IHookInput, IPermissionLists, THookEvent, THooksConfig, TPermissionDecision, TPermissionMode, TRUST_TO_MODE, TToolArgs, TTrustLevel, evaluatePermission, runHooks } from '@robota-sdk/agent-core';
 import * as _robota_sdk_agent_tools from '@robota-sdk/agent-tools';
 export { TToolResult, bashTool, editTool, globTool, grepTool, readTool, writeTool } from '@robota-sdk/agent-tools';
-import { ITerminalOutput, IResolvedConfig as IResolvedConfig$1, ILoadedContext as ILoadedContext$1, IProjectInfo as IProjectInfo$1 } from '@robota-sdk/agent-sessions';
+import { ITerminalOutput, SessionStore, TPermissionHandler, ISessionLogger, Session } from '@robota-sdk/agent-sessions';
 export { FileSessionLogger, ISessionLogger, ISessionOptions, ISessionRecord, ISpinner, ITerminalOutput, Session, SessionStore, SilentSessionLogger, TPermissionHandler, TPermissionResult, TSessionLogData } from '@robota-sdk/agent-sessions';
 import { z } from 'zod';
 
-/**
- * query() — single entry point for running an AI agent conversation.
- * Automatically loads config, context, and project info.
- */
-
-interface IQueryOptions {
-    cwd?: string;
-    permissionMode?: TPermissionMode;
-    maxTurns?: number;
-    provider?: IAIProvider;
-    permissionHandler?: (toolName: string, toolArgs: TToolArgs) => Promise<boolean>;
-    onTextDelta?: (delta: string) => void;
-    /** Callback when context is compacted */
-    onCompact?: (summary: string) => void;
-}
-/**
- * query() — single entry point for running an AI agent conversation.
- * Equivalent to Claude Agent SDK's query() function.
- * Automatically loads config, context, and project info.
- */
-declare function query(prompt: string, options?: IQueryOptions): Promise<string>;
-
 /**
  * Zod schemas and TypeScript types for Robota CLI settings
  */
@@ -210,13 +188,6 @@ interface IResolvedConfig {
     hooks?: z.infer<typeof HooksSchema>;
 }
 
-/**
- * Load and merge all settings files, validate with Zod, return resolved config.
- *
- * @param cwd - The working directory (project root) to search for .robota/
- */
-declare function loadConfig(cwd: string): Promise<IResolvedConfig>;
-
 interface ILoadedContext {
     /** Concatenated content of all AGENTS.md files found (root-first) */
     agentsMd: string;
@@ -270,6 +241,111 @@ interface ISystemPromptParams {
  */
 declare function buildSystemPrompt(params: ISystemPromptParams): string;
 
+/**
+ * Session factory — assembles a fully-configured Session from config, context,
+ * tools, and provider.
+ *
+ * This is the main entry point for creating sessions. It wires together
+ * the provider, tools, system prompt, and configuration that Session now
+ * expects as pre-constructed dependencies.
+ */
+
+/** Options for the createSession factory */
+interface ICreateSessionOptions {
+    /** Resolved CLI configuration (model, API key, permissions) */
+    config: IResolvedConfig;
+    /** Loaded AGENTS.md / CLAUDE.md context */
+    context: ILoadedContext;
+    /** Terminal I/O for permission prompts */
+    terminal: ITerminalOutput;
+    /** Project metadata for system prompt */
+    projectInfo?: IProjectInfo;
+    /** Initial permission mode (defaults to config.defaultTrustLevel → mode mapping) */
+    permissionMode?: TPermissionMode;
+    /** Maximum number of agentic turns per run() call. Undefined = unlimited. */
+    maxTurns?: number;
+    /** Optional session store for persistence */
+    sessionStore?: SessionStore;
+    /** Inject a pre-constructed AI provider (used by tests to avoid real API calls) */
+    provider?: IAIProvider;
+    /** Custom permission handler (overrides terminal-based prompts, used by Ink UI) */
+    permissionHandler?: TPermissionHandler;
+    /** Callback for text deltas — enables streaming text to the UI in real-time */
+    onTextDelta?: (delta: string) => void;
+    /** Custom prompt-for-approval function (injected from CLI) */
+    promptForApproval?: (terminal: ITerminalOutput, toolName: string, toolArgs: TToolArgs) => Promise<boolean>;
+    /** Additional tools to register beyond the defaults (e.g. agent-tool) */
+    additionalTools?: IToolWithEventService[];
+    /** Callback when context is compacted */
+    onCompact?: (summary: string) => void;
+    /** Instructions to include in the compaction prompt (e.g. from CLAUDE.md) */
+    compactInstructions?: string;
+    /** Custom system prompt builder function */
+    systemPromptBuilder?: (params: ISystemPromptParams) => string;
+    /** Custom tool descriptions for the system prompt */
+    toolDescriptions?: string[];
+    /** Session logger — injected for pluggable session event logging. */
+    sessionLogger?: ISessionLogger;
+}
+/**
+ * Create a fully-configured Session instance.
+ *
+ * Assembles provider, tools, and system prompt, then passes them
+ * to Session as pre-constructed dependencies.
+ */
+declare function createSession(options: ICreateSessionOptions): Session;
+
+/**
+ * Default tool set factory — creates the standard set of CLI tools.
+ */
+
+/** Human-readable descriptions of the built-in tools (for system prompt) */
+declare const DEFAULT_TOOL_DESCRIPTIONS: string[];
+/**
+ * Create the default set of CLI tools.
+ * Returns the 8 standard tools as IToolWithEventService[].
+ */
+declare function createDefaultTools(): IToolWithEventService[];
+
+/**
+ * Provider factory — creates an AI provider from resolved config.
+ */
+
+/**
+ * Create an AI provider from the resolved config.
+ * Currently supports Anthropic only. Throws if no API key is available.
+ */
+declare function createProvider(config: IResolvedConfig): IAIProvider;
+
+/**
+ * query() — single entry point for running an AI agent conversation.
+ * Automatically loads config, context, and project info.
+ */
+
+interface IQueryOptions {
+    cwd?: string;
+    permissionMode?: TPermissionMode;
+    maxTurns?: number;
+    provider?: IAIProvider;
+    permissionHandler?: (toolName: string, toolArgs: TToolArgs) => Promise<boolean>;
+    onTextDelta?: (delta: string) => void;
+    /** Callback when context is compacted */
+    onCompact?: (summary: string) => void;
+}
+/**
+ * query() — single entry point for running an AI agent conversation.
+ * Equivalent to Claude Agent SDK's query() function.
+ * Automatically loads config, context, and project info.
+ */
+declare function query(prompt: string, options?: IQueryOptions): Promise<string>;
+
+/**
+ * Load and merge all settings files, validate with Zod, return resolved config.
+ *
+ * @param cwd - The working directory (project root) to search for .robota/
+ */
+declare function loadConfig(cwd: string): Promise<IResolvedConfig>;
+
 /**
  * Permission prompt — this is now CLI-specific.
  * Re-exported here for backward compatibility.
@@ -302,12 +378,12 @@ declare function userPaths(): {
 
 /** Dependencies injected at registration time */
 interface IAgentToolDeps {
-    config: IResolvedConfig$1;
-    context: ILoadedContext$1;
-    projectInfo?: IProjectInfo$1;
+    config: IResolvedConfig;
+    context: ILoadedContext;
+    projectInfo?: IProjectInfo;
 }
 /** Set dependencies for the agent tool. Must be called before tool is used. */
 declare function setAgentToolDeps(deps: IAgentToolDeps): void;
 declare const agentTool: _robota_sdk_agent_tools.FunctionTool;
 
-export { type ILoadedContext, type IProjectInfo, type IQueryOptions, type IResolvedConfig, type ISystemPromptParams, agentTool, buildSystemPrompt, detectProject, loadConfig, loadContext, projectPaths, promptForApproval, query, setAgentToolDeps, userPaths };
+export { DEFAULT_TOOL_DESCRIPTIONS, type ICreateSessionOptions, type ILoadedContext, type IProjectInfo, type IQueryOptions, type IResolvedConfig, type ISystemPromptParams, agentTool, buildSystemPrompt, createDefaultTools, createProvider, createSession, detectProject, loadConfig, loadContext, projectPaths, promptForApproval, query, setAgentToolDeps, userPaths };

package/dist/node/index.js

@@ -1,13 +1,159 @@
 // src/types.ts
 import { TRUST_TO_MODE } from "@robota-sdk/agent-core";
 
-// src/session.ts
+// src/assembly/create-session.ts
 import { Session } from "@robota-sdk/agent-sessions";
 
+// src/context/system-prompt-builder.ts
+var TRUST_LEVEL_DESCRIPTIONS = {
+  safe: "safe (read-only / plan mode \u2014 only read-access tools are available)",
+  moderate: "moderate (default mode \u2014 write and bash tools require approval)",
+  full: "full (acceptEdits mode \u2014 file writes are auto-approved; bash requires approval)"
+};
+function buildProjectSection(info) {
+  const lines = ["## Current Project"];
+  if (info.name !== void 0) {
+    lines.push(`- **Name:** ${info.name}`);
+  }
+  if (info.type !== "unknown") {
+    lines.push(`- **Type:** ${info.type}`);
+  }
+  if (info.language !== "unknown") {
+    lines.push(`- **Language:** ${info.language}`);
+  }
+  if (info.packageManager !== void 0) {
+    lines.push(`- **Package manager:** ${info.packageManager}`);
+  }
+  return lines.join("\n");
+}
+function buildToolsSection(descriptions) {
+  if (descriptions.length === 0) {
+    return "";
+  }
+  const lines = ["## Available Tools", ...descriptions.map((d) => `- ${d}`)];
+  return lines.join("\n");
+}
+function buildSystemPrompt(params) {
+  const { agentsMd, claudeMd, toolDescriptions, trustLevel, projectInfo } = params;
+  const sections = [];
+  sections.push(
+    [
+      "## Role",
+      "You are an AI coding assistant with access to tools that let you read and modify code.",
+      "You help developers understand, write, and improve their codebase.",
+      "Always be precise, follow existing code conventions, and prefer minimal changes."
+    ].join("\n")
+  );
+  sections.push(buildProjectSection(projectInfo));
+  sections.push(
+    [
+      "## Permission Mode",
+      `Your current trust level is **${TRUST_LEVEL_DESCRIPTIONS[trustLevel]}**.`
+    ].join("\n")
+  );
+  if (agentsMd.trim().length > 0) {
+    sections.push(["## Agent Instructions", agentsMd].join("\n"));
+  }
+  if (claudeMd.trim().length > 0) {
+    sections.push(["## Project Notes", claudeMd].join("\n"));
+  }
+  sections.push(
+    [
+      "## Web Search",
+      "You have access to web search. When the user asks to search, look up, or find current/latest information,",
+      "you MUST use the web_search tool. Do NOT answer from training data when the user explicitly asks to search.",
+      "Always prefer web search for: news, latest versions, current events, live documentation."
+    ].join("\n")
+  );
+  const toolsSection = buildToolsSection(toolDescriptions);
+  if (toolsSection.length > 0) {
+    sections.push(toolsSection);
+  }
+  return sections.join("\n\n");
+}
+
+// src/assembly/create-tools.ts
+import {
+  bashTool,
+  readTool,
+  writeTool,
+  editTool,
+  globTool,
+  grepTool,
+  webFetchTool,
+  webSearchTool
+} from "@robota-sdk/agent-tools";
+var DEFAULT_TOOL_DESCRIPTIONS = [
+  "Bash \u2014 execute shell commands",
+  "Read \u2014 read file contents with line numbers",
+  "Write \u2014 write content to a file",
+  "Edit \u2014 replace a string in a file",
+  "Glob \u2014 find files matching a pattern",
+  "Grep \u2014 search file contents with regex",
+  "WebSearch \u2014 search the internet (Anthropic built-in)"
+];
+function createDefaultTools() {
+  return [
+    bashTool,
+    readTool,
+    writeTool,
+    editTool,
+    globTool,
+    grepTool,
+    webFetchTool,
+    webSearchTool
+  ];
+}
+
+// src/assembly/create-provider.ts
+import { AnthropicProvider } from "@robota-sdk/agent-provider-anthropic";
+function createProvider(config) {
+  const apiKey = config.provider.apiKey ?? process.env["ANTHROPIC_API_KEY"];
+  if (!apiKey) {
+    throw new Error(
+      "ANTHROPIC_API_KEY is not set. Set the environment variable or configure provider.apiKey in ~/.robota/settings.json"
+    );
+  }
+  return new AnthropicProvider({ apiKey });
+}
+
+// src/assembly/create-session.ts
+function createSession(options) {
+  const provider = options.provider ?? createProvider(options.config);
+  const defaultTools = createDefaultTools();
+  const tools = [...defaultTools, ...options.additionalTools ?? []];
+  const buildPrompt = options.systemPromptBuilder ?? buildSystemPrompt;
+  const systemMessage = buildPrompt({
+    agentsMd: options.context.agentsMd,
+    claudeMd: options.context.claudeMd,
+    toolDescriptions: options.toolDescriptions ?? DEFAULT_TOOL_DESCRIPTIONS,
+    trustLevel: options.config.defaultTrustLevel,
+    projectInfo: options.projectInfo ?? { type: "unknown", language: "unknown" }
+  });
+  return new Session({
+    tools,
+    provider,
+    systemMessage,
+    terminal: options.terminal,
+    permissions: options.config.permissions,
+    hooks: options.config.hooks,
+    permissionMode: options.permissionMode,
+    defaultTrustLevel: options.config.defaultTrustLevel,
+    model: options.config.provider.model,
+    maxTurns: options.maxTurns,
+    sessionStore: options.sessionStore,
+    permissionHandler: options.permissionHandler,
+    onTextDelta: options.onTextDelta,
+    promptForApproval: options.promptForApproval,
+    onCompact: options.onCompact,
+    compactInstructions: options.compactInstructions ?? options.context.compactInstructions,
+    sessionLogger: options.sessionLogger
+  });
+}
+
 // src/index.ts
+import { Session as Session2 } from "@robota-sdk/agent-sessions";
 import { FileSessionLogger, SilentSessionLogger } from "@robota-sdk/agent-sessions";
-
-// src/session-store.ts
 import { SessionStore } from "@robota-sdk/agent-sessions";
 
 // src/config/config-loader.ts
@@ -273,77 +419,6 @@ async function detectProject(cwd) {
   };
 }
 
-// src/context/system-prompt-builder.ts
-var TRUST_LEVEL_DESCRIPTIONS = {
-  safe: "safe (read-only / plan mode \u2014 only read-access tools are available)",
-  moderate: "moderate (default mode \u2014 write and bash tools require approval)",
-  full: "full (acceptEdits mode \u2014 file writes are auto-approved; bash requires approval)"
-};
-function buildProjectSection(info) {
-  const lines = ["## Current Project"];
-  if (info.name !== void 0) {
-    lines.push(`- **Name:** ${info.name}`);
-  }
-  if (info.type !== "unknown") {
-    lines.push(`- **Type:** ${info.type}`);
-  }
-  if (info.language !== "unknown") {
-    lines.push(`- **Language:** ${info.language}`);
-  }
-  if (info.packageManager !== void 0) {
-    lines.push(`- **Package manager:** ${info.packageManager}`);
-  }
-  return lines.join("\n");
-}
-function buildToolsSection(descriptions) {
-  if (descriptions.length === 0) {
-    return "";
-  }
-  const lines = ["## Available Tools", ...descriptions.map((d) => `- ${d}`)];
-  return lines.join("\n");
-}
-function buildSystemPrompt(params) {
-  const { agentsMd, claudeMd, toolDescriptions, trustLevel, projectInfo } = params;
-  const sections = [];
-  sections.push(
-    [
-      "## Role",
-      "You are an AI coding assistant with access to tools that let you read and modify code.",
-      "You help developers understand, write, and improve their codebase.",
-      "Always be precise, follow existing code conventions, and prefer minimal changes."
-    ].join("\n")
-  );
-  sections.push(buildProjectSection(projectInfo));
-  sections.push(
-    [
-      "## Permission Mode",
-      `Your current trust level is **${TRUST_LEVEL_DESCRIPTIONS[trustLevel]}**.`
-    ].join("\n")
-  );
-  if (agentsMd.trim().length > 0) {
-    sections.push(["## Agent Instructions", agentsMd].join("\n"));
-  }
-  if (claudeMd.trim().length > 0) {
-    sections.push(["## Project Notes", claudeMd].join("\n"));
-  }
-  sections.push(
-    [
-      "## Web Search",
-      "You have access to web search. When the user asks to search, look up, or find current/latest information,",
-      "you MUST use the web_search tool. Do NOT answer from training data when the user explicitly asks to search.",
-      "Always prefer web search for: news, latest versions, current events, live documentation."
-    ].join("\n")
-  );
-  const toolsSection = buildToolsSection(toolDescriptions);
-  if (toolsSection.length > 0) {
-    sections.push(toolsSection);
-  }
-  return sections.join("\n\n");
-}
-
-// src/query.ts
-import { Session as Session2 } from "@robota-sdk/agent-sessions";
-
 // src/permissions/permission-prompt.ts
 import chalk from "chalk";
 var PERMISSION_OPTIONS = ["Allow", "Deny"];
@@ -387,7 +462,7 @@ async function query(prompt, options) {
     }, update: () => {
     } })
   };
-  const session = new Session2({
+  const session = createSession({
     config,
     context,
     terminal: noopTerminal,
@@ -399,16 +474,13 @@ async function query(prompt, options) {
     onTextDelta: options?.onTextDelta,
     onCompact: options?.onCompact,
     compactInstructions: context.compactInstructions,
-    systemPromptBuilder: buildSystemPrompt,
     promptForApproval
   });
   return session.run(prompt);
 }
 
-// src/permissions/permission-gate.ts
+// src/index.ts
 import { evaluatePermission } from "@robota-sdk/agent-core";
-
-// src/hooks/hook-runner.ts
 import { runHooks } from "@robota-sdk/agent-core";
 
 // src/paths.ts
@@ -431,28 +503,9 @@ function userPaths() {
   };
 }
 
-// src/tools/bash-tool.ts
-import { bashTool } from "@robota-sdk/agent-tools";
-
-// src/tools/read-tool.ts
-import { readTool } from "@robota-sdk/agent-tools";
-
-// src/tools/write-tool.ts
-import { writeTool } from "@robota-sdk/agent-tools";
-
-// src/tools/edit-tool.ts
-import { editTool } from "@robota-sdk/agent-tools";
-
-// src/tools/glob-tool.ts
-import { globTool } from "@robota-sdk/agent-tools";
-
-// src/tools/grep-tool.ts
-import { grepTool } from "@robota-sdk/agent-tools";
-
 // src/tools/agent-tool.ts
 import { z as z2 } from "zod";
 import { createZodFunctionTool } from "@robota-sdk/agent-tools";
-import { Session as Session3 } from "@robota-sdk/agent-sessions";
 function asZodSchema(schema) {
   return schema;
 }
@@ -473,26 +526,26 @@ async function runAgent(args) {
     };
     return JSON.stringify(result);
   }
-  const subSession = new Session3({
+  const noopTerminal = {
+    write: () => {
+    },
+    writeLine: () => {
+    },
+    writeMarkdown: () => {
+    },
+    writeError: () => {
+    },
+    prompt: () => Promise.resolve(""),
+    select: () => Promise.resolve(0),
+    spinner: () => ({ stop: () => {
+    }, update: () => {
+    } })
+  };
+  const subSession = createSession({
     config: agentToolDeps.config,
     context: agentToolDeps.context,
     projectInfo: agentToolDeps.projectInfo,
-    // No terminal needed — sub-agents don't prompt for permissions
-    terminal: {
-      write: () => {
-      },
-      writeLine: () => {
-      },
-      writeMarkdown: () => {
-      },
-      writeError: () => {
-      },
-      prompt: () => Promise.resolve(""),
-      select: () => Promise.resolve(0),
-      spinner: () => ({ stop: () => {
-      }, update: () => {
-      } })
-    },
+    terminal: noopTerminal,
     // Sub-agents bypass permissions — they inherit parent's trust
     permissionMode: "bypassPermissions"
   });
@@ -521,28 +574,40 @@ var agentTool = createZodFunctionTool(
     return runAgent(params);
   }
 );
+
+// src/index.ts
+import { bashTool as bashTool2 } from "@robota-sdk/agent-tools";
+import { readTool as readTool2 } from "@robota-sdk/agent-tools";
+import { writeTool as writeTool2 } from "@robota-sdk/agent-tools";
+import { editTool as editTool2 } from "@robota-sdk/agent-tools";
+import { globTool as globTool2 } from "@robota-sdk/agent-tools";
+import { grepTool as grepTool2 } from "@robota-sdk/agent-tools";
 export {
+  DEFAULT_TOOL_DESCRIPTIONS,
   FileSessionLogger,
-  Session,
+  Session2 as Session,
   SessionStore,
   SilentSessionLogger,
   TRUST_TO_MODE,
   agentTool,
-  bashTool,
+  bashTool2 as bashTool,
   buildSystemPrompt,
+  createDefaultTools,
+  createProvider,
+  createSession,
   detectProject,
-  editTool,
+  editTool2 as editTool,
   evaluatePermission,
-  globTool,
-  grepTool,
+  globTool2 as globTool,
+  grepTool2 as grepTool,
   loadConfig,
   loadContext,
   projectPaths,
   promptForApproval,
   query,
-  readTool,
+  readTool2 as readTool,
   runHooks,
   setAgentToolDeps,
   userPaths,
-  writeTool
+  writeTool2 as writeTool
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robota-sdk/agent-sdk",
-  "version": "3.0.0-beta.3",
+  "version": "3.0.0-beta.4",
   "description": "Programmatic SDK for building AI agents with Robota — provides Session, query(), built-in tools, permissions, hooks, and context loading",
   "type": "module",
   "main": "dist/node/index.js",
@@ -24,10 +24,10 @@
   "dependencies": {
     "chalk": "^5.3.0",
     "zod": "^3.24.0",
-    "@robota-sdk/agent-core": "3.0.0-beta.3",
-    "@robota-sdk/agent-provider-anthropic": "3.0.0-beta.3",
-    "@robota-sdk/agent-sessions": "3.0.0-beta.3",
-    "@robota-sdk/agent-tools": "3.0.0-beta.3"
+    "@robota-sdk/agent-core": "3.0.0-beta.4",
+    "@robota-sdk/agent-provider-anthropic": "3.0.0-beta.4",
+    "@robota-sdk/agent-sessions": "3.0.0-beta.4",
+    "@robota-sdk/agent-tools": "3.0.0-beta.4"
   },
   "devDependencies": {
     "rimraf": "^5.0.5",