@cuylabs/agent-core 0.8.0 → 0.10.0

package/README.md

@@ -1,11 +1,12 @@
 # @cuylabs/agent-core
 
-Embeddable AI agent infrastructure built on the AI SDK.
+Composable AI agent harness with pluggable execution control.
 
-`@cuylabs/agent-core` is the in-process execution layer in this workspace. It
-owns the `Agent` API, tool and model execution semantics, middleware, sessions,
-prompt construction, tracing, and the reusable task/turn/workflow primitives
-that higher layers build on.
+`@cuylabs/agent-core` is the in-process execution kernel for AI agents. It owns
+the `Agent` API, streaming execution, tool and model semantics, middleware and
+lifecycle hooks, sessions, prompt construction, tracing, and the reusable
+task/turn/workflow primitives that runtime packages build on for durability,
+hosting, and scheduling.
 
 ## Package Boundary
 
@@ -15,15 +16,20 @@ Use `@cuylabs/agent-core` when you want:
 - tool definition and execution
 - model hooks, tool hooks, and lifecycle middleware
 - sessions, storage, branching, and prompt construction
-- tracing, MCP, skills, presets, and sub-agents
-- runtime-facing task/turn/workflow helpers from `@cuylabs/agent-core/runtime`
+- tracing, MCP, skills, profiles, and dispatch-based child-agent tools
+- execution-facing task/turn/workflow helpers from `@cuylabs/agent-core/execution`
 
 This package does not own outer orchestration or hosting:
 
-- use `@cuylabs/agent-runtime` for jobs, schedules, retries, and workload dispatch
-- use `@cuylabs/agent-runtime-dapr` for Dapr-backed durability and workflow hosting
+- use `@cuylabs/agent-runtime` for the backend-agnostic orchestration contract — it defines the interfaces for scheduling, dispatch, workload lifecycle, and execution stores that runtime backends implement
+- use `@cuylabs/agent-runtime-dapr` for a concrete backend that implements those contracts with Dapr workflows, state stores, and pub/sub
+- use `@cuylabs/agent-server` for a transport-neutral local server with session management, turn execution, and streamed event fanout over WebSocket / stdio
 - use `@cuylabs/agent-http` for an AI SDK chat-stream HTTP adapter
 
+`@cuylabs/agent-core` includes the default local execution host. Non-local
+tool environments should live in separate packages so the execution semantics
+and host implementations stay decoupled.
+
 ## Core Capabilities
 
 - Streaming agent execution with structured events
@@ -31,9 +37,11 @@ This package does not own outer orchestration or hosting:
 - Middleware for model input/output, stream chunks, tool calls, and lifecycle hooks
 - Session persistence with branching support
 - Prompt pipeline and dynamic prompt sections
-- Skills and built-in sub-agent delegation
+- Skills and built-in dispatch-based child-agent delegation
 - OpenTelemetry tracing
 - MCP integration
+- EventBus — pluggable pub/sub with history replay and backpressure
+- AgentSignal — typed inter-agent signalling within teams
 - Runtime-facing task, turn, and workflow primitives for durable adapters
 
 ## Installation
@@ -110,17 +118,23 @@ structure when you want clearer boundaries:
 import { createAgent, Tool } from "@cuylabs/agent-core";
 import type { AgentMiddleware } from "@cuylabs/agent-core/middleware";
 import { Inference } from "@cuylabs/agent-core/inference";
-import { createAgentTaskRunner } from "@cuylabs/agent-core/runtime";
-import { localHost } from "@cuylabs/agent-core/host";
+import { createAgentTaskRunner } from "@cuylabs/agent-core/execution";
+import { localHost } from "@cuylabs/agent-core/tool/host";
 import { createPromptBuilder } from "@cuylabs/agent-core/prompt";
 import { withinScope } from "@cuylabs/agent-core/scope";
 import { createSkillRegistry } from "@cuylabs/agent-core/skill";
-import { createSubAgentTools } from "@cuylabs/agent-core/sub-agent";
+import { createSubAgentTools } from "@cuylabs/agent-core/subagents";
 import { createMCPManager } from "@cuylabs/agent-core/mcp";
+import { createEventBus } from "@cuylabs/agent-core/events";
+import type { AgentSignal } from "@cuylabs/agent-core/signal";
 ```
 
 Additional focused entrypoints are available for `tool`, `tracking`, `storage`,
-`context`, `reasoning`, `models`, `mcp`, `inference`, `host`, and `scope`.
+`reasoning`, `models`, `mcp`, `inference`, `tool/host`, `scope`, `dispatch`,
+`subagents`, `events`, and `signal`.
+
+For non-local tool execution environments, install a dedicated host package and
+pass its host instance through the same `host` option.
 
 ## Relationship To The Runtime Packages
 
@@ -150,10 +164,12 @@ Start with the package docs:
 
 - [docs/README.md](./docs/README.md) for the learning path
 - [docs/agent.md](./docs/agent.md) for the main `Agent` API
-- [docs/middleware.md](./docs/middleware.md) for model/tool hooks and lifecycle middleware
+- [docs/middleware/](./docs/middleware/README.md) for model/tool hooks and lifecycle middleware
 - [docs/scope.md](./docs/scope.md) for nested execution lineage and scope snapshots
-- [docs/tools.md](./docs/tools.md) for tool definition and execution
-- [docs/runtime-integration.md](./docs/runtime-integration.md) for task/turn/workflow runtime integration
+- [docs/tools/](./docs/tools/README.md) for tool definition and execution
+- [docs/execution/README.md](./docs/execution/README.md) for task/turn/workflow execution integration
+- [docs/events.md](./docs/events.md) for the EventBus pub/sub interface
+- [docs/signal.md](./docs/signal.md) for inter-agent signalling
 - [docs/tracing.md](./docs/tracing.md) for tracing setup
 
 Runnable examples live in [examples/README.md](./examples/README.md).