@yolo-labs/core-types 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,645 @@
+/**
+ * Plain text content block.
+ *
+ * @remarks
+ * The most common content block type, representing a segment of text
+ * in a conversation message.
+ */
+interface TextBlock {
+    type: 'text';
+    text: string;
+}
+/**
+ * Image content block with inline base64-encoded data.
+ *
+ * @remarks
+ * Used when the image data is available directly, e.g. from a file upload
+ * or canvas capture. The `media_type` should be a valid MIME type such as
+ * `image/png`, `image/jpeg`, `image/gif`, or `image/webp`.
+ */
+interface ImageBlockBase64 {
+    type: 'image';
+    source: {
+        type: 'base64';
+        media_type: string;
+        data: string;
+    };
+}
+/**
+ * Image content block referenced by URL.
+ *
+ * @remarks
+ * Used when the image is hosted at a publicly accessible URL.
+ * The provider adapter is responsible for fetching or passing through the URL.
+ */
+interface ImageBlockUrl {
+    type: 'image';
+    source: {
+        type: 'url';
+        url: string;
+    };
+}
+/** An image block, either base64-encoded or URL-referenced. */
+type ImageBlock = ImageBlockBase64 | ImageBlockUrl;
+/**
+ * File content block with base64-encoded data and optional filename.
+ *
+ * @remarks
+ * Represents non-image file attachments (e.g. PDFs, CSVs). Not all providers
+ * support file blocks natively; adapters may convert them to text references.
+ */
+interface FileBlock {
+    type: 'file';
+    source: {
+        type: 'base64';
+        media_type: string;
+        data: string;
+        name?: string;
+    };
+}
+/**
+ * Tool use content block representing an assistant's tool call in conversation history.
+ *
+ * @remarks
+ * When the assistant decides to invoke a tool, the response includes one or more
+ * `ToolUseBlock` entries alongside any `TextBlock` entries. The `id` is provider-assigned
+ * and must be referenced by the corresponding {@link ToolResultBlock}.
+ */
+interface ToolUseBlock {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+/**
+ * Tool result content block representing the output of a tool execution.
+ *
+ * @remarks
+ * After executing one or more tool calls, the results are sent back as a user message
+ * containing `ToolResultBlock` entries. The `tool_use_id` must match the `id` from the
+ * corresponding {@link ToolUseBlock} so the provider can correlate calls with results.
+ */
+interface ToolResultBlock {
+    type: 'tool_result';
+    tool_use_id: string;
+    content: string;
+    is_error?: boolean;
+}
+/** Union of all supported multimodal content block types. */
+type ContentBlock = TextBlock | ImageBlock | FileBlock | ToolUseBlock | ToolResultBlock;
+/**
+ * A conversation message with a role and multimodal content.
+ *
+ * @remarks
+ * Content can be a plain string for text-only messages, or an array of
+ * {@link ContentBlock} for multimodal messages containing images or files.
+ */
+interface Message {
+    role: 'user' | 'assistant';
+    content: string | ContentBlock[];
+}
+
+/** Emitted when the agent begins processing a request. */
+interface AgentStartEvent {
+    type: 'agent_start';
+    sessionId: string;
+    timestamp: string;
+}
+/** Streamed fragment of the agent's internal reasoning. */
+interface ThoughtDeltaEvent {
+    type: 'thought_delta';
+    text: string;
+}
+/** Streamed fragment of the agent's visible text output. */
+interface TextDeltaEvent {
+    type: 'text_delta';
+    text: string;
+}
+/**
+ * Emitted when the agent invokes a tool with its resolved name and input.
+ *
+ * @remarks
+ * The `input` field contains the fully parsed JSON input for the tool.
+ * This event is emitted after the tool input has been fully accumulated
+ * from `tool_input_delta` events.
+ */
+interface ToolCallEvent {
+    type: 'tool_call';
+    toolCallId: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+/** Streamed fragment of a tool call's input as it is being constructed. */
+interface ToolInputDeltaEvent {
+    type: 'tool_input_delta';
+    toolCallId: string;
+    partialInput: string;
+}
+/** Reports incremental progress of a long-running tool execution. */
+interface ToolProgressEvent {
+    type: 'tool_progress';
+    toolCallId: string;
+    message: string;
+    percentage?: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Emitted when a tool finishes execution, carrying its output or error.
+ *
+ * @remarks
+ * Check `success` to determine whether the tool completed normally.
+ * On failure, the `error` field contains a human-readable description.
+ * Tool results are fed back into the conversation for the next AI turn.
+ */
+interface ToolResultEvent {
+    type: 'tool_result';
+    toolCallId: string;
+    name: string;
+    success: boolean;
+    output: unknown;
+    error?: string;
+}
+/** General-purpose status notification for session-level state changes. */
+interface StatusUpdateEvent {
+    type: 'status_update';
+    status: string;
+    message?: string;
+    metadata?: Record<string, unknown>;
+}
+/** Emitted when an error occurs, indicating whether the session can recover. */
+interface ErrorEvent {
+    type: 'error';
+    error: string;
+    code?: string;
+    recoverable: boolean;
+}
+/**
+ * Emitted when the agent finishes processing, optionally including token usage.
+ *
+ * @remarks
+ * Always the last event in a generation session. The `usage` field is
+ * populated when the provider reports token counts and turn information.
+ */
+interface AgentCompleteEvent {
+    type: 'agent_complete';
+    sessionId: string;
+    timestamp: string;
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTurns: number;
+    };
+}
+/**
+ * Discriminated union of all session lifecycle and streaming events.
+ *
+ * @remarks
+ * Use the `type` field to discriminate between event variants.
+ * Events are emitted in order through the `AsyncIterable` returned
+ * by {@link agentLoop}.
+ */
+type SessionEvent = AgentStartEvent | ThoughtDeltaEvent | TextDeltaEvent | ToolCallEvent | ToolInputDeltaEvent | ToolProgressEvent | ToolResultEvent | StatusUpdateEvent | ErrorEvent | AgentCompleteEvent;
+
+/** Represents a file with its path, content, and optional encoding. */
+interface FileEntry {
+    path: string;
+    content: string;
+    encoding?: 'utf-8' | 'base64';
+}
+/** Result of a command execution, including exit code and captured output streams. */
+interface CommandResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+/**
+ * Abstraction for file system operations and command execution within a sandboxed environment.
+ *
+ * @remarks
+ * Implementations include {@link InMemorySandbox} (virtual filesystem),
+ * {@link NodeVMSandbox} (isolated VM), and {@link LocalSandboxProvider}
+ * (host filesystem). The optional `build`, `create`, `destroy`, and `reset`
+ * methods support lifecycle management for stateful sandbox environments.
+ */
+interface SandboxProvider {
+    readFile(path: string): Promise<string>;
+    writeFile(path: string, content: string): Promise<void>;
+    deleteFile(path: string): Promise<void>;
+    listFiles(path: string): Promise<string[]>;
+    mkdir(path: string): Promise<void>;
+    executeCommand(command: string, options?: CommandExecutionOptions): Promise<CommandResult>;
+    build?(options?: Record<string, unknown>): Promise<CommandResult>;
+    create?(): Promise<void>;
+    destroy?(): Promise<void>;
+    reset?(): Promise<void>;
+}
+/** Options for configuring command execution, including working directory, environment, and timeout. */
+interface CommandExecutionOptions {
+    cwd?: string;
+    env?: Record<string, string>;
+    timeout?: number;
+    onStdout?: (data: string) => void;
+    onStderr?: (data: string) => void;
+}
+/**
+ * Execution context provided to tools during invocation within a sandbox session.
+ *
+ * @remarks
+ * Every tool receives a `SandboxContext` as its second argument. The context
+ * provides access to the sandbox filesystem, the current session ID, environment
+ * variables, and optional metadata.
+ */
+interface SandboxContext {
+    sandbox: SandboxProvider;
+    sessionId: string;
+    env: Record<string, string>;
+    metadata?: Record<string, unknown>;
+}
+
+/**
+ * Canonical tool definition format sent to AI providers.
+ *
+ * @remarks
+ * The `inputSchema` must be a valid JSON Schema object describing the
+ * tool's expected input parameters. Provider adapters translate this
+ * into their native tool format (e.g. Anthropic `input_schema`, OpenAI
+ * `function.parameters`, Google `functionDeclarations`).
+ */
+interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+/** Result returned after a tool execution, including output and optional error details. */
+interface ToolResult {
+    success: boolean;
+    output: unknown;
+    preview?: string;
+    error?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * An executable tool with its schema and an execute method that runs within a sandbox.
+ *
+ * @remarks
+ * Register tools with a {@link ToolRegistry} to make them available to the
+ * agent loop. The `execute` method receives validated input, a sandbox context,
+ * and an optional progress callback for long-running operations.
+ *
+ * @example
+ * ```ts
+ * const myTool: Tool = {
+ *   name: 'greet',
+ *   description: 'Returns a greeting',
+ *   inputSchema: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] },
+ *   async execute(input, context) {
+ *     return { success: true, output: `Hello, ${input.name}!` };
+ *   },
+ * };
+ * ```
+ */
+interface Tool {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    execute(input: Record<string, unknown>, context: SandboxContext, onProgress?: (progress: ToolProgressInfo) => void): Promise<ToolResult>;
+}
+/** Progress information emitted during long-running tool execution. */
+interface ToolProgressInfo {
+    message: string;
+    percentage?: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Registry for managing and executing tools by name.
+ *
+ * @remarks
+ * Use {@link ToolRegistryImpl} as the default implementation. The registry
+ * provides runtime registration/unregistration, lookup, and serialization
+ * of tools to the AI provider's tool definition format.
+ */
+interface ToolRegistry {
+    register(tool: Tool): void;
+    unregister(name: string): void;
+    get(name: string): Tool | undefined;
+    list(): Tool[];
+    toAIToolDefinitions(): ToolDefinition[];
+}
+
+/**
+ * Parameters for creating an AI message.
+ *
+ * @remarks
+ * This is the canonical, provider-agnostic format for requesting a message
+ * from an AI model. Each provider adapter translates these parameters into
+ * the provider's native API format.
+ */
+interface CreateMessageParams {
+    model: string;
+    messages: Message[];
+    system?: string;
+    tools?: ToolDefinition[];
+    maxTokens?: number;
+    temperature?: number;
+    topP?: number;
+    stopSequences?: string[];
+    metadata?: Record<string, unknown>;
+}
+/** Emitted when a new content block (text or tool use) begins in the stream. */
+interface ContentBlockStartEvent {
+    type: 'content_block_start';
+    index: number;
+    contentBlock: {
+        type: 'text' | 'tool_use';
+        id?: string;
+        name?: string;
+    };
+}
+/** Emitted when an incremental delta (text, thinking, or tool input JSON) is received for a content block. */
+interface ContentBlockDeltaEvent {
+    type: 'content_block_delta';
+    index: number;
+    delta: {
+        type: 'text_delta';
+        text: string;
+    } | {
+        type: 'thinking_delta';
+        thinking: string;
+    } | {
+        type: 'input_json_delta';
+        partial_json: string;
+    };
+}
+/** Emitted when a content block has finished streaming. */
+interface ContentBlockStopEvent {
+    type: 'content_block_stop';
+    index: number;
+}
+/** Emitted at the beginning of a streamed message, containing message metadata and initial usage. */
+interface MessageStartEvent {
+    type: 'message_start';
+    message: {
+        id: string;
+        model: string;
+        role: 'assistant';
+        usage?: {
+            input_tokens: number;
+            output_tokens: number;
+        };
+    };
+}
+/** Emitted near the end of a message with the stop reason and final token usage. */
+interface MessageDeltaEvent {
+    type: 'message_delta';
+    delta: {
+        stop_reason: string | null;
+    };
+    usage?: {
+        output_tokens: number;
+    };
+}
+/** Emitted when the message stream has fully completed. */
+interface MessageStopEvent {
+    type: 'message_stop';
+}
+/** Emitted when an error occurs during message streaming. */
+interface StreamErrorEvent {
+    type: 'error';
+    error: {
+        type: string;
+        message: string;
+    };
+}
+/** Union of all provider-agnostic stream events emitted during message creation. */
+type StreamEvent = MessageStartEvent | ContentBlockStartEvent | ContentBlockDeltaEvent | ContentBlockStopEvent | MessageDeltaEvent | MessageStopEvent | StreamErrorEvent;
+/**
+ * Provider-agnostic interface for AI model interaction via streaming message creation.
+ *
+ * @remarks
+ * Implement this interface to add support for a new AI provider.
+ * The `createMessage` method must return an `AsyncIterable` of canonical
+ * {@link StreamEvent} objects. Provider adapters for Anthropic, OpenAI,
+ * and Google are included in `@yolo-labs/core-providers`.
+ *
+ * @example
+ * ```ts
+ * const provider: AIProvider = new AnthropicProvider({ apiKey: '...' });
+ * for await (const event of provider.createMessage(params)) {
+ *   console.log(event.type);
+ * }
+ * ```
+ */
+interface AIProvider {
+    createMessage(params: CreateMessageParams): AsyncIterable<StreamEvent>;
+}
+
+/**
+ * User request initiating a generation session.
+ *
+ * @remarks
+ * Pass to {@link agentLoop} to start a generation. The `sessionId` is
+ * auto-generated if omitted. Provide `context.conversationHistory` to
+ * resume an existing conversation.
+ */
+interface GenerationRequest {
+    prompt: string;
+    sessionId?: string;
+    context?: Record<string, unknown>;
+    model?: string;
+    system?: string;
+    maxTokens?: number;
+    temperature?: number;
+    tools?: ToolDefinition[];
+    metadata?: Record<string, unknown>;
+}
+/** Stateful session tracking conversation history, tool calls, and metadata. */
+interface GenerationSession {
+    id: string;
+    userId?: string;
+    conversationHistory: Message[];
+    fileSystemSnapshot?: Record<string, string>;
+    toolCallLog: ToolCallLogEntry[];
+    metadata: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Record of a single tool invocation and its result within a session. */
+interface ToolCallLogEntry {
+    toolCallId: string;
+    name: string;
+    input: Record<string, unknown>;
+    output: unknown;
+    success: boolean;
+    timestamp: string;
+}
+/**
+ * Persistence layer for creating, retrieving, and updating generation sessions.
+ *
+ * @remarks
+ * Implement this interface to persist sessions to a database. An in-memory
+ * implementation ({@link InMemorySessionStore}) is provided for development
+ * and testing.
+ */
+interface SessionStore {
+    create(session: Omit<GenerationSession, 'id' | 'createdAt' | 'updatedAt'>): Promise<GenerationSession>;
+    get(id: string): Promise<GenerationSession | undefined>;
+    update(id: string, updates: Partial<GenerationSession>): Promise<GenerationSession>;
+    delete(id: string): Promise<void>;
+    listByUser(userId: string): Promise<GenerationSession[]>;
+    appendEvent(sessionId: string, event: SessionEvent): Promise<void>;
+    getEventsSince(sessionId: string, eventId?: string): Promise<SessionEvent[]>;
+}
+
+/** Versioned prompt entry with content, metadata, and tags. */
+interface PromptRecord {
+    key: string;
+    content: string;
+    version: number;
+    metadata: Record<string, unknown>;
+    tags: string[];
+}
+/**
+ * Storage backend for managing prompt records by key or tags.
+ *
+ * @remarks
+ * Implementations include {@link YamlPromptStore} (file-based) and
+ * {@link DatabasePromptStore} (abstract base for DB-backed stores).
+ */
+interface PromptStore {
+    get(key: string): Promise<PromptRecord | undefined>;
+    list(): Promise<PromptRecord[]>;
+    upsert(record: PromptRecord): Promise<PromptRecord>;
+    delete(key: string): Promise<void>;
+    queryByTags(tags: string[]): Promise<PromptRecord[]>;
+}
+/** Variables and metadata passed to the prompt assembler during rendering. */
+interface PromptAssemblerContext {
+    variables: Record<string, string>;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Combines and renders prompt records into a final prompt string.
+ *
+ * @remarks
+ * Supports `{{variable}}` interpolation and `{{#if var}}...{{/if}}`
+ * conditional sections. Use {@link PromptAssemblerImpl} as the default
+ * implementation.
+ */
+interface PromptAssembler {
+    assemble(keys: string[], context: PromptAssemblerContext): Promise<string>;
+    assembleByTags(tags: string[], context: PromptAssemblerContext): Promise<string>;
+}
+
+/** A single variable declaration within a template, including its default and requirement flag. */
+interface TemplateVariable {
+    name: string;
+    description?: string;
+    default?: string;
+    required: boolean;
+}
+/**
+ * Blueprint describing a scaffoldable project template with files and variables.
+ *
+ * @remarks
+ * A template definition is loaded from a `template.yaml` manifest file.
+ * The `files` map contains relative paths to their file contents.
+ * Variables declared in `variables` can be substituted with `{{var}}`
+ * placeholders in both file paths and file contents during scaffolding.
+ */
+interface TemplateDefinition {
+    id: string;
+    name: string;
+    description: string;
+    files: Record<string, string>;
+    variables: TemplateVariable[];
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Backend for listing, retrieving, and scaffolding project templates.
+ *
+ * @remarks
+ * Implementations include {@link FileSystemTemplateProvider} (local directory)
+ * and {@link GitTemplateProvider} (clones from git repos on demand).
+ */
+interface TemplateProvider {
+    list(): Promise<TemplateDefinition[]>;
+    get(id: string): Promise<TemplateDefinition | undefined>;
+    scaffold(id: string, variables: Record<string, string>): Promise<Record<string, string>>;
+}
+
+/**
+ * Configuration for initializing a headless agent runtime instance.
+ *
+ * @remarks
+ * Pass to {@link createHeadlessAgent} to create an agent. Set `sandbox`
+ * to `'local'` when the agent operates directly on the host filesystem.
+ * The `idlePolicy` controls behavior when the task queue is empty:
+ * `'wait'` keeps the agent alive, `'shutdown'` exits automatically.
+ */
+interface HeadlessAgentConfig {
+    provider: AIProvider;
+    tools: Tool[];
+    prompts: PromptStore | {
+        system?: string;
+        inline?: string[];
+    };
+    sandbox: SandboxProvider | 'local';
+    sessionStore?: SessionStore;
+    initialTask?: string;
+    maxConcurrentTasks?: number;
+    idlePolicy?: 'wait' | 'shutdown';
+}
+/**
+ * Discriminated union of inbound command messages the agent accepts.
+ *
+ * @remarks
+ * Commands are received via an {@link AgentTransport}. Use `type` to
+ * discriminate between variants: `task` submits work, `interrupt` cancels
+ * in-progress work, `shutdown` finishes current work then exits, `abort`
+ * exits immediately, `context_inject` adds runtime context,
+ * `context_clear` resets conversation history, and
+ * `status_query` requests a status report.
+ */
+type AgentCommand = {
+    type: 'task';
+    prompt: string;
+    context?: Record<string, unknown>;
+} | {
+    type: 'interrupt';
+} | {
+    type: 'shutdown';
+} | {
+    type: 'abort';
+} | {
+    type: 'context_inject';
+    key: string;
+    value: unknown;
+} | {
+    type: 'context_clear';
+} | {
+    type: 'status_query';
+};
+/** Outbound status report describing the agent's current state and progress. */
+interface AgentStatus {
+    state: 'idle' | 'working' | 'shutting_down' | 'error';
+    currentTask?: string;
+    queueDepth: number;
+    uptime: number;
+    tasksCompleted: number;
+}
+/**
+ * Pluggable I/O transport for sending commands to and receiving events from the agent.
+ *
+ * @remarks
+ * Implementations include {@link StdioTransport} (JSON lines over stdin/stdout),
+ * {@link MessagePortTransport} (postMessage for Web Workers), and
+ * {@link HttpTransport} (HTTP server with SSE streaming).
+ */
+interface AgentTransport {
+    onCommand(handler: (cmd: AgentCommand) => void): void;
+    emit(event: SessionEvent | AgentStatus): void;
+    close(): Promise<void>;
+}
+
+export type { AIProvider, AgentCommand, AgentCompleteEvent, AgentStartEvent, AgentStatus, AgentTransport, CommandExecutionOptions, CommandResult, ContentBlock, ContentBlockDeltaEvent, ContentBlockStartEvent, ContentBlockStopEvent, CreateMessageParams, ErrorEvent, FileBlock, FileEntry, GenerationRequest, GenerationSession, HeadlessAgentConfig, ImageBlock, ImageBlockBase64, ImageBlockUrl, Message, MessageDeltaEvent, MessageStartEvent, MessageStopEvent, PromptAssembler, PromptAssemblerContext, PromptRecord, PromptStore, SandboxContext, SandboxProvider, SessionEvent, SessionStore, StatusUpdateEvent, StreamErrorEvent, StreamEvent, TemplateDefinition, TemplateProvider, TemplateVariable, TextBlock, TextDeltaEvent, ThoughtDeltaEvent, Tool, ToolCallEvent, ToolCallLogEntry, ToolDefinition, ToolInputDeltaEvent, ToolProgressEvent, ToolProgressInfo, ToolRegistry, ToolResult, ToolResultBlock, ToolResultEvent, ToolUseBlock };

package/dist/index.js

@@ -0,0 +1 @@
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@yolo-labs/core-types",
+  "version": "1.0.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0"
+  },
+  "description": "Shared TypeScript interfaces and type definitions for yolo-core",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yolo-labs-hq/monorepo.git",
+    "directory": "yolo-core/packages/types"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "homepage": "https://github.com/yolo-labs-hq/monorepo/tree/main/yolo-core#readme",
+  "bugs": {
+    "url": "https://github.com/yolo-labs-hq/monorepo/issues"
+  },
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  }
+}