@anvia/studio 1.1.1 → 1.2.0

package/README.md

@@ -5,6 +5,58 @@ knowledge inspection.
 
 Use this package to serve local agents and pipelines over HTTP, inspect sessions, traces, tools, MCPs, Memory, Status, and Knowledge in the browser UI, and exercise tool approval workflows during development.
 
+## Agent teams
+
+Register existing team definitions alongside agents and pipelines:
+
+```ts
+import { Agent, AgentTeam } from "@anvia/core/agent";
+import { Studio } from "@anvia/studio";
+
+const researcher = new Agent({ id: "researcher", model });
+const team = new AgentTeam({ id: "research-team", model, members: [researcher] });
+await new Studio([researcher, team]).serve({ port: 4021 });
+```
+
+Select a team from the playground's agent/team selector. A Studio configured with only teams
+opens its first team automatically. Submit a task to the coordinator, send follow-ups while it
+runs, or stop the whole team. The Members panel shows queued and active instances, including
+recursive children; selecting an instance reveals its output, tool activity, run messages, and
+usage. The Messages panel shows sender, recipient, and delivery status (the latest 500 messages).
+Approvals and questions appear as independent cards labeled with the requesting member.
+
+Team tasks are local to the current page. Stopping or leaving a task requests server cancellation
+independently of closing its stream. Completed tasks remain visible until you choose **New task**. They do not appear in saved agent sessions.
+
+`GET /teams` and `/config` expose team IDs, registered member definitions, and limits.
+`GET /teams/:teamId` returns one definition. Duplicate team IDs are rejected; agent and team
+IDs occupy separate namespaces. Members are not automatically registered as standalone agents.
+
+| Endpoint                                                      | Request                                  | Behavior                                 |
+| ------------------------------------------------------------- | ---------------------------------------- | ---------------------------------------- |
+| `POST /teams/:teamId/runs`                                    | `{ prompt }` or `{ messages }`           | Start an attributed JSONL event stream   |
+| `POST /teams/:teamId/runs/:runId/steer`                       | `{ prompt }` or user-only `{ messages }` | Queue user input for the coordinator     |
+| `POST /teams/:teamId/runs/:runId/cancel`                      | `{}`                                     | Cancel the entire team                   |
+| `POST /teams/:teamId/runs/:runId/interactions/:interactionId` | `AgentInteractionResponse`               | Resolve one pending approval or question |
+
+The stream begins with `{ type: "team_run_started", teamId, runId }`; the same Studio control
+ID is available in the `x-anvia-team-run-id` response header. Subsequent events follow
+`AgentTeamEvent`, with core's separate `teamRunId`, instance IDs, parent IDs, and depth.
+Internal agent continuation events are omitted; attributed `interaction` events contain everything
+needed for the application's approval/question UI. Terminal failures emit an `error` event.
+Team requests accept at most 1 MiB of JSON and 256 messages; oversized bodies or message counts return 413.
+`StudioTeamRunRequest`, `StudioTeamRunEvent`, and `StudioTeamConfig` are exported for clients.
+
+Runs and pending interactions are scoped to the team and Studio run ID. Invalid replies leave
+the interaction pending; repeated replies are rejected. Several members may request approval
+simultaneously, and only the HTTP application can answer them. Apply authentication/authorization
+middleware to these routes when exposing Studio remotely, as with other Studio execution routes.
+
+Disconnecting the stream or shutting down Studio cancels the team and its pending interactions.
+Completed runs leave the live registry; later control requests return 404. Core's configured event
+buffer limit bounds unread events. Team runs currently use ephemeral conversations and are not
+stored in Studio's agent session history; this API does not provide reconnection or durable resume.
+
 ## Installation
 
 ```sh

package/dist/index.d.ts

@@ -1,13 +1,39 @@
 import { Hono } from 'hono';
 import { AgentObserver, AgentRunStartArgs, AgentRunObserver } from '@anvia/core/observability';
-import { AgentOutcome, AgentInteractionOutcome, AgentStreamEvent, Agent } from '@anvia/core/agent';
+import { AgentTeamLimits, AgentTeamEvent, AgentOutcome, AgentInteractionOutcome, AgentStreamEvent, Agent, AgentTeam } from '@anvia/core/agent';
+import { Message, JsonObject, JsonValue, CompletionModelCapabilities, CompletionModelControls, ToolResultContentPart, Usage, CompletionModel, StreamingCompletionModel } from '@anvia/core/completion';
 import { AgentInteractionResponse } from '@anvia/core/agent/interactions';
-import { JsonObject, Message, JsonValue, CompletionModelCapabilities, CompletionModelControls, ToolResultContentPart, Usage, CompletionModel, StreamingCompletionModel } from '@anvia/core/completion';
 import { MemoryStore, MemoryAppendOptions, MemoryErrorOptions, MemoryScope } from '@anvia/core/memory';
 import { ModelList } from '@anvia/core/model-listing';
 import { Pipeline, PipelineGraph } from '@anvia/core/pipeline';
 import { GraphExplorer } from '@anvia/graph';
 
+type StudioTeamConfig = {
+    id: string;
+    members: {
+        id: string;
+        name?: string;
+        description?: string;
+    }[];
+    limits: Readonly<Required<AgentTeamLimits>>;
+};
+type StudioTeamRunRequest = {
+    prompt: string;
+    messages?: never;
+} | {
+    messages: readonly Message[];
+    prompt?: never;
+};
+/** JSONL events; runId on team_run_started addresses Studio's live run controls. */
+type StudioTeamRunEvent = {
+    type: "team_run_started";
+    teamId: string;
+    runId: string;
+} | AgentTeamEvent<unknown> | {
+    type: "error";
+    error: unknown;
+};
+
 declare function traceSummary(trace: StudioTrace): StudioTraceSummary;
 
 type StudioCapability = "agents" | "interactions" | "evals" | "graphs" | "memory" | "knowledge" | "mcps" | "observability" | "pipelines" | "sandboxes" | "sessions" | "status" | "tools" | "traces";
@@ -101,7 +127,7 @@ type StudioAgent = {
     quickPrompts?: string[];
     metadata?: JsonObject;
 };
-type StudioTarget = Agent | Pipeline<any, any>;
+type StudioTarget = Agent | AgentTeam<unknown> | Pipeline<any, any>;
 type StudioAgentConfig = {
     id: string;
     name?: string;
@@ -247,6 +273,7 @@ type StudioConfig = {
     description?: string;
     version?: string;
     agents: StudioAgentConfig[];
+    teams?: StudioTeamConfig[];
     models?: StudioModelsConfig;
     pipelines: StudioPipelineConfig[];
     graphs: StudioGraphConfig[];
@@ -1115,4 +1142,4 @@ declare function createSqliteSessionStore(options?: SqliteSessionStoreOptions):
 
 declare function createInMemoryStudioStore(): StudioSessionStore & StudioTraceStore & StudioPipelineLogStore & StudioPipelineRunStore;
 
-export { type AgentRunRequest, type AgentRunResponse, type AgentRunStreamEvent, type AgentTraceInfo, type AgentTraceOptions, type AnviaStudio, type SqliteSessionStoreOptions, Studio, type StudioAgent, type StudioAgentConfig, type StudioAgentKnowledgeConfig, type StudioAgentMcpServerMetadata, type StudioAgentMcpToolMetadata, type StudioAgentMcpsSummary, type StudioAgentModelPolicy, type StudioAgentModelPolicyConfig, type StudioAgentModelsSummary, type StudioAgentRuntimeSummary, type StudioAgentToolApprovalMetadata, type StudioAgentToolMetadata, type StudioAgentToolSource, type StudioAgentToolsSummary, type StudioCapability, type StudioCapabilityConfig, type StudioConfig, type StudioErrorCode, type StudioErrorResponse, type StudioEvalCasePreview, type StudioEvalMetricSummary, type StudioEvalRunRequest, type StudioEvalRunResponse, type StudioEvalSuite, type StudioEvalSuiteConfig, type StudioGraphConfig, type StudioGraphExploreRequest, type StudioGraphRegistration, type StudioKnowledgeEvidence, type StudioKnowledgeEvidenceDocument, type StudioKnowledgeItem, type StudioKnowledgeItemKind, type StudioKnowledgeItemsPage, type StudioKnowledgeSourceKind, type StudioKnowledgeSourceSummary, type StudioKnowledgeSummary, type StudioMemoryAppendOptions, type StudioMemoryConversationMessages, type StudioMemoryConversationSteps, type StudioMemoryConversationSummary, type StudioMemoryConversationsPage, type StudioMemoryErrorOptions, type StudioMemoryMessageRecord, type StudioMemoryScope, type StudioMemorySourceConversationMessages, type StudioMemorySourceConversationSteps, type StudioMemorySourceConversationSummary, type StudioMemorySourceConversationsPage, type StudioMemorySourceKind, type StudioMemorySourceSummary, type StudioMemorySourceUsersPage, type StudioMemorySourcesPage, type StudioMemoryStore, type StudioMemoryUserSummary, type StudioMemoryUsersPage, type StudioModelConfig, type StudioModelDefinition, type StudioModelModalities, type StudioModelModality, type StudioModelProvider, type StudioModelProviderConfig, type StudioModelRef, type StudioModelSummary, type StudioModelsConfig, type StudioObservabilityEvent, type StudioObservabilityEventType, type StudioOptions, type StudioPipeline, type StudioPipelineConfig, type StudioPipelineDetail, type StudioPipelineFinalEvent, type StudioPipelineLogAppendInput, type StudioPipelineLogCategory, type StudioPipelineLogEntry, type StudioPipelineLogEvent, type StudioPipelineLogLevel, type StudioPipelineLogListOptions, type StudioPipelineLogStore, type StudioPipelineReplayRequest, type StudioPipelineRunGetOptions, type StudioPipelineRunListOptions, type StudioPipelineRunRecord, type StudioPipelineRunRequest, type StudioPipelineRunResponse, type StudioPipelineRunSaveInput, type StudioPipelineRunStatus, type StudioPipelineRunStore, type StudioSandboxCapabilities, type StudioSandboxFileEntry, type StudioSandboxFileType, type StudioSandboxFilesResponse, type StudioSandboxInspector, type StudioSandboxInspectorFileEntry, type StudioSandboxInspectorPort, type StudioSandboxInspectorProcess, type StudioSandboxInspectorProcessLogs, type StudioSandboxPort, type StudioSandboxPortsResponse, type StudioSandboxProcess, type StudioSandboxProcessLogsResponse, type StudioSandboxProcessStatus, type StudioSandboxProcessesResponse, type StudioSandboxRegistration, type StudioSandboxSummary, type StudioSandboxViewAccess, type StudioSandboxViewAuthentication, type StudioSandboxViewAuthorizeArgs, type StudioSandboxViewConnection, type StudioSandboxViewControl, type StudioSandboxViewControlLease, type StudioSandboxViewControlSnapshot, type StudioSandboxViewRegistration, type StudioSandboxViewSource, type StudioSandboxViewSummary, type StudioSandboxesSummary, type StudioServeLifecycleOptions, type StudioServeOptions, type StudioSession, type StudioSessionCreateInput, type StudioSessionListOptions, type StudioSessionLogAppendInput, type StudioSessionLogCategory, type StudioSessionLogEntry, type StudioSessionLogEvent, type StudioSessionLogLevel, type StudioSessionLogListOptions, type StudioSessionRunStatus, type StudioSessionRunTranscriptInput, type StudioSessionStore, type StudioSessionSummary, type StudioSessionTraceListOptions, type StudioStaticKnowledgeDocument, type StudioStatusSummary, type StudioStores, type StudioTarget, type StudioToolApprovalStatus, type StudioToolApprovalTranscript, type StudioToolQuestionAnswer, type StudioToolQuestionChoice, type StudioToolQuestionPrompt, type StudioToolQuestionStatus, type StudioToolQuestionTranscript, type StudioToolRunRequest, type StudioToolRunResponse, type StudioTrace, type StudioTraceListOptions, type StudioTraceObservation, type StudioTraceObservationKind, StudioTraceObserver, type StudioTraceObserverOptions, type StudioTraceStatus, type StudioTraceStore, type StudioTraceSummary, type StudioTranscriptAttachment, type StudioTranscriptChatEntry, type StudioTranscriptChildAgentEvent, type StudioTranscriptEntry, type StudioTranscriptReasoningEntry, type StudioTranscriptToolEntry, type StudioUiOptions, createInMemoryStudioStore, createSqliteSessionStore, traceSummary };
+export { type AgentRunRequest, type AgentRunResponse, type AgentRunStreamEvent, type AgentTraceInfo, type AgentTraceOptions, type AnviaStudio, type SqliteSessionStoreOptions, Studio, type StudioAgent, type StudioAgentConfig, type StudioAgentKnowledgeConfig, type StudioAgentMcpServerMetadata, type StudioAgentMcpToolMetadata, type StudioAgentMcpsSummary, type StudioAgentModelPolicy, type StudioAgentModelPolicyConfig, type StudioAgentModelsSummary, type StudioAgentRuntimeSummary, type StudioAgentToolApprovalMetadata, type StudioAgentToolMetadata, type StudioAgentToolSource, type StudioAgentToolsSummary, type StudioCapability, type StudioCapabilityConfig, type StudioConfig, type StudioErrorCode, type StudioErrorResponse, type StudioEvalCasePreview, type StudioEvalMetricSummary, type StudioEvalRunRequest, type StudioEvalRunResponse, type StudioEvalSuite, type StudioEvalSuiteConfig, type StudioGraphConfig, type StudioGraphExploreRequest, type StudioGraphRegistration, type StudioKnowledgeEvidence, type StudioKnowledgeEvidenceDocument, type StudioKnowledgeItem, type StudioKnowledgeItemKind, type StudioKnowledgeItemsPage, type StudioKnowledgeSourceKind, type StudioKnowledgeSourceSummary, type StudioKnowledgeSummary, type StudioMemoryAppendOptions, type StudioMemoryConversationMessages, type StudioMemoryConversationSteps, type StudioMemoryConversationSummary, type StudioMemoryConversationsPage, type StudioMemoryErrorOptions, type StudioMemoryMessageRecord, type StudioMemoryScope, type StudioMemorySourceConversationMessages, type StudioMemorySourceConversationSteps, type StudioMemorySourceConversationSummary, type StudioMemorySourceConversationsPage, type StudioMemorySourceKind, type StudioMemorySourceSummary, type StudioMemorySourceUsersPage, type StudioMemorySourcesPage, type StudioMemoryStore, type StudioMemoryUserSummary, type StudioMemoryUsersPage, type StudioModelConfig, type StudioModelDefinition, type StudioModelModalities, type StudioModelModality, type StudioModelProvider, type StudioModelProviderConfig, type StudioModelRef, type StudioModelSummary, type StudioModelsConfig, type StudioObservabilityEvent, type StudioObservabilityEventType, type StudioOptions, type StudioPipeline, type StudioPipelineConfig, type StudioPipelineDetail, type StudioPipelineFinalEvent, type StudioPipelineLogAppendInput, type StudioPipelineLogCategory, type StudioPipelineLogEntry, type StudioPipelineLogEvent, type StudioPipelineLogLevel, type StudioPipelineLogListOptions, type StudioPipelineLogStore, type StudioPipelineReplayRequest, type StudioPipelineRunGetOptions, type StudioPipelineRunListOptions, type StudioPipelineRunRecord, type StudioPipelineRunRequest, type StudioPipelineRunResponse, type StudioPipelineRunSaveInput, type StudioPipelineRunStatus, type StudioPipelineRunStore, type StudioSandboxCapabilities, type StudioSandboxFileEntry, type StudioSandboxFileType, type StudioSandboxFilesResponse, type StudioSandboxInspector, type StudioSandboxInspectorFileEntry, type StudioSandboxInspectorPort, type StudioSandboxInspectorProcess, type StudioSandboxInspectorProcessLogs, type StudioSandboxPort, type StudioSandboxPortsResponse, type StudioSandboxProcess, type StudioSandboxProcessLogsResponse, type StudioSandboxProcessStatus, type StudioSandboxProcessesResponse, type StudioSandboxRegistration, type StudioSandboxSummary, type StudioSandboxViewAccess, type StudioSandboxViewAuthentication, type StudioSandboxViewAuthorizeArgs, type StudioSandboxViewConnection, type StudioSandboxViewControl, type StudioSandboxViewControlLease, type StudioSandboxViewControlSnapshot, type StudioSandboxViewRegistration, type StudioSandboxViewSource, type StudioSandboxViewSummary, type StudioSandboxesSummary, type StudioServeLifecycleOptions, type StudioServeOptions, type StudioSession, type StudioSessionCreateInput, type StudioSessionListOptions, type StudioSessionLogAppendInput, type StudioSessionLogCategory, type StudioSessionLogEntry, type StudioSessionLogEvent, type StudioSessionLogLevel, type StudioSessionLogListOptions, type StudioSessionRunStatus, type StudioSessionRunTranscriptInput, type StudioSessionStore, type StudioSessionSummary, type StudioSessionTraceListOptions, type StudioStaticKnowledgeDocument, type StudioStatusSummary, type StudioStores, type StudioTarget, type StudioTeamConfig, type StudioTeamRunEvent, type StudioTeamRunRequest, type StudioToolApprovalStatus, type StudioToolApprovalTranscript, type StudioToolQuestionAnswer, type StudioToolQuestionChoice, type StudioToolQuestionPrompt, type StudioToolQuestionStatus, type StudioToolQuestionTranscript, type StudioToolRunRequest, type StudioToolRunResponse, type StudioTrace, type StudioTraceListOptions, type StudioTraceObservation, type StudioTraceObservationKind, StudioTraceObserver, type StudioTraceObserverOptions, type StudioTraceStatus, type StudioTraceStore, type StudioTraceSummary, type StudioTranscriptAttachment, type StudioTranscriptChatEntry, type StudioTranscriptChildAgentEvent, type StudioTranscriptEntry, type StudioTranscriptReasoningEntry, type StudioTranscriptToolEntry, type StudioUiOptions, createInMemoryStudioStore, createSqliteSessionStore, traceSummary };