@mast-ai/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/** Current version of the `@mast-ai/core` package. */
+export declare const VERSION = "0.1.0";
+export * from './types';
+export * from './error';
+export * from './tool';
+export * from './agent';
+export * from './agentTool';
+export * from './runner';
+export * from './conversation';
+export * from './adapter/index';
+export * from './adapter/urp';
+export * from './transport/http';

package/dist/index.js

@@ -0,0 +1,14 @@
+// Copyright 2026 Andre Cipriani Bandarra
+// SPDX-License-Identifier: Apache-2.0
+/** Current version of the `@mast-ai/core` package. */
+export const VERSION = '0.1.0';
+export * from './types';
+export * from './error';
+export * from './tool';
+export * from './agent';
+export * from './agentTool';
+export * from './runner';
+export * from './conversation';
+export * from './adapter/index';
+export * from './adapter/urp';
+export * from './transport/http';

package/dist/runner.d.ts

@@ -0,0 +1,74 @@
+import type { AgentConfig, AgentEvent, AgentResult, Message } from './types';
+import type { LlmAdapter } from './adapter/index';
+import { type ToolProvider } from './tool';
+import { Conversation } from './conversation';
+type StreamExecutor = (input: string, history: Message[], signal?: AbortSignal, onToolEvent?: (toolName: string, event: AgentEvent) => void) => AsyncIterable<AgentEvent>;
+/**
+ * Fluent builder for a single agent run.
+ *
+ * Obtain an instance from {@link AgentRunner.runBuilder} rather than
+ * constructing one directly.
+ */
+export declare class RunBuilder {
+    private readonly agent;
+    private readonly execute;
+    private _history;
+    private _signal?;
+    private _onToolEvent?;
+    constructor(agent: AgentConfig, execute: StreamExecutor);
+    /** Prepend prior conversation turns. */
+    history(messages: Message[]): this;
+    /** Attach an AbortSignal to cancel the run and any in-flight tool calls. */
+    signal(signal: AbortSignal): this;
+    /**
+     * Register a callback that receives events emitted by tools running
+     * sub-agents. `toolName` identifies which tool fired the event.
+     * Note: convenience methods on {@link AgentRunner} do not surface tool
+     * events — use `runBuilder().onToolEvent(...).runStream()` for that.
+     */
+    onToolEvent(handler: (toolName: string, event: AgentEvent) => void): this;
+    /** Executes the run and returns a stream of {@link AgentEvent} objects. */
+    runStream(input: string): AsyncIterable<AgentEvent>;
+    /** Executes the run and returns the final text output. */
+    run(input: string): Promise<AgentResult>;
+    /**
+     * Executes the run and parses the final output as JSON into `T`.
+     *
+     * Throws {@link AgentError} if the output cannot be parsed.
+     */
+    runTyped<T>(input: string): Promise<T>;
+}
+/**
+ * Core execution engine that drives the agent agentic loop.
+ *
+ * Pair an {@link LlmAdapter} with a {@link ToolRegistry} and use
+ * {@link AgentRunner.runBuilder} (multi-turn) or the convenience methods
+ * {@link AgentRunner.run} / {@link AgentRunner.runStream} (single-turn).
+ */
+export declare class AgentRunner {
+    /** The LLM adapter used to generate responses. */
+    readonly adapter: LlmAdapter;
+    /** Provider of tools the runner may invoke on behalf of agents. */
+    readonly registry: ToolProvider;
+    constructor(
+    /** The LLM adapter used to generate responses. */
+    adapter: LlmAdapter, 
+    /** Provider of tools the runner may invoke on behalf of agents. */
+    registry?: ToolProvider);
+    /** Creates a Conversation that automatically tracks history across turns. */
+    conversation(agent: AgentConfig): Conversation;
+    /** Primary entry point for multi-turn use. */
+    runBuilder(agent: AgentConfig): RunBuilder;
+    /** Single-turn convenience methods (delegate to runBuilder). */
+    runStream(agent: AgentConfig, input: string): AsyncIterable<AgentEvent>;
+    /** Single-turn convenience method — runs the agent and returns the final text output. */
+    run(agent: AgentConfig, input: string): Promise<AgentResult>;
+    /**
+     * Single-turn convenience method — runs the agent and parses the output as JSON into `T`.
+     *
+     * Throws {@link AgentError} if parsing fails.
+     */
+    runTyped<T>(agent: AgentConfig, input: string): Promise<T>;
+    private executeStream;
+}
+export {};

package/dist/runner.js

@@ -0,0 +1,216 @@
+// Copyright 2026 Andre Cipriani Bandarra
+// SPDX-License-Identifier: Apache-2.0
+import { ToolRegistry } from './tool';
+import { AgentError } from './error';
+import { Conversation } from './conversation';
+/**
+ * Fluent builder for a single agent run.
+ *
+ * Obtain an instance from {@link AgentRunner.runBuilder} rather than
+ * constructing one directly.
+ */
+export class RunBuilder {
+    agent;
+    execute;
+    _history = [];
+    _signal;
+    _onToolEvent;
+    constructor(agent, execute) {
+        this.agent = agent;
+        this.execute = execute;
+    }
+    /** Prepend prior conversation turns. */
+    history(messages) {
+        this._history = [...messages];
+        return this;
+    }
+    /** Attach an AbortSignal to cancel the run and any in-flight tool calls. */
+    signal(signal) {
+        this._signal = signal;
+        return this;
+    }
+    /**
+     * Register a callback that receives events emitted by tools running
+     * sub-agents. `toolName` identifies which tool fired the event.
+     * Note: convenience methods on {@link AgentRunner} do not surface tool
+     * events — use `runBuilder().onToolEvent(...).runStream()` for that.
+     */
+    onToolEvent(handler) {
+        this._onToolEvent = handler;
+        return this;
+    }
+    /** Executes the run and returns a stream of {@link AgentEvent} objects. */
+    runStream(input) {
+        return this.execute(input, this._history, this._signal, this._onToolEvent);
+    }
+    /** Executes the run and returns the final text output. */
+    async run(input) {
+        let output = '';
+        for await (const event of this.runStream(input)) {
+            if (event.type === 'text_delta') {
+                output += event.delta;
+            }
+        }
+        return { output };
+    }
+    /**
+     * Executes the run and parses the final output as JSON into `T`.
+     *
+     * Throws {@link AgentError} if the output cannot be parsed.
+     */
+    async runTyped(input) {
+        const result = await this.run(input);
+        try {
+            return JSON.parse(result.output);
+        }
+        catch (err) {
+            throw new AgentError('Failed to parse structured output', err);
+        }
+    }
+}
+/**
+ * Core execution engine that drives the agent agentic loop.
+ *
+ * Pair an {@link LlmAdapter} with a {@link ToolRegistry} and use
+ * {@link AgentRunner.runBuilder} (multi-turn) or the convenience methods
+ * {@link AgentRunner.run} / {@link AgentRunner.runStream} (single-turn).
+ */
+export class AgentRunner {
+    adapter;
+    registry;
+    constructor(
+    /** The LLM adapter used to generate responses. */
+    adapter, 
+    /** Provider of tools the runner may invoke on behalf of agents. */
+    registry = new ToolRegistry()) {
+        this.adapter = adapter;
+        this.registry = registry;
+    }
+    /** Creates a Conversation that automatically tracks history across turns. */
+    conversation(agent) {
+        return new Conversation(this, agent);
+    }
+    /** Primary entry point for multi-turn use. */
+    runBuilder(agent) {
+        return new RunBuilder(agent, (input, history, signal, onToolEvent) => this.executeStream(agent, input, history, signal, onToolEvent));
+    }
+    /** Single-turn convenience methods (delegate to runBuilder). */
+    runStream(agent, input) {
+        return this.runBuilder(agent).runStream(input);
+    }
+    /** Single-turn convenience method — runs the agent and returns the final text output. */
+    run(agent, input) {
+        return this.runBuilder(agent).run(input);
+    }
+    /**
+     * Single-turn convenience method — runs the agent and parses the output as JSON into `T`.
+     *
+     * Throws {@link AgentError} if parsing fails.
+     */
+    runTyped(agent, input) {
+        return this.runBuilder(agent).runTyped(input);
+    }
+    async *executeStream(agent, input, history, signal, onToolEvent) {
+        // Use the explicit tool list when provided; otherwise expose all registered tools.
+        const toolDefinitions = agent.tools
+            ? agent.tools.map((toolName) => {
+                const tool = this.registry.getTool(toolName);
+                if (!tool) {
+                    throw new AgentError(`Tool '${toolName}' requested by agent '${agent.name}' is not registered.`);
+                }
+                return tool.definition();
+            })
+            : this.registry.getTools();
+        // Clone history and add new user message
+        const currentHistory = [
+            ...history,
+            { role: 'user', content: { type: 'text', text: input } },
+        ];
+        while (true) {
+            if (signal?.aborted) {
+                throw new AgentError('Run aborted', signal.reason);
+            }
+            const request = {
+                system: agent.instructions,
+                messages: currentHistory,
+                tools: toolDefinitions,
+                outputSchema: agent.outputSchema,
+                signal,
+            };
+            let finalOutput = '';
+            const toolCalls = [];
+            if (this.adapter.generateStream) {
+                const stream = this.adapter.generateStream(request);
+                for await (const chunk of stream) {
+                    if (signal?.aborted) {
+                        throw new AgentError('Run aborted', signal.reason);
+                    }
+                    if (chunk.type === 'text_delta') {
+                        finalOutput += chunk.delta;
+                        yield { type: 'text_delta', delta: chunk.delta };
+                    }
+                    else if (chunk.type === 'thinking') {
+                        yield { type: 'thinking', delta: chunk.delta };
+                    }
+                    else if (chunk.type === 'tool_call') {
+                        toolCalls.push(chunk.toolCall);
+                    }
+                }
+            }
+            else {
+                const response = await this.adapter.generate(request);
+                if (response.text) {
+                    finalOutput = response.text;
+                    yield { type: 'text_delta', delta: finalOutput };
+                }
+                if (response.toolCalls) {
+                    toolCalls.push(...response.toolCalls);
+                }
+            }
+            if (toolCalls.length > 0) {
+                for (const call of toolCalls) {
+                    yield { type: 'tool_call_started', name: call.name, args: call.args };
+                }
+                const toolResults = await Promise.all(toolCalls.map(async (call) => {
+                    const tool = this.registry.getTool(call.name);
+                    if (!tool) {
+                        return {
+                            call,
+                            result: `Error: Tool '${call.name}' not found.`,
+                            error: true,
+                        };
+                    }
+                    try {
+                        const result = await tool.call(call.args, {
+                            signal,
+                            onEvent: onToolEvent ? (event) => onToolEvent(call.name, event) : undefined,
+                        });
+                        return { call, result, error: false };
+                    }
+                    catch (err) {
+                        const message = err instanceof Error ? err.message : String(err);
+                        return { call, result: `Error executing tool: ${message}`, error: true };
+                    }
+                }));
+                const resultMessages = [];
+                for (const { call, result, error } of toolResults) {
+                    yield { type: 'tool_call_completed', name: call.name, result, error };
+                    resultMessages.push({
+                        role: 'user',
+                        content: { type: 'tool_result', id: call.id, name: call.name, result },
+                    });
+                }
+                // Assistant tool_calls message must precede tool result messages in history.
+                currentHistory.push({
+                    role: 'assistant',
+                    content: { type: 'tool_calls', calls: toolCalls },
+                });
+                currentHistory.push(...resultMessages);
+                continue;
+            }
+            currentHistory.push({ role: 'assistant', content: { type: 'text', text: finalOutput } });
+            yield { type: 'done', output: finalOutput, history: currentHistory };
+            return;
+        }
+    }
+}

package/dist/tool.d.ts

@@ -0,0 +1,77 @@
+import type { AgentEvent } from './types';
+/** Static description of a tool that is sent to the model so it can decide when to call it. */
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    /** JSON Schema object describing the tool's arguments. */
+    parameters: Record<string, unknown>;
+    /** Whether the tool reads or modifies state. Used for scope-based filtering. */
+    scope: 'read' | 'write';
+    /** When true, the tool author declares this tool is sensitive and requires human confirmation before executing. */
+    requiresApproval?: boolean;
+}
+/** Runtime context passed to every {@link Tool.call} invocation. */
+export interface ToolContext {
+    /** Forwarded from the runner; allows long-running tools to be cancelled. */
+    signal?: AbortSignal;
+    /**
+     * Called by tools that internally run sub-agents to surface child events to
+     * the parent runner's consumer. Simple tools can ignore this entirely.
+     * Tools should filter out {@link AgentEvent} `done` events before forwarding
+     * to avoid leaking child conversation history to the parent's consumers.
+     */
+    onEvent?: (event: AgentEvent) => void;
+}
+/**
+ * A callable tool that can be registered with a {@link ToolRegistry}.
+ *
+ * @typeParam TArgs - Shape of the arguments object the model passes to `call`.
+ * @typeParam TResult - Value returned by `call` and forwarded to the model as the tool result.
+ */
+export interface Tool<TArgs = unknown, TResult = unknown> {
+    /** Returns the static description used to advertise this tool to the model. */
+    definition(): ToolDefinition;
+    /** Executes the tool with the given arguments. */
+    call(args: TArgs, context: ToolContext): Promise<TResult>;
+}
+/**
+ * Read-only interface for accessing tool definitions and resolving tools by name.
+ * Passed to {@link AgentRunner} so that scope-based filtering is handled by the
+ * provider rather than the runner.
+ */
+export interface ToolProvider {
+    /** Returns the definitions of all accessible tools. */
+    getTools(): ToolDefinition[];
+    /** Returns the tool registered under `name`, or `undefined` if not found or out of scope. */
+    getTool(name: string): Tool | undefined;
+}
+/** Holds all tools available to an {@link AgentRunner} and resolves them by name during execution. */
+export declare class ToolRegistry implements ToolProvider {
+    private _tools;
+    /**
+     * Registers a tool. Throws if a tool with the same name is already registered.
+     * Returns `this` for chaining.
+     */
+    register(tool: Tool): this;
+    /** Removes the tool registered under `name`. No-op if not found. */
+    unregister(name: string): void;
+    /** Returns the tool registered under `name`, or `undefined` if not found. */
+    getTool(name: string): Tool | undefined;
+    /** Returns the definitions of all registered tools for inclusion in an adapter request. */
+    getTools(): ToolDefinition[];
+    /** Returns a live read-only view filtered to tools with `scope: 'read'`. */
+    readOnly(): ToolRegistryView;
+}
+/**
+ * A live filtered projection of a {@link ToolRegistry}.
+ *
+ * Changes to the parent registry are automatically reflected — no copy is made.
+ * Only tools whose `scope` matches the view's scope are visible.
+ */
+export declare class ToolRegistryView implements ToolProvider {
+    private readonly parent;
+    private readonly scope;
+    constructor(parent: ToolRegistry, scope: 'read' | 'write');
+    getTools(): ToolDefinition[];
+    getTool(name: string): Tool | undefined;
+}

package/dist/tool.js

@@ -0,0 +1,57 @@
+// Copyright 2026 Andre Cipriani Bandarra
+// SPDX-License-Identifier: Apache-2.0
+/** Holds all tools available to an {@link AgentRunner} and resolves them by name during execution. */
+export class ToolRegistry {
+    _tools = new Map();
+    /**
+     * Registers a tool. Throws if a tool with the same name is already registered.
+     * Returns `this` for chaining.
+     */
+    register(tool) {
+        const name = tool.definition().name;
+        if (this._tools.has(name)) {
+            throw new Error(`Tool '${name}' is already registered.`);
+        }
+        this._tools.set(name, tool);
+        return this;
+    }
+    /** Removes the tool registered under `name`. No-op if not found. */
+    unregister(name) {
+        this._tools.delete(name);
+    }
+    /** Returns the tool registered under `name`, or `undefined` if not found. */
+    getTool(name) {
+        return this._tools.get(name);
+    }
+    /** Returns the definitions of all registered tools for inclusion in an adapter request. */
+    getTools() {
+        return Array.from(this._tools.values()).map((t) => t.definition());
+    }
+    /** Returns a live read-only view filtered to tools with `scope: 'read'`. */
+    readOnly() {
+        return new ToolRegistryView(this, 'read');
+    }
+}
+/**
+ * A live filtered projection of a {@link ToolRegistry}.
+ *
+ * Changes to the parent registry are automatically reflected — no copy is made.
+ * Only tools whose `scope` matches the view's scope are visible.
+ */
+export class ToolRegistryView {
+    parent;
+    scope;
+    constructor(parent, scope) {
+        this.parent = parent;
+        this.scope = scope;
+    }
+    getTools() {
+        return this.parent.getTools().filter((def) => def.scope === this.scope);
+    }
+    getTool(name) {
+        const tool = this.parent.getTool(name);
+        if (!tool)
+            return undefined;
+        return tool.definition().scope === this.scope ? tool : undefined;
+    }
+}

package/dist/transport/http.d.ts

@@ -0,0 +1,21 @@
+import type { UrpRequest, UrpResponse, UrpTransport, UrpStreamChunk } from '../adapter/urp';
+/** Configuration for {@link HttpTransport}. */
+export interface HttpTransportOptions {
+    /** Endpoint URL that accepts URP-formatted POST requests. */
+    url: string;
+    /** Additional headers merged into every request (e.g. `Authorization`). */
+    headers?: Record<string, string>;
+}
+/**
+ * {@link UrpTransport} implementation that sends URP requests over HTTP/HTTPS.
+ *
+ * Supports both non-streaming (JSON) and streaming (NDJSON / SSE) responses.
+ */
+export declare class HttpTransport implements UrpTransport {
+    private options;
+    constructor(options: HttpTransportOptions);
+    /** {@inheritDoc UrpTransport.send} */
+    send(request: UrpRequest, signal?: AbortSignal): Promise<UrpResponse>;
+    /** {@inheritDoc UrpTransport.sendStream} */
+    sendStream(request: UrpRequest, signal?: AbortSignal): AsyncIterable<UrpStreamChunk>;
+}

package/dist/transport/http.js

@@ -0,0 +1,108 @@
+// Copyright 2026 Andre Cipriani Bandarra
+// SPDX-License-Identifier: Apache-2.0
+import { AdapterError } from '../error';
+/**
+ * {@link UrpTransport} implementation that sends URP requests over HTTP/HTTPS.
+ *
+ * Supports both non-streaming (JSON) and streaming (NDJSON / SSE) responses.
+ */
+export class HttpTransport {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    /** {@inheritDoc UrpTransport.send} */
+    async send(request, signal) {
+        try {
+            const response = await fetch(this.options.url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...(this.options.headers || {}),
+                },
+                body: JSON.stringify(request),
+                signal,
+            });
+            if (!response.ok) {
+                throw new AdapterError(`HTTP request failed with status ${response.status}`, response.status);
+            }
+            const data = await response.json();
+            return data;
+        }
+        catch (error) {
+            if (error instanceof AdapterError) {
+                throw error;
+            }
+            throw new AdapterError(`Failed to send request: ${error instanceof Error ? error.message : String(error)}`, undefined, error);
+        }
+    }
+    /** {@inheritDoc UrpTransport.sendStream} */
+    async *sendStream(request, signal) {
+        let response;
+        try {
+            response = await fetch(this.options.url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Accept: 'text/event-stream, application/x-ndjson, application/json',
+                    ...(this.options.headers || {}),
+                },
+                body: JSON.stringify({ ...request, stream: true }),
+                signal,
+            });
+        }
+        catch (error) {
+            throw new AdapterError(`Failed to send streaming request: ${error instanceof Error ? error.message : String(error)}`, undefined, error);
+        }
+        if (!response.ok) {
+            throw new AdapterError(`HTTP streaming request failed with status ${response.status}`, response.status);
+        }
+        if (!response.body) {
+            throw new AdapterError('Response body is empty');
+        }
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                const lines = buffer.split('\n');
+                buffer = lines.pop() || '';
+                for (const line of lines) {
+                    const trimmed = line.trim();
+                    if (!trimmed)
+                        continue;
+                    // Support both simple NDJSON and SSE (data: ...)
+                    const jsonStr = trimmed.startsWith('data: ') ? trimmed.slice(6) : trimmed;
+                    if (jsonStr === '[DONE]')
+                        continue;
+                    try {
+                        yield JSON.parse(jsonStr);
+                    }
+                    catch (e) {
+                        throw new AdapterError(`Failed to parse URP stream chunk: ${jsonStr}`, undefined, e);
+                    }
+                }
+            }
+            // Handle remaining buffer
+            if (buffer.trim()) {
+                const trimmed = buffer.trim();
+                const jsonStr = trimmed.startsWith('data: ') ? trimmed.slice(6) : trimmed;
+                if (jsonStr !== '[DONE]') {
+                    try {
+                        yield JSON.parse(jsonStr);
+                    }
+                    catch (e) {
+                        throw new AdapterError(`Failed to parse URP stream chunk: ${jsonStr}`, undefined, e);
+                    }
+                }
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Represents the role of a message sender.
+ */
+export type Role = 'user' | 'assistant';
+/**
+ * A single tool call issued by the assistant.
+ */
+export interface ToolCall {
+    id: string;
+    name: string;
+    args: unknown;
+}
+/**
+ * Discriminated union of possible message content types.
+ */
+export type MessageContent = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'tool_calls';
+    calls: ToolCall[];
+} | {
+    type: 'tool_result';
+    id: string;
+    name: string;
+    result: unknown;
+};
+/**
+ * A single message in a conversation history.
+ */
+export interface Message {
+    role: Role;
+    content: MessageContent;
+}
+/**
+ * Events emitted by the AgentRunner during execution.
+ */
+export type AgentEvent = {
+    type: 'tool_call_started';
+    name: string;
+    args: unknown;
+} | {
+    type: 'tool_call_completed';
+    name: string;
+    result: unknown;
+    error?: boolean;
+} | {
+    type: 'text_delta';
+    delta: string;
+} | {
+    type: 'thinking';
+    delta: string;
+} | {
+    type: 'done';
+    output: string;
+    history: Message[];
+};
+/**
+ * Pure data blueprint for an agent.
+ */
+export interface AgentConfig {
+    name: string;
+    instructions: string;
+    tools?: string[];
+    outputSchema?: Record<string, unknown>;
+}
+/**
+ * The final result of an agent run.
+ */
+export interface AgentResult {
+    output: string;
+}

package/dist/types.js

@@ -0,0 +1,3 @@
+// Copyright 2026 Andre Cipriani Bandarra
+// SPDX-License-Identifier: Apache-2.0
+export {};