@anvia/studio 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Indra Zulfi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,69 @@
+# @anvia/studio
+
+Studio UI and HTTP runtime for Anvia agents.
+
+Use this package to serve local agents over HTTP, inspect sessions and traces in the browser UI, and exercise tool approval workflows during development.
+
+## Installation
+
+```sh
+pnpm add @anvia/studio @anvia/core
+```
+
+In this monorepo, the package is available through the workspace:
+
+```sh
+pnpm --filter @anvia/studio build
+```
+
+## Usage
+
+```ts
+import { AgentBuilder } from "@anvia/core";
+import { OpenAIClient } from "@anvia/openai";
+import { Studio } from "@anvia/studio";
+
+const client = new OpenAIClient({
+  apiKey,
+});
+
+const agent = new AgentBuilder("support", client.completionModel())
+  .name("Support")
+  .description("Answers support questions.")
+  .instructions("Answer support questions clearly.")
+  .build();
+
+new Studio([agent]).start({
+  port: 4021,
+});
+```
+
+Then open:
+
+```txt
+http://localhost:4021/playground
+```
+
+## Session Storage
+
+Studio uses a local SQLite store by default so sessions and traces can persist across process restarts. If you omit the port, Studio uses `RUNNER_PORT` and then falls back to `4021`.
+
+Set `ANVIA_STUDIO_DB` to control the database path:
+
+```sh
+ANVIA_STUDIO_DB=.anvia/studio.sqlite node ./dist/server.js
+```
+
+## Exports
+
+- `Studio`
+- `createSqliteSessionStore`
+- Studio session, trace, approval, and runtime types
+
+## Development
+
+```sh
+pnpm --filter @anvia/studio typecheck
+pnpm --filter @anvia/studio test
+pnpm --filter @anvia/studio build
+```

package/dist/index.d.ts

@@ -0,0 +1,344 @@
+import { Message, JsonObject, AgentTraceOptions, PromptResponse, AgentStreamEvent, JsonValue, Usage, AgentTraceInfo, Agent, AgentObserver, AgentRunStartArgs, AgentRunObserver } from '@anvia/core';
+import { Hono } from 'hono';
+
+type StudioCapability = "agents" | "approvals" | "knowledge" | "observability" | "sessions" | "traces";
+type StudioAgent = {
+    id: string;
+    agent: Agent;
+    name?: string;
+    description?: string;
+    quickPrompts?: string[];
+    metadata?: JsonObject;
+};
+type StudioAgentConfig = {
+    id: string;
+    name?: string;
+    description?: string;
+    quickPrompts: string[];
+    metadata?: JsonObject;
+};
+type StudioCapabilityConfig = {
+    enabled: boolean;
+    reason?: string;
+};
+type StudioConfig = {
+    id: string;
+    name?: string;
+    description?: string;
+    version?: string;
+    agents: StudioAgentConfig[];
+    chat: {
+        quickPrompts: Record<string, string[]>;
+    };
+    capabilities: Partial<Record<StudioCapability, StudioCapabilityConfig>>;
+    unsupportedCapabilities: StudioCapability[];
+};
+type StudioTranscriptChatEntry = {
+    entryId: number;
+    kind: "message";
+    role: "user" | "assistant";
+    text: string;
+    traceId?: string;
+};
+type StudioTranscriptReasoningEntry = {
+    entryId: number;
+    kind: "reasoning";
+    reasoningId?: string;
+    text: string;
+};
+type StudioTranscriptToolEntry = {
+    entryId: number;
+    kind: "tool";
+    toolName: string;
+    callId?: string;
+    args?: string;
+    result?: string;
+    approval?: StudioToolApprovalTranscript;
+    question?: StudioToolQuestionTranscript;
+};
+type StudioTranscriptEntry = StudioTranscriptChatEntry | StudioTranscriptReasoningEntry | StudioTranscriptToolEntry;
+type StudioSessionSummary = {
+    id: string;
+    agentId: string;
+    title?: string;
+    createdAt: string;
+    updatedAt: string;
+    messageCount: number;
+    metadata?: JsonObject;
+};
+type StudioSession = StudioSessionSummary & {
+    messages: Message[];
+    transcript: StudioTranscriptEntry[];
+};
+type StudioSessionCreateInput = {
+    id: string;
+    agentId: string;
+    title?: string;
+    metadata?: JsonObject;
+};
+type StudioSessionListOptions = {
+    agentId?: string;
+    limit: number;
+};
+type StudioSessionAppendInput = {
+    id: string;
+    title?: string;
+    messages: Message[];
+    transcript: StudioTranscriptEntry[];
+};
+type StudioSessionStore = {
+    readonly kind?: string;
+    listSessions(options: StudioSessionListOptions): StudioSessionSummary[] | Promise<StudioSessionSummary[]>;
+    createSession(input: StudioSessionCreateInput): StudioSessionSummary | Promise<StudioSessionSummary>;
+    getSession(id: string): StudioSession | undefined | Promise<StudioSession | undefined>;
+    appendSessionRun(input: StudioSessionAppendInput): StudioSession | undefined | Promise<StudioSession | undefined>;
+    deleteSession?(id: string): boolean | Promise<boolean>;
+};
+type StudioTraceStatus = "running" | "success" | "error";
+type StudioTraceObservationKind = "generation" | "tool";
+type StudioTraceObservation = {
+    id: string;
+    kind: StudioTraceObservationKind;
+    name: string;
+    status: StudioTraceStatus;
+    turn: number;
+    startedAt: string;
+    endedAt?: string;
+    durationMs?: number;
+    input?: JsonValue;
+    output?: JsonValue;
+    error?: JsonValue;
+    metadata?: JsonObject;
+};
+type StudioTraceSummary = {
+    id: string;
+    sessionId: string;
+    name?: string;
+    status: StudioTraceStatus;
+    startedAt: string;
+    endedAt?: string;
+    durationMs?: number;
+    output?: string;
+    error?: JsonValue;
+    usage?: Usage;
+    metadata?: JsonObject;
+    observationCount: number;
+};
+type StudioTrace = StudioTraceSummary & {
+    trace?: AgentTraceInfo;
+    input?: JsonValue;
+    observations: StudioTraceObservation[];
+};
+type StudioTraceListOptions = {
+    limit: number;
+    agentId?: string;
+    sessionId?: string;
+    status?: StudioTraceStatus;
+};
+type StudioSessionTraceListOptions = {
+    sessionId: string;
+    limit: number;
+};
+type StudioTraceStore = {
+    readonly kind?: string;
+    listTraces?(options: StudioTraceListOptions): StudioTraceSummary[] | Promise<StudioTraceSummary[]>;
+    listSessionTraces(options: StudioSessionTraceListOptions): StudioTraceSummary[] | Promise<StudioTraceSummary[]>;
+    getTrace(id: string): StudioTrace | undefined | Promise<StudioTrace | undefined>;
+    saveTrace(trace: StudioTrace): StudioTrace | Promise<StudioTrace>;
+};
+type StudioKnowledgeSourceKind = "static_context" | "dynamic_context" | "dynamic_tools";
+type StudioKnowledgeSourceSummary = {
+    kind: StudioKnowledgeSourceKind;
+    count: number;
+};
+type StudioStaticKnowledgeDocument = {
+    id: string;
+    text: string;
+    additionalProps?: JsonObject;
+};
+type StudioKnowledgeEvidenceDocument = {
+    id?: string;
+    text?: string;
+    additionalProps?: JsonObject;
+};
+type StudioKnowledgeEvidence = {
+    traceId: string;
+    sessionId: string;
+    observationId: string;
+    observationName: string;
+    turn: number;
+    startedAt: string;
+    query?: string;
+    documentCount: number;
+    toolCount: number;
+    documents: StudioKnowledgeEvidenceDocument[];
+    tools: string[];
+};
+type StudioAgentKnowledgeConfig = {
+    agentId: string;
+    agentName?: string;
+    sources: StudioKnowledgeSourceSummary[];
+    staticContext: StudioStaticKnowledgeDocument[];
+};
+type StudioKnowledgeSummary = {
+    agents: StudioAgentKnowledgeConfig[];
+    evidence: StudioKnowledgeEvidence[];
+};
+type StudioStores = {
+    sessions?: StudioSessionStore | false;
+    traces?: StudioTraceStore;
+};
+type StudioUiOptions = {
+    path?: string;
+    rootRoutes?: boolean;
+    title?: string;
+    redirectRoot?: boolean;
+    clientScript?: string;
+    protectShell?: boolean;
+};
+type StudioOptions = {
+    quickPrompts?: Record<string, string[]>;
+};
+type StudioServeOptions = {
+    port?: number;
+    hostname?: string;
+    log?: boolean;
+};
+type StudioToolApprovalDecision = {
+    approved: boolean;
+    reason?: string;
+};
+type StudioToolApprovalStatus = "pending" | "approved" | "rejected" | "timed_out";
+type StudioToolApproval = {
+    id: string;
+    runId: string;
+    agentId: string;
+    sessionId?: string;
+    toolName: string;
+    callId?: string;
+    internalCallId: string;
+    args: string;
+    status: StudioToolApprovalStatus;
+    requestedAt: string;
+    resolvedAt?: string;
+    reason?: string;
+};
+type StudioToolApprovalTranscript = {
+    id: string;
+    status: StudioToolApprovalStatus;
+    requestedAt: string;
+    resolvedAt?: string;
+    reason?: string;
+};
+type StudioToolApprovalRequestEvent = {
+    type: "tool_approval_request";
+    approval: StudioToolApproval;
+};
+type StudioToolApprovalResultEvent = {
+    type: "tool_approval_result";
+    approval: StudioToolApproval;
+};
+type StudioToolQuestionChoice = {
+    label: string;
+    value: string;
+};
+type StudioToolQuestionPrompt = {
+    id: string;
+    question: string;
+    choices: StudioToolQuestionChoice[];
+};
+type StudioToolQuestionAnswer = {
+    questionId: string;
+    answer: string;
+    choice?: string;
+    custom?: boolean;
+};
+type StudioToolQuestionStatus = "pending" | "answered";
+type StudioToolQuestion = {
+    id: string;
+    runId: string;
+    agentId: string;
+    sessionId?: string;
+    toolName: string;
+    callId?: string;
+    internalCallId: string;
+    args: string;
+    questions: StudioToolQuestionPrompt[];
+    status: StudioToolQuestionStatus;
+    requestedAt: string;
+    answeredAt?: string;
+    answers?: StudioToolQuestionAnswer[];
+};
+type StudioToolQuestionTranscript = {
+    id: string;
+    status: StudioToolQuestionStatus;
+    requestedAt: string;
+    answeredAt?: string;
+    questions: StudioToolQuestionPrompt[];
+    answers?: StudioToolQuestionAnswer[];
+};
+type StudioToolQuestionRequestEvent = {
+    type: "tool_question_request";
+    question: StudioToolQuestion;
+};
+type StudioToolQuestionResultEvent = {
+    type: "tool_question_result";
+    question: StudioToolQuestion;
+};
+type AgentRunRequest = {
+    message: string | Message;
+    history?: Message[];
+    sessionId?: string;
+    stream?: boolean;
+    maxTurns?: number;
+    toolConcurrency?: number;
+    metadata?: JsonObject;
+    trace?: AgentTraceOptions;
+};
+type AgentRunResponse = PromptResponse;
+type AgentRunStreamEvent = AgentStreamEvent | StudioToolApprovalRequestEvent | StudioToolApprovalResultEvent | StudioToolQuestionRequestEvent | StudioToolQuestionResultEvent;
+type StudioErrorCode = "bad_request" | "conflict" | "not_found" | "unsupported_capability" | "internal_error";
+type StudioErrorResponse = {
+    error: {
+        code: StudioErrorCode;
+        message: string;
+        details?: JsonValue;
+    };
+};
+type AnviaStudio = {
+    readonly app: Hono;
+    fetch(request: Request): Response | Promise<Response>;
+    config(): StudioConfig;
+    close(): void;
+};
+
+type StudioTraceObserverOptions = {
+    store: StudioTraceStore | (() => StudioTraceStore | undefined) | undefined;
+};
+declare class StudioTraceObserver implements AgentObserver {
+    private readonly options;
+    constructor(options: StudioTraceObserverOptions);
+    startRun(args: AgentRunStartArgs): AgentRunObserver;
+    private store;
+}
+
+declare class Studio implements AnviaStudio {
+    private readonly options;
+    private studio;
+    private server;
+    private sigintHandler;
+    constructor(agents?: Agent[], options?: StudioOptions);
+    get app(): Hono;
+    fetch(request: Request): Response | Promise<Response>;
+    config(): StudioConfig;
+    traceObserver(): StudioTraceObserver;
+    start(serveOptions?: StudioServeOptions): this;
+    close(): void;
+}
+
+type SqliteSessionStoreOptions = {
+    path?: string;
+};
+declare function createSqliteSessionStore(options?: SqliteSessionStoreOptions): StudioSessionStore & StudioTraceStore;
+
+export { type AgentRunRequest, type AgentRunResponse, type AgentRunStreamEvent, type AnviaStudio, type SqliteSessionStoreOptions, Studio, type StudioAgent, type StudioAgentConfig, type StudioAgentKnowledgeConfig, type StudioCapability, type StudioCapabilityConfig, type StudioConfig, type StudioErrorCode, type StudioErrorResponse, type StudioKnowledgeEvidence, type StudioKnowledgeEvidenceDocument, type StudioKnowledgeSourceKind, type StudioKnowledgeSourceSummary, type StudioKnowledgeSummary, type StudioOptions, type StudioServeOptions, type StudioSession, type StudioSessionAppendInput, type StudioSessionCreateInput, type StudioSessionListOptions, type StudioSessionStore, type StudioSessionSummary, type StudioSessionTraceListOptions, type StudioStaticKnowledgeDocument, type StudioStores, type StudioToolApproval, type StudioToolApprovalDecision, type StudioToolApprovalRequestEvent, type StudioToolApprovalResultEvent, type StudioToolApprovalStatus, type StudioToolApprovalTranscript, type StudioToolQuestion, type StudioToolQuestionAnswer, type StudioToolQuestionChoice, type StudioToolQuestionPrompt, type StudioToolQuestionRequestEvent, type StudioToolQuestionResultEvent, type StudioToolQuestionStatus, type StudioToolQuestionTranscript, type StudioTrace, type StudioTraceListOptions, type StudioTraceObservation, type StudioTraceObservationKind, StudioTraceObserver, type StudioTraceObserverOptions, type StudioTraceStatus, type StudioTraceStore, type StudioTraceSummary, type StudioTranscriptChatEntry, type StudioTranscriptEntry, type StudioTranscriptReasoningEntry, type StudioTranscriptToolEntry, type StudioUiOptions, createSqliteSessionStore };