@robota-sdk/agent-sdk 3.0.0-beta.35 → 3.0.0-beta.36

package/README.md

@@ -1,6 +1,6 @@
 # @robota-sdk/agent-sdk
 
-Programmatic SDK for building AI agents with Robota. Provides a single `query()` entry point along with session management, built-in tools, permissions, hooks, streaming, and context loading.
+Programmatic SDK for building AI agents with Robota. Provides `InteractiveSession` as the central client-facing API, `query()` for one-shot use, session management, built-in tools, permissions, hooks, streaming, and context loading.
 
 This is the **assembly layer** of the Robota ecosystem — it composes lower-level packages (`agent-core`, `agent-tools`, `agent-sessions`, `agent-provider-anthropic`) into a cohesive SDK.
 
@@ -33,7 +33,10 @@ const response = await query('Analyze the code', {
 
 ## Features
 
-- **query()** — Single entry point for AI agent interactions with streaming support
+- **InteractiveSession** — Event-driven session wrapper (composition over Session). Central client-facing API for CLI, web, API server, or any other client
+- **SystemCommandExecutor + ISystemCommand** — SDK-level command execution. Built-in commands: `help`, `clear`, `compact`, `mode`, `model`, `language`, `cost`, `context`, `permissions`, `reset`
+- **CommandRegistry, BuiltinCommandSource, SkillCommandSource** — Slash command registry and discovery (owned by SDK; agent-cli re-exports `CommandRegistry` from here)
+- **query()** — Single entry point for one-shot AI agent interactions with streaming support
 - **createSession()** — Assembly factory: wires tools, provider, config, and context into a Session
 - **Built-in Tools** — Bash, Read, Write, Edit, Glob, Grep (re-exported from `@robota-sdk/agent-tools`)
 - **Agent Tool** — Sub-agent session creation for multi-agent workflows
@@ -49,16 +52,167 @@ const response = await query('Analyze the code', {
 
 ```
 agent-sdk (assembly layer)
-  -> agent-sessions  (Session, SessionStore)
-  -> agent-tools     (tool infrastructure + 8 built-in tools)
-  -> agent-provider-anthropic (Anthropic LLM provider)
-  -> agent-core      (Robota engine, providers, permissions, hooks)
+  ├── InteractiveSession  ← central client-facing API (event-driven)
+  │     └── Session       ← generic session (agent-sessions)
+  ├── SystemCommandExecutor ← SDK-level command execution
+  ├── CommandRegistry / BuiltinCommandSource / SkillCommandSource
+  ├── query()             ← one-shot entry point
+  ├── createSession()     ← assembly factory
+  └── deps:
+        agent-sessions  (Session, SessionStore)
+        agent-tools     (tool infrastructure + 8 built-in tools)
+        agent-provider-anthropic (Anthropic LLM provider)
+        agent-core      (Robota engine, providers, permissions, hooks)
+
+agent-cli (TUI layer — bridges InteractiveSession events to React/Ink state)
+  → agent-sdk
 ```
 
-`agent-sdk` assembles existing packages — it does not re-implement functionality that belongs in lower layers.
+The SDK is **pure TypeScript with no React dependency**. The CLI is a thin TUI-only layer that consumes `InteractiveSession` events and maps them to React state. Any other client (web app, API server, worker) can do the same.
 
 ## API
 
+### InteractiveSession — Central Client-Facing API
+
+`InteractiveSession` wraps `Session` (composition over inheritance) to provide event-driven interaction for any client. It manages streaming text accumulation, tool execution state tracking, prompt queuing, abort orchestration, and message history. Logic that was previously embedded in CLI React hooks now lives here.
+
+```typescript
+import { InteractiveSession } from '@robota-sdk/agent-sdk';
+import type { IInteractiveSessionOptions } from '@robota-sdk/agent-sdk';
+
+const session = new InteractiveSession({
+  config,
+  context,
+  projectInfo,
+  sessionStore,
+  permissionMode: 'default',
+  maxTurns: 10,
+  cwd: process.cwd(),
+  permissionHandler: async (toolName, toolArgs) => ({ allowed: true }),
+});
+
+// Subscribe to events
+session.on('text_delta', (delta: string) => {
+  process.stdout.write(delta); // streaming text chunk
+});
+session.on('tool_start', (state) => {
+  console.log(`Running: ${state.toolName}`);
+});
+session.on('tool_end', (state) => {
+  console.log(`Done: ${state.toolName} — ${state.result}`);
+});
+session.on('thinking', (isThinking: boolean) => {
+  // show/hide spinner
+});
+session.on('complete', (result) => {
+  console.log(result.response);
+});
+session.on('error', (error: Error) => {
+  console.error(error);
+});
+session.on('context_update', (state) => {
+  // token usage updated
+});
+session.on('interrupted', (result) => {
+  // abort completed
+});
+
+// Submit a prompt (queues if already executing, max 1 queued)
+await session.submit('Explain this code');
+
+// Submit with display override (shown in UI) and raw input (for hook matching)
+await session.submit(fullPrompt, '/audit', '/rulebased-harness:audit');
+
+// Abort current execution and clear queue
+session.abort();
+
+// Cancel queued prompt without aborting current execution
+session.cancelQueue();
+
+// State queries
+session.isExecuting(); // boolean
+session.getPendingPrompt(); // string | null
+session.getMessages(); // TUniversalMessage[]
+session.getContextState(); // IContextWindowState
+session.getStreamingText(); // string (accumulated so far)
+session.getActiveTools(); // IToolState[]
+
+// Access underlying Session for advanced use
+session.getSession(); // Session
+```
+
+### SystemCommandExecutor — SDK-Level Commands
+
+`SystemCommandExecutor` executes named system commands against an `InteractiveSession`. Commands are pure TypeScript — no React, no TUI dependency. The CLI wraps them as slash commands with UI chrome.
+
+```typescript
+import { SystemCommandExecutor, createSystemCommands } from '@robota-sdk/agent-sdk';
+import type { ICommandResult } from '@robota-sdk/agent-sdk';
+
+const executor = new SystemCommandExecutor(); // loads built-in commands by default
+
+// Execute a command
+const result: ICommandResult | null = await executor.execute('context', session, '');
+if (result) {
+  console.log(result.message); // "Context: 12,345 / 200,000 tokens (6%)"
+  console.log(result.data); // { usedTokens, maxTokens, percentage }
+}
+
+// Register a custom command
+executor.register({
+  name: 'status',
+  description: 'Show agent status',
+  execute: (session, args) => ({ message: 'OK', success: true }),
+});
+
+// List all commands
+executor.listCommands(); // ISystemCommand[]
+executor.hasCommand('mode'); // boolean
+```
+
+Built-in commands:
+
+| Command       | Description                                             |
+| ------------- | ------------------------------------------------------- |
+| `help`        | Show available commands                                 |
+| `clear`       | Clear conversation history                              |
+| `compact`     | Compress context window (optional focus instructions)   |
+| `mode [m]`    | Show or change permission mode                          |
+| `model <id>`  | Change AI model                                         |
+| `language`    | Set response language (ko, en, ja, zh)                  |
+| `cost`        | Show session info (session ID, message count)           |
+| `context`     | Context window token usage                              |
+| `permissions` | Show current permission mode and session-approved tools |
+| `reset`       | Delete settings (caller handles file I/O and exit)      |
+
+### CommandRegistry, BuiltinCommandSource, SkillCommandSource
+
+These classes provide slash command discovery and aggregation for clients that expose a command palette or autocomplete UI.
+
+```typescript
+import { CommandRegistry, BuiltinCommandSource, SkillCommandSource } from '@robota-sdk/agent-sdk';
+
+const registry = new CommandRegistry();
+registry.addSource(new BuiltinCommandSource());
+registry.addSource(new SkillCommandSource(process.cwd()));
+
+// Get all commands (returns ISlashCommand[])
+const commands = registry.getCommands();
+
+// Filter by prefix (for autocomplete)
+const filtered = registry.getCommands('mod'); // matches "mode", "model"
+
+// Resolve short plugin name to fully qualified form
+registry.resolveQualifiedName('audit'); // "my-plugin:audit"
+```
+
+`SkillCommandSource` discovers skills from (highest priority first):
+
+- `<cwd>/.claude/skills/*/SKILL.md`
+- `<cwd>/.claude/commands/*.md` (Claude Code compatible)
+- `~/.robota/skills/*/SKILL.md`
+- `<cwd>/.agents/skills/*/SKILL.md`
+
 ### query()
 
 ```typescript

package/dist/node/index.cjs

@@ -2398,7 +2398,6 @@ var SystemCommandExecutor = class {
 // src/interactive/interactive-session.ts
 var import_agent_sessions4 = require("@robota-sdk/agent-sessions");
 var import_agent_core3 = require("@robota-sdk/agent-core");
-var import_node_crypto = require("crypto");
 var TOOL_ARG_DISPLAY_MAX = 80;
 var TAIL_KEEP = 30;
 var MAX_COMPLETED_TOOLS = 50;
@@ -2414,6 +2413,8 @@ var InteractiveSession = class {
   // Execution state
   executing = false;
   pendingPrompt = null;
+  pendingDisplayInput;
+  pendingRawInput;
   // Display messages (what clients render — not the raw session history)
   messages = [];
   constructor(options) {
@@ -2456,13 +2457,17 @@ var InteractiveSession = class {
     }
   }
   // ── Public API ────────────────────────────────────────────────
-  /** Submit a prompt. Queues if already executing (max 1 queued). */
-  async submit(input) {
+  /** Submit a prompt. Queues if already executing (max 1 queued).
+   *  displayInput overrides what appears as the user message (e.g., "/audit" instead of full skill prompt).
+   *  rawInput is passed to Session.run() for hook matching (e.g., "/rulebased-harness:audit"). */
+  async submit(input, displayInput, rawInput) {
     if (this.executing) {
       this.pendingPrompt = input;
+      this.pendingDisplayInput = displayInput;
+      this.pendingRawInput = rawInput;
       return;
     }
-    await this.executePrompt(input);
+    await this.executePrompt(input, displayInput, rawInput);
   }
   /** Abort current execution and clear queue. */
   abort() {
@@ -2495,14 +2500,14 @@ var InteractiveSession = class {
     return this.session;
   }
   // ── Execution ─────────────────────────────────────────────────
-  async executePrompt(input) {
+  async executePrompt(input, displayInput, rawInput) {
     this.executing = true;
     this.clearStreaming();
     this.emit("thinking", true);
-    this.messages.push((0, import_agent_core3.createUserMessage)(input));
+    this.messages.push((0, import_agent_core3.createUserMessage)(displayInput ?? input));
     const historyBefore = this.session.getHistory().length;
     try {
-      const response = await this.session.run(input);
+      const response = await this.session.run(input, rawInput);
       this.flushStreaming();
       this.clearStreaming();
       const result = this.buildResult(response || "(empty response)", historyBefore);
@@ -2529,8 +2534,12 @@ var InteractiveSession = class {
       this.emit("thinking", false);
       if (this.pendingPrompt) {
         const queued = this.pendingPrompt;
+        const queuedDisplay = this.pendingDisplayInput;
+        const queuedRaw = this.pendingRawInput;
         this.pendingPrompt = null;
-        setTimeout(() => this.executePrompt(queued), 0);
+        this.pendingDisplayInput = void 0;
+        this.pendingRawInput = void 0;
+        setTimeout(() => this.executePrompt(queued, queuedDisplay, queuedRaw), 0);
       }
     }
   }
@@ -2586,14 +2595,6 @@ var InteractiveSession = class {
   }
   buildResult(response, historyBefore) {
     const toolSummaries = this.extractToolSummaries(historyBefore);
-    if (toolSummaries.length > 0) {
-      this.messages.push(
-        (0, import_agent_core3.createToolMessage)(JSON.stringify(toolSummaries), {
-          toolCallId: (0, import_node_crypto.randomUUID)(),
-          name: `${toolSummaries.length} tools`
-        })
-      );
-    }
     return {
       response,
       messages: this.messages,
@@ -2604,14 +2605,6 @@ var InteractiveSession = class {
   buildInterruptedResult(historyBefore) {
     const history = this.session.getHistory();
     const toolSummaries = this.extractToolSummaries(historyBefore);
-    if (toolSummaries.length > 0) {
-      this.messages.push(
-        (0, import_agent_core3.createToolMessage)(JSON.stringify(toolSummaries), {
-          toolCallId: (0, import_node_crypto.randomUUID)(),
-          name: `${toolSummaries.length} tools`
-        })
-      );
-    }
     const parts = [];
     for (let i = historyBefore; i < history.length; i++) {
       const msg = history[i];

package/dist/node/index.d.cts

@@ -1033,13 +1033,17 @@ declare class InteractiveSession {
     private activeTools;
     private executing;
     private pendingPrompt;
+    private pendingDisplayInput;
+    private pendingRawInput;
     private messages;
     constructor(options: IInteractiveSessionOptions);
     on<E extends TInteractiveEventName>(event: E, handler: IInteractiveSessionEvents[E]): void;
     off<E extends TInteractiveEventName>(event: E, handler: IInteractiveSessionEvents[E]): void;
     private emit;
-    /** Submit a prompt. Queues if already executing (max 1 queued). */
-    submit(input: string): Promise<void>;
+    /** Submit a prompt. Queues if already executing (max 1 queued).
+     *  displayInput overrides what appears as the user message (e.g., "/audit" instead of full skill prompt).
+     *  rawInput is passed to Session.run() for hook matching (e.g., "/rulebased-harness:audit"). */
+    submit(input: string, displayInput?: string, rawInput?: string): Promise<void>;
     /** Abort current execution and clear queue. */
     abort(): void;
     /** Cancel queued prompt without aborting current execution. */

package/dist/node/index.d.ts

@@ -1033,13 +1033,17 @@ declare class InteractiveSession {
     private activeTools;
     private executing;
     private pendingPrompt;
+    private pendingDisplayInput;
+    private pendingRawInput;
     private messages;
     constructor(options: IInteractiveSessionOptions);
     on<E extends TInteractiveEventName>(event: E, handler: IInteractiveSessionEvents[E]): void;
     off<E extends TInteractiveEventName>(event: E, handler: IInteractiveSessionEvents[E]): void;
     private emit;
-    /** Submit a prompt. Queues if already executing (max 1 queued). */
-    submit(input: string): Promise<void>;
+    /** Submit a prompt. Queues if already executing (max 1 queued).
+     *  displayInput overrides what appears as the user message (e.g., "/audit" instead of full skill prompt).
+     *  rawInput is passed to Session.run() for hook matching (e.g., "/rulebased-harness:audit"). */
+    submit(input: string, displayInput?: string, rawInput?: string): Promise<void>;
     /** Abort current execution and clear queue. */
     abort(): void;
     /** Cancel queued prompt without aborting current execution. */

package/dist/node/index.js

@@ -2333,10 +2333,8 @@ import { FileSessionLogger as FileSessionLogger2 } from "@robota-sdk/agent-sessi
 import {
   createUserMessage,
   createAssistantMessage,
-  createSystemMessage,
-  createToolMessage
+  createSystemMessage
 } from "@robota-sdk/agent-core";
-import { randomUUID } from "crypto";
 var TOOL_ARG_DISPLAY_MAX = 80;
 var TAIL_KEEP = 30;
 var MAX_COMPLETED_TOOLS = 50;
@@ -2352,6 +2350,8 @@ var InteractiveSession = class {
   // Execution state
   executing = false;
   pendingPrompt = null;
+  pendingDisplayInput;
+  pendingRawInput;
   // Display messages (what clients render — not the raw session history)
   messages = [];
   constructor(options) {
@@ -2394,13 +2394,17 @@ var InteractiveSession = class {
     }
   }
   // ── Public API ────────────────────────────────────────────────
-  /** Submit a prompt. Queues if already executing (max 1 queued). */
-  async submit(input) {
+  /** Submit a prompt. Queues if already executing (max 1 queued).
+   *  displayInput overrides what appears as the user message (e.g., "/audit" instead of full skill prompt).
+   *  rawInput is passed to Session.run() for hook matching (e.g., "/rulebased-harness:audit"). */
+  async submit(input, displayInput, rawInput) {
     if (this.executing) {
       this.pendingPrompt = input;
+      this.pendingDisplayInput = displayInput;
+      this.pendingRawInput = rawInput;
       return;
     }
-    await this.executePrompt(input);
+    await this.executePrompt(input, displayInput, rawInput);
   }
   /** Abort current execution and clear queue. */
   abort() {
@@ -2433,14 +2437,14 @@ var InteractiveSession = class {
     return this.session;
   }
   // ── Execution ─────────────────────────────────────────────────
-  async executePrompt(input) {
+  async executePrompt(input, displayInput, rawInput) {
     this.executing = true;
     this.clearStreaming();
     this.emit("thinking", true);
-    this.messages.push(createUserMessage(input));
+    this.messages.push(createUserMessage(displayInput ?? input));
     const historyBefore = this.session.getHistory().length;
     try {
-      const response = await this.session.run(input);
+      const response = await this.session.run(input, rawInput);
       this.flushStreaming();
       this.clearStreaming();
       const result = this.buildResult(response || "(empty response)", historyBefore);
@@ -2467,8 +2471,12 @@ var InteractiveSession = class {
       this.emit("thinking", false);
       if (this.pendingPrompt) {
         const queued = this.pendingPrompt;
+        const queuedDisplay = this.pendingDisplayInput;
+        const queuedRaw = this.pendingRawInput;
         this.pendingPrompt = null;
-        setTimeout(() => this.executePrompt(queued), 0);
+        this.pendingDisplayInput = void 0;
+        this.pendingRawInput = void 0;
+        setTimeout(() => this.executePrompt(queued, queuedDisplay, queuedRaw), 0);
       }
     }
   }
@@ -2524,14 +2532,6 @@ var InteractiveSession = class {
   }
   buildResult(response, historyBefore) {
     const toolSummaries = this.extractToolSummaries(historyBefore);
-    if (toolSummaries.length > 0) {
-      this.messages.push(
-        createToolMessage(JSON.stringify(toolSummaries), {
-          toolCallId: randomUUID(),
-          name: `${toolSummaries.length} tools`
-        })
-      );
-    }
     return {
       response,
       messages: this.messages,
@@ -2542,14 +2542,6 @@ var InteractiveSession = class {
   buildInterruptedResult(historyBefore) {
     const history = this.session.getHistory();
     const toolSummaries = this.extractToolSummaries(historyBefore);
-    if (toolSummaries.length > 0) {
-      this.messages.push(
-        createToolMessage(JSON.stringify(toolSummaries), {
-          toolCallId: randomUUID(),
-          name: `${toolSummaries.length} tools`
-        })
-      );
-    }
     const parts = [];
     for (let i = historyBefore; i < history.length; i++) {
       const msg = history[i];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robota-sdk/agent-sdk",
-  "version": "3.0.0-beta.35",
+  "version": "3.0.0-beta.36",
   "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",