@robota-sdk/agent-framework 3.0.0-beta.75 → 3.0.0-beta.77

package/README.md

@@ -1,6 +1,6 @@
 # @robota-sdk/agent-framework
 
-Programmatic SDK for building AI agents with Robota. Provides `InteractiveSession` as the central client-facing API, `createQuery()` for one-shot use, session management, SDK-owned command/common APIs, permissions, hooks, streaming, context loading, bounded prompt file references, and context reference inventory.
+Programmatic SDK for building AI agents with Robota. Provides `InteractiveSession` as the central client-facing API, `createQuery()` for one-shot use, `createAgentRuntime()` as a composition factory for headless and multi-session consumers, session management, SDK-owned command/common APIs, permissions, hooks, streaming, context loading, bounded prompt file references, and context reference inventory.
 
 This is the **assembly layer** of the Robota ecosystem — it composes lower-level packages (`agent-core`, `agent-tools`, `agent-session`, `agent-provider`) into a cohesive SDK.
 
@@ -36,11 +36,30 @@ const queryWithOptions = createQuery({
 const detailedResponse = await queryWithOptions('Analyze the code');
 ```
 
+### Headless / multi-session runtime
+
+For headless or multi-session consumers, `createAgentRuntime()` builds a composition root that
+spawns `InteractiveSession`s sharing one configuration (provider, cwd, command modules, session
+store, transports):
+
+```typescript
+import { createAgentRuntime } from '@robota-sdk/agent-framework';
+import { AnthropicProvider } from '@robota-sdk/agent-provider/anthropic';
+
+const runtime = createAgentRuntime({
+  cwd: process.cwd(),
+  provider: new AnthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY }),
+});
+
+// Each call composes a fresh InteractiveSession that inherits the runtime config.
+const session = runtime.createSession({});
+```
+
 ## Features
 
 - **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 infrastructure for product-composed command modules
-- **CommandRegistry, BuiltinCommandSource, SkillCommandSource** — Command registry and SDK common discovery APIs. User-visible built-ins are composed through `agent-command-*` packages.
+- **CommandRegistry, BuiltinCommandSource, SkillCommandSource** — Command registry and SDK common discovery APIs. User-visible built-ins are composed through `agent-command` packages.
 - **Model Command Common APIs** — Provider-neutral `/model` helpers that resolve active provider catalogs and optionally invoke provider-owned refresh hooks
 - **createQuery()** — Provider-bound factory for one-shot AI agent interactions with streaming support
 - **Session assembly** — Internal factory wires tools, provider, config, and context for `InteractiveSession`
@@ -95,22 +114,20 @@ The SDK is **pure TypeScript with no React dependency**. The CLI is a thin TUI-o
 
 ```typescript
 import { InteractiveSession, createProjectSessionStore } from '@robota-sdk/agent-framework';
-import type { IInteractiveSessionOptions } from '@robota-sdk/agent-framework';
+import type { IAIProvider } from '@robota-sdk/agent-core';
 
+declare const provider: IAIProvider;
 const cwd = process.cwd();
 const sessionStore = createProjectSessionStore(cwd);
 
 const session = new InteractiveSession({
-  config,
-  context,
-  projectInfo,
+  cwd,
+  provider,
   sessionStore, // SDK-owned project-local persistence facade
-  resumeSessionId, // Session ID to restore, including sandbox snapshot when available
-  forkSession, // Session ID to fork from (optional)
+  resumeSessionId: 'sess_123', // Session ID to restore, incl. sandbox snapshot (optional)
+  forkSession: false, // Fork the resumed session into a new one (optional)
   permissionMode: 'default',
   maxTurns: 10,
-  cwd,
-  permissionHandler: async (toolName, toolArgs) => ({ allowed: true }),
 });
 
 // Subscribe to events
@@ -147,7 +164,7 @@ await session.submit('Explain this code');
 await session.submit('Explain @AGENTS.md and @docs/SPEC.md');
 
 // Submit with display override (shown in UI) and raw input (for hook matching)
-await session.submit(fullPrompt, '/audit', '/rulebased-harness:audit');
+await session.submit('full expanded prompt…', '/audit', '/rulebased-harness:audit');
 
 // Execute slash commands through the command layer. With the skills command module composed,
 // `/audit src/index.ts` is normalized by SDK to command "skills" with args "audit src/index.ts".
@@ -188,8 +205,10 @@ session.getSession(); // Session
 
 ```typescript
 import { SystemCommandExecutor, createSystemCommands } from '@robota-sdk/agent-framework';
-import type { ICommandResult } from '@robota-sdk/agent-framework';
+import type { ICommandHostContext } from '@robota-sdk/agent-framework';
+import type { ICommandResult } from '@robota-sdk/agent-interface-transport';
 
+declare const session: ICommandHostContext;
 const executor = new SystemCommandExecutor(); // starts empty unless commands are supplied
 
 // Execute a command
@@ -210,7 +229,7 @@ executor.listCommands(); // ISystemCommand[]
 executor.hasCommand('permissions'); // boolean
 ```
 
-SDK core does not own user-visible built-in commands. Product built-ins are supplied as `agent-command-*` modules. SDK command identity is slash-free (`skills`, `help`, `compact`); UI shells render and parse those commands as slash syntax such as `/skills`, `/help`, and `/compact`.
+SDK core does not own user-visible built-in commands. Product built-ins are supplied as `agent-command` modules. SDK command identity is slash-free (`skills`, `help`, `compact`); UI shells render and parse those commands as slash syntax such as `/skills`, `/help`, and `/compact`.
 
 Command modules may use SDK common APIs for shared provider-neutral behavior. For `/model`, the SDK
 resolves the active provider from settings, reads provider-owned fallback metadata from injected
@@ -235,7 +254,7 @@ These classes provide slash command discovery and aggregation for clients that e
 
 ```typescript
 import { CommandRegistry } from '@robota-sdk/agent-framework';
-import { createSkillsCommandModule } from '@robota-sdk/agent-command-skills';
+import { createSkillsCommandModule } from '@robota-sdk/agent-command';
 
 const registry = new CommandRegistry();
 registry.addModule(createSkillsCommandModule({ cwd: process.cwd() }));
@@ -258,7 +277,7 @@ registry.resolveQualifiedName('audit'); // "my-plugin:audit"
 - `<cwd>/.agents/skills/*/SKILL.md`
 
 Model-invocable skills are exposed to the model as metadata only when the session has a composed
-model-invocable `skills` command descriptor. `@robota-sdk/agent-command-skills` owns `skills` and
+model-invocable `skills` command descriptor. `@robota-sdk/agent-command` owns `skills` and
 activates skills through the SDK host API. Models use the SDK-projected `robota_command_skills`
 tool with skill arguments in `args`. Mentioning a skill in ordinary prose,
 recommending a skill in assistant text, or matching a natural-language phrase in SDK/TUI code does
@@ -314,6 +333,8 @@ import {
 
 SDK sessions can receive a provider-neutral sandbox client. When provided, Bash, Read, Write, and Edit use the sandbox execution plane instead of the host process/filesystem:
 
+<!-- doc-example-skip: requires the optional e2b dependency -->
+
 ```typescript
 import { InteractiveSession } from '@robota-sdk/agent-framework';
 import { AnthropicProvider } from '@robota-sdk/agent-provider/anthropic';
@@ -340,7 +361,7 @@ const session = new InteractiveSession({
 });
 ```
 
-`E2BSandboxClient` is a structural adapter owned by `agent-tools`, and it does not make `e2b` a dependency of `agent-sdk`. Install and create the concrete provider SDK in the application layer, then pass the adapter into `InteractiveSession`. `workspaceManifest` also uses the `agent-tools` contract; SDK applies it once before constructing the underlying `Session`.
+`E2BSandboxClient` is a structural adapter owned by `agent-tools`, and it does not make `e2b` a dependency of `agent-framework`. Install and create the concrete provider SDK in the application layer, then pass the adapter into `InteractiveSession`. `workspaceManifest` also uses the `agent-tools` contract; SDK applies it once before constructing the underlying `Session`.
 
 When `sessionStore` and a snapshot-capable `sandboxClient` are both provided, `InteractiveSession.shutdown()` stores `sandboxSnapshotId` in the session record. A later non-fork `resumeSessionId` restore calls `sandboxClient.restore(snapshotId)` before saved messages are injected back into the `Session`. Forked sessions intentionally do not hydrate the previous sandbox reference because provider pause/resume references can be one-to-one.
 
@@ -350,13 +371,12 @@ When `sessionStore` and a snapshot-capable `sandboxClient` are both provided, `I
 
 ```typescript
 import { createSubagentSession } from '@robota-sdk/agent-framework';
+import type { ISubagentOptions } from '@robota-sdk/agent-framework';
 
-const subSession = createSubagentSession({
-  parentSession: session,
-  agentDefinition: 'explore',
-  prompt: 'Analyze the test coverage gaps',
-});
-const result = await subSession.run();
+// agentDefinition, parentConfig/parentContext/parentTools, provider, terminal, …
+declare const options: ISubagentOptions;
+const subSession = createSubagentSession(options);
+const result = await subSession.run('Analyze the test coverage gaps');
 ```
 
 ### Agent Definitions
@@ -379,7 +399,7 @@ Provider-native payload events are emitted by concrete provider packages through
 
 ## Hook Executors (SDK-Specific)
 
-`agent-sdk` provides two `IHookTypeExecutor` implementations beyond the `command` and `http` executors in `agent-core`:
+`agent-framework` provides two `IHookTypeExecutor` implementations beyond the `command` and `http` executors in `agent-core`:
 
 | Executor         | Hook Type | Description                                                               |
 | ---------------- | --------- | ------------------------------------------------------------------------- |
@@ -411,26 +431,24 @@ Manages plugin installation and uninstallation:
 
 ## Plugins
 
-`agent-plugin-*` packages are **consumer opt-in** — they are not built into the CLI or SDK by default. Application consumers register plugins at composition time by passing plugin instances to the SDK assembly API.
+`@robota-sdk/agent-plugin` plugins are **consumer opt-in** — they are not built into the CLI or SDK by default. Application consumers register plugins at composition time by passing plugin instances to the SDK assembly API.
 
 ```typescript
-import { InteractiveSession } from '@robota-sdk/agent-framework';
-import { AnthropicProvider } from '@robota-sdk/agent-provider/anthropic';
-import { ConversationHistoryPlugin } from '@robota-sdk/agent-plugin';
-import { LoggingPlugin } from '@robota-sdk/agent-plugin';
+import { Robota } from '@robota-sdk/agent-core';
+import { ConversationHistoryPlugin, LoggingPlugin } from '@robota-sdk/agent-plugin';
+import type { IAgentConfig } from '@robota-sdk/agent-core';
 
-const session = new InteractiveSession({
-  cwd: process.cwd(),
-  config,
-  context,
+declare const base: IAgentConfig;
+const agent = new Robota({
+  ...base,
   plugins: [
-    new ConversationHistoryPlugin({ maxMessages: 100 }),
-    new LoggingPlugin({ level: 'info' }),
+    new ConversationHistoryPlugin({ storage: 'memory' }),
+    new LoggingPlugin({ strategy: 'console', level: 'info' }),
   ],
 });
 ```
 
-Each plugin implements `AbstractPlugin` from `@robota-sdk/agent-core` and depends only on `agent-core`. Available plugins: `agent-plugin-conversation-history`, `agent-plugin-error-handling`, `agent-plugin-event-emitter`, `agent-plugin-execution-analytics`, `agent-plugin-limits`, `agent-plugin-logging`, `agent-plugin-performance`, `agent-plugin-usage`, `agent-plugin-webhook`.
+Each plugin implements `AbstractPlugin` from `@robota-sdk/agent-core` and depends only on `agent-core`. The 8 plugins ship consolidated in a single package, `@robota-sdk/agent-plugin`: `ConversationHistoryPlugin`, `ErrorHandlingPlugin`, `ExecutionAnalyticsPlugin`, `LimitsPlugin`, `LoggingPlugin`, `PerformancePlugin`, `UsagePlugin`, `WebhookPlugin`.
 
 ## Configuration
 
@@ -510,4 +528,4 @@ See [docs/SPEC.md](./docs/SPEC.md) for the full specification, architecture deta
 
 ## License
 
-MIT
+Robota is dual-licensed under the [GNU AGPL-3.0](../../LICENSE) or a [commercial license](../../COMMERCIAL.md). See [LICENSING.md](../../LICENSING.md).