@framers/agentos 0.1.0

package/dist/core/observability/Tracer.js

@@ -0,0 +1,360 @@
+/**
+ * @file Tracer.ts
+ * @description Implementation of distributed tracing for AgentOS.
+ * @module AgentOS/Observability
+ * @version 1.0.0
+ */
+import { v4 as uuidv4 } from 'uuid';
+// ============================================================================
+// Span Implementation
+// ============================================================================
+/**
+ * Span implementation.
+ */
+class Span {
+    constructor(name, context, kind, links, onEnd, startTime) {
+        this.status = 'unset';
+        this.attributes = {};
+        this.events = [];
+        this._isRecording = true;
+        this.name = name;
+        this.context = context;
+        this.kind = kind;
+        this.links = links;
+        this.startTime = startTime || Date.now();
+        this.onEnd = onEnd;
+    }
+    setAttribute(key, value) {
+        if (this._isRecording) {
+            this.attributes[key] = value;
+        }
+    }
+    setAttributes(attributes) {
+        if (this._isRecording) {
+            Object.assign(this.attributes, attributes);
+        }
+    }
+    addEvent(name, attributes) {
+        if (this._isRecording) {
+            this.events.push({
+                name,
+                timestamp: Date.now(),
+                attributes,
+            });
+        }
+    }
+    setStatus(status, message) {
+        if (this._isRecording) {
+            this.status = status;
+            this.statusMessage = message;
+        }
+    }
+    recordException(error) {
+        if (this._isRecording) {
+            this.addEvent('exception', {
+                'exception.type': error.name,
+                'exception.message': error.message,
+                'exception.stacktrace': error.stack || '',
+            });
+            this.setStatus('error', error.message);
+        }
+    }
+    end() {
+        if (this._isRecording) {
+            this.endTime = Date.now();
+            this._isRecording = false;
+            this.onEnd(this);
+        }
+    }
+    isRecording() {
+        return this._isRecording;
+    }
+    toExportedSpan() {
+        return {
+            traceId: this.context.traceId,
+            spanId: this.context.spanId,
+            parentSpanId: this.context.parentSpanId,
+            name: this.name,
+            kind: this.kind,
+            startTime: this.startTime,
+            endTime: this.endTime,
+            status: this.status,
+            statusMessage: this.statusMessage,
+            attributes: { ...this.attributes },
+            events: [...this.events],
+            links: [...this.links],
+        };
+    }
+}
+// ============================================================================
+// Console Exporter
+// ============================================================================
+/**
+ * Simple console exporter for development.
+ */
+export class ConsoleSpanExporter {
+    constructor(prefix = '[Trace]') {
+        this.prefix = prefix;
+    }
+    async export(spans) {
+        for (const span of spans) {
+            const duration = span.endTime ? span.endTime - span.startTime : 'ongoing';
+            const status = span.status === 'error' ? '❌' : span.status === 'ok' ? '✅' : '⚪';
+            console.log(`${this.prefix} ${status} ${span.name} [${span.traceId.slice(0, 8)}:${span.spanId.slice(0, 8)}] ${duration}ms`);
+            if (Object.keys(span.attributes).length > 0) {
+                console.log(`  Attributes:`, span.attributes);
+            }
+            if (span.events.length > 0) {
+                console.log(`  Events:`, span.events.map(e => e.name).join(', '));
+            }
+        }
+    }
+    async shutdown() {
+        // No cleanup needed
+    }
+}
+// ============================================================================
+// In-Memory Exporter (for testing)
+// ============================================================================
+/**
+ * In-memory exporter that stores spans for retrieval.
+ */
+export class InMemorySpanExporter {
+    constructor(maxSpans = 1000) {
+        this.spans = [];
+        this.maxSpans = maxSpans;
+    }
+    async export(spans) {
+        this.spans.push(...spans);
+        // Trim if over limit
+        if (this.spans.length > this.maxSpans) {
+            this.spans = this.spans.slice(-this.maxSpans);
+        }
+    }
+    getSpans() {
+        return [...this.spans];
+    }
+    getSpansByName(name) {
+        return this.spans.filter(s => s.name === name);
+    }
+    getSpansByTraceId(traceId) {
+        return this.spans.filter(s => s.traceId === traceId);
+    }
+    clear() {
+        this.spans = [];
+    }
+    async shutdown() {
+        this.spans = [];
+    }
+}
+const DEFAULT_CONFIG = {
+    name: 'agentos-tracer',
+    autoExport: true,
+    exportBatchSize: 100,
+    exportIntervalMs: 5000,
+    maxBufferSize: 1000,
+};
+/**
+ * Distributed tracer implementation.
+ */
+export class Tracer {
+    constructor(config) {
+        this.activeSpans = new Map();
+        this.completedSpans = [];
+        this.exporters = [];
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.name = this.config.name;
+        this.stats = this.createEmptyStats();
+        if (this.config.autoExport && this.config.exportIntervalMs) {
+            this.startExportTimer();
+        }
+    }
+    getCurrentContext() {
+        return this.currentContext;
+    }
+    startSpan(name, options) {
+        const kind = options?.kind || 'internal';
+        // Generate IDs
+        const spanId = this.generateId(16);
+        let traceId;
+        let parentSpanId;
+        if (options?.parent) {
+            traceId = options.parent.traceId;
+            parentSpanId = options.parent.spanId;
+        }
+        else if (this.currentContext) {
+            traceId = this.currentContext.traceId;
+            parentSpanId = this.currentContext.spanId;
+        }
+        else {
+            traceId = this.generateId(32);
+        }
+        const context = {
+            traceId,
+            spanId,
+            parentSpanId,
+            traceFlags: 1, // Sampled
+        };
+        const span = new Span(name, context, kind, options?.links || [], this.onSpanEnd.bind(this), options?.startTime);
+        if (options?.attributes) {
+            span.setAttributes(options.attributes);
+        }
+        this.activeSpans.set(spanId, span);
+        this.currentContext = context;
+        // Update stats
+        this.stats.totalSpans++;
+        this.stats.activeSpans++;
+        this.stats.spansByName[name] = (this.stats.spansByName[name] || 0) + 1;
+        return span;
+    }
+    async withSpan(name, fn, options) {
+        const span = this.startSpan(name, options);
+        try {
+            const result = await fn(span);
+            span.setStatus('ok');
+            return result;
+        }
+        catch (error) {
+            span.recordException(error);
+            throw error;
+        }
+        finally {
+            span.end();
+        }
+    }
+    inject(carrier) {
+        if (this.currentContext) {
+            carrier['traceparent'] = `00-${this.currentContext.traceId}-${this.currentContext.spanId}-0${this.currentContext.traceFlags}`;
+            if (this.currentContext.baggage) {
+                carrier['baggage'] = Object.entries(this.currentContext.baggage)
+                    .map(([k, v]) => `${k}=${encodeURIComponent(v)}`)
+                    .join(',');
+            }
+        }
+        return carrier;
+    }
+    extract(carrier) {
+        const traceparent = carrier['traceparent'];
+        if (!traceparent)
+            return undefined;
+        const parts = traceparent.split('-');
+        if (parts.length < 4)
+            return undefined;
+        const context = {
+            traceId: parts[1],
+            spanId: parts[2],
+            traceFlags: parseInt(parts[3], 16),
+        };
+        const baggage = carrier['baggage'];
+        if (baggage) {
+            context.baggage = {};
+            baggage.split(',').forEach(item => {
+                const [key, value] = item.split('=');
+                if (key && value) {
+                    context.baggage[key.trim()] = decodeURIComponent(value.trim());
+                }
+            });
+        }
+        return context;
+    }
+    getSpan(spanId) {
+        return this.activeSpans.get(spanId);
+    }
+    getActiveSpans() {
+        return Array.from(this.activeSpans.values());
+    }
+    addExporter(exporter) {
+        this.exporters.push(exporter);
+    }
+    async flush() {
+        if (this.completedSpans.length === 0)
+            return;
+        const spans = this.completedSpans.splice(0);
+        const exported = spans.map(s => s.toExportedSpan());
+        for (const exporter of this.exporters) {
+            try {
+                await exporter.export(exported);
+                this.stats.exportedSpans += exported.length;
+            }
+            catch (error) {
+                console.error('[Tracer] Export failed:', error);
+            }
+        }
+    }
+    getStats() {
+        return { ...this.stats };
+    }
+    resetStats() {
+        this.stats = this.createEmptyStats();
+    }
+    async shutdown() {
+        if (this.exportTimer) {
+            clearInterval(this.exportTimer);
+        }
+        // End all active spans
+        for (const span of this.activeSpans.values()) {
+            span.setStatus('error', 'Tracer shutdown');
+            span.end();
+        }
+        // Final flush
+        await this.flush();
+        // Shutdown exporters
+        for (const exporter of this.exporters) {
+            await exporter.shutdown();
+        }
+    }
+    // ============================================================================
+    // Private Helpers
+    // ============================================================================
+    onSpanEnd(span) {
+        this.activeSpans.delete(span.context.spanId);
+        this.completedSpans.push(span);
+        this.stats.activeSpans--;
+        if (span.status === 'error') {
+            this.stats.errorSpans++;
+        }
+        this.stats.totalEvents += span.events.length;
+        // Update average duration
+        if (span.endTime) {
+            const duration = span.endTime - span.startTime;
+            const totalCompleted = this.stats.totalSpans - this.stats.activeSpans;
+            this.stats.avgDurationMs =
+                (this.stats.avgDurationMs * (totalCompleted - 1) + duration) / totalCompleted;
+        }
+        // Restore parent context
+        if (span.context.parentSpanId) {
+            const parent = this.activeSpans.get(span.context.parentSpanId);
+            if (parent) {
+                this.currentContext = parent.context;
+            }
+        }
+        // Auto-export if batch size reached
+        if (this.config.autoExport &&
+            this.completedSpans.length >= (this.config.exportBatchSize || 100)) {
+            this.flush().catch(console.error);
+        }
+    }
+    startExportTimer() {
+        this.exportTimer = setInterval(() => {
+            if (this.completedSpans.length > 0) {
+                this.flush().catch(console.error);
+            }
+        }, this.config.exportIntervalMs);
+    }
+    generateId(length) {
+        const id = uuidv4().replace(/-/g, '');
+        return id.slice(0, length).padEnd(length, '0');
+    }
+    createEmptyStats() {
+        return {
+            totalSpans: 0,
+            activeSpans: 0,
+            errorSpans: 0,
+            totalEvents: 0,
+            spansByName: {},
+            avgDurationMs: 0,
+            exportedSpans: 0,
+        };
+    }
+}
+//# sourceMappingURL=Tracer.js.map

package/dist/core/observability/Tracer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Tracer.js","sourceRoot":"","sources":["../../../src/core/observability/Tracer.ts"],"names":[],"mappings":"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"}

package/dist/core/observability/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @file Observability Module Index
+ * @description Exports for tracing and observability.
+ * @module AgentOS/Observability
+ */
+export type { ITracer, ISpan, ISpanExporter, TraceContext, SpanOptions, SpanKind, SpanStatus, SpanAttributes, SpanEvent, SpanLink, ExportedSpan, TracerStats, AttributeValue, } from './ITracer';
+export { formatTraceId, SemanticAttributes } from './ITracer';
+export { Tracer, ConsoleSpanExporter, InMemorySpanExporter, type TracerConfig, } from './Tracer';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/observability/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/observability/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,YAAY,EACV,OAAO,EACP,KAAK,EACL,aAAa,EACb,YAAY,EACZ,WAAW,EACX,QAAQ,EACR,UAAU,EACV,cAAc,EACd,SAAS,EACT,QAAQ,EACR,YAAY,EACZ,WAAW,EACX,cAAc,GACf,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAE9D,OAAO,EACL,MAAM,EACN,mBAAmB,EACnB,oBAAoB,EACpB,KAAK,YAAY,GAClB,MAAM,UAAU,CAAC"}

package/dist/core/observability/index.js

@@ -0,0 +1,8 @@
+/**
+ * @file Observability Module Index
+ * @description Exports for tracing and observability.
+ * @module AgentOS/Observability
+ */
+export { formatTraceId, SemanticAttributes } from './ITracer.js';
+export { Tracer, ConsoleSpanExporter, InMemorySpanExporter, } from './Tracer.js';
+//# sourceMappingURL=index.js.map

package/dist/core/observability/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/observability/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAkBH,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAE9D,OAAO,EACL,MAAM,EACN,mBAAmB,EACnB,oBAAoB,GAErB,MAAM,UAAU,CAAC"}

package/dist/core/orchestration/AgentOrchestrator.d.ts

@@ -0,0 +1,243 @@
+/**
+ * @fileoverview Implements the `AgentOSOrchestrator` class, the central nervous system for AgentOS interactions.
+ * This module is responsible for the intricate coordination between the public-facing `AgentOS` API
+ * and the cognitive core, the `GMI` (Generalized Mind Instance). It meticulously manages the
+ * entire lifecycle of an interaction turn.
+ *
+ * Key Responsibilities:
+ * - **GMI Instance Management**: Selection/creation of GMI instances via `GMIManager`.
+ * - **Contextualization**: Preparation and loading of `ConversationContext`.
+ * - **Input Processing**: Transformation of `AgentOSInput` into `GMITurnInput`.
+ * - **Streaming Output Handling**: Iteration over `GMIOutputChunk` streams from the GMI.
+ * - **Tool Use Coordination**:
+ * - Relaying `ToolCallRequest`s to the client (via `StreamingManager`).
+ * - Receiving tool execution results.
+ * - Forwarding tool results back to the GMI via `handleToolResult`.
+ * - Processing the GMI's response (`GMIOutput`) post-tool execution.
+ * - **Response Streaming**: Conversion of GMI outputs into `AgentOSResponse` chunks and their
+ * distribution through the `StreamingManager`.
+ * - **State Management**: Tracking active interaction streams and their associated contexts.
+ * - **Error Handling**: Robust error management for orchestration failures.
+ *
+ * The orchestrator embodies asynchronous processing and streaming, ensuring a responsive user experience.
+ * It relies on dependency injection for its core components, promoting modularity and testability.
+ *
+ * @module backend/agentos/core/orchestration/AgentOSOrchestrator
+ */
+import { AgentOSInput } from '../../api/types/AgentOSInput';
+import { GMIManager } from '../../cognitive_substrate/GMIManager';
+import { ConversationManager } from '../conversation/ConversationManager';
+import { ToolOrchestrator as ConcreteToolOrchestrator } from '../tools/ToolOrchestrator';
+import { StreamingManager, StreamId } from '../streaming/StreamingManager';
+/**
+ * Configuration options for the AgentOSOrchestrator.
+ * These settings govern the behavior and limits of the orchestration process.
+ * @interface AgentOSOrchestratorConfig
+ */
+export interface AgentOSOrchestratorConfig {
+    /**
+     * The maximum number of sequential tool call iterations allowed within a single logical turn.
+     * This prevents potential infinite loops if GMIs repeatedly call tools without resolution.
+     * @type {number}
+     * @default 5
+     */
+    maxToolCallIterations?: number;
+    /**
+     * Default timeout in milliseconds for a single GMI processing step
+     * (e.g., initial turn or processing after a tool result).
+     * Note: Actual timeout implementation might reside within the GMI or LLM provider layer.
+     * @type {number}
+     * @default 120000 (2 minutes)
+     */
+    defaultAgentTurnTimeoutMs?: number;
+    /**
+     * If true, conversation context will be persistently saved and loaded by the `ConversationManager`.
+     * If false, conversations are primarily in-memory, and their persistence depends on the
+     * `ConversationManager`'s specific configuration.
+     * @type {boolean}
+     * @default true
+     */
+    enableConversationalPersistence?: boolean;
+    /** If true, orchestrator logs detailed information about tool calls. */
+    logToolCalls?: boolean;
+}
+/**
+ * Defines the dependencies required by the AgentOSOrchestrator for its operation.
+ * These services are typically injected during the orchestrator's initialization phase,
+ * adhering to the Dependency Inversion Principle.
+ * @interface AgentOSOrchestratorDependencies
+ */
+export interface AgentOSOrchestratorDependencies {
+    /** An instance of GMIManager for managing GMI instances and persona definitions. */
+    gmiManager: GMIManager;
+    /** An instance of ToolOrchestrator for orchestrating the execution of tools. */
+    toolOrchestrator: ConcreteToolOrchestrator;
+    /** An instance of ConversationManager for managing conversation contexts. */
+    conversationManager: ConversationManager;
+    /** An instance of StreamingManager for managing streaming responses to clients. */
+    streamingManager: StreamingManager;
+}
+/**
+ * @class AgentOSOrchestrator
+ * @classdesc
+ * The `AgentOSOrchestrator` serves as the master conductor of interactions within the AgentOS platform.
+ * It is the critical intermediary layer that bridges high-level API requests (`AgentOSInput`)
+ * with the sophisticated cognitive processing of Generalized Mind Instances (`IGMI`).
+ * Its primary function is to manage the entire lifecycle of a user's interaction turn, a potentially
+ * complex, multi-step process.
+ */
+export declare class AgentOSOrchestrator {
+    private initialized;
+    private config;
+    private dependencies;
+    /**
+     * Stores the context for active, ongoing interaction streams.
+     * The key is the `agentOSStreamId` generated by this orchestrator.
+     * @private
+     * @type {Map<StreamId, ActiveStreamContext>}
+     */
+    private readonly activeStreamContexts;
+    /**
+     * Constructs an AgentOSOrchestrator instance.
+     * The orchestrator is not operational until `initialize()` is successfully called.
+     */
+    constructor();
+    /**
+     * Initializes the AgentOSOrchestrator with its configuration and essential service dependencies.
+     * This method must be called and resolve successfully before the orchestrator can process any requests.
+     * It sets up the orchestrator's internal state and validates its dependencies.
+     *
+     * @public
+     * @async
+     * @param {AgentOSOrchestratorConfig} config - Configuration settings for the orchestrator.
+     * @param {AgentOSOrchestratorDependencies} dependencies - An object containing instances of required services.
+     * @returns {Promise<void>} A Promise that resolves when initialization is complete.
+     * @throws {GMIError} If critical dependencies are missing (GMIErrorCode.CONFIGURATION_ERROR).
+     */
+    initialize(config: AgentOSOrchestratorConfig, dependencies: AgentOSOrchestratorDependencies): Promise<void>;
+    /**
+     * Ensures that the orchestrator has been initialized before performing operations.
+     * @private
+     * @throws {GMIError} If the orchestrator is not initialized (GMIErrorCode.NOT_INITIALIZED).
+     */
+    private ensureInitialized;
+    /**
+     * Pushes a response chunk to the client via the StreamingManager.
+     * This is a centralized helper for all chunk types.
+     * @private
+     * @param {StreamId} agentOSStreamId - The unique ID of the AgentOS stream.
+     * @param {AgentOSResponseChunkType} type - The type of chunk being pushed.
+     * @param {string} gmiInstanceId - The ID of the GMI instance generating this chunk.
+     * @param {string} personaId - The ID of the persona active during this chunk's generation.
+     * @param {boolean} isFinal - Whether this chunk marks the end of the response for this stream.
+     * @param {any} data - The specific payload data for the chunk, varying by `type`.
+     * @returns {Promise<void>}
+     */
+    private pushChunkToStream;
+    /**
+     * Pushes a standardized error chunk to the client.
+     * @private
+     * @param {StreamId} agentOSStreamId - The ID of the AgentOS stream.
+     * @param {string} personaId - The ID of the persona associated with this error.
+     * @param {string} [gmiInstanceId='unknown_gmi_instance'] - The ID of the GMI instance.
+     * @param {GMIErrorCode | string} code - The error code.
+     * @param {string} message - The error message.
+     * @param {any} [details] - Additional error details.
+     * @returns {Promise<void>}
+     */
+    private pushErrorChunk;
+    /**
+     * Orchestrates a complete user interaction turn, starting from an `AgentOSInput`.
+     * This method initiates a new stream for the interaction via `StreamingManager`,
+     * then delegates the complex, potentially long-running processing to `_processTurnInternal`
+     * without awaiting its completion. This allows `orchestrateTurn` to return the `StreamId`
+     * to the caller (e.g., `AgentOS` facade) immediately, enabling clients to subscribe to the
+     * stream for real-time updates.
+     *
+     * @public
+     * @async
+     * @param {AgentOSInput} input - The comprehensive input for the current turn from the API layer.
+     * @returns {Promise<StreamId>} The unique ID of the stream established for this interaction.
+     * Clients should use this ID to listen for `AgentOSResponse` chunks.
+     * @throws {GMIError} If the `StreamingManager` fails to create a new stream (e.g., `GMIErrorCode.STREAM_ERROR`).
+     */
+    orchestrateTurn(input: AgentOSInput): Promise<StreamId>;
+    /**
+     * Constructs a `GMITurnInput` object from the API-level `AgentOSInput`.
+     * This method maps and transforms data to the structure expected by the `IGMI`.
+     *
+     * @private
+     * @param {StreamId} agentOSStreamId - The orchestrator-level stream ID, used to generate a GMI interaction ID.
+     * @param {AgentOSInput} agentOSInput - The input received from the AgentOS API layer.
+     * @param {string} activePersonaId - The definitive ID of the persona resolved for this turn. Guaranteed to be a string by caller.
+     * @returns {GMITurnInput} The structured input object ready for the GMI.
+     */
+    private constructGMITurnInput;
+    /**
+     * Core internal turn processing logic. This method is executed asynchronously by `orchestrateTurn`.
+     * It manages the GMI interaction loop, including streaming chunks, handling tool call requests,
+     * and ensuring finalization of the stream.
+     *
+     * @private
+     * @async
+     * @param {StreamId} agentOSStreamId - The unique ID for this AgentOS-level stream.
+     * @param {AgentOSInput} input - The initial input for this turn.
+     * @returns {Promise<void>} Resolves when processing for this turn is complete or a terminal error occurs.
+     */
+    private _processTurnInternal;
+    /**
+     * Handles the result of an externally executed tool, feeding it back into the active GMI instance.
+     * It then processes the GMI's subsequent output (`GMIOutput`), streaming further responses or
+     * new tool requests as needed.
+     *
+     * @public
+     * @async
+     * @param {StreamId} agentOSStreamId - The orchestrator-level stream ID for this interaction flow.
+     * @param {string} toolCallId - The ID of the specific tool call (from `ToolCallRequest`) whose result is being provided.
+     * @param {string} toolName - The name of the tool that was executed.
+     * @param {any} toolOutput - The output data returned by the tool execution.
+     * @param {boolean} isSuccess - A flag indicating whether the tool execution was successful.
+     * @param {string} [errorMessage] - An optional error message if `isSuccess` is false.
+     * @returns {Promise<void>} Resolves when the tool result has been processed and subsequent GMI output streamed.
+     * @throws {GMIError} If the `agentOSStreamId` is not found or if a critical error occurs during GMI's handling of the tool result.
+     */
+    orchestrateToolResult(agentOSStreamId: StreamId, toolCallId: string, toolName: string, toolOutput: any, isSuccess: boolean, errorMessage?: string): Promise<void>;
+    /**
+     * Processes a direct `GMIOutput` object (typically the result of `gmi.handleToolResult` or the
+     * final return value of `gmi.processTurnStream`). It transforms and pushes the relevant
+     * parts of this `GMIOutput` as `AgentOSResponse` chunks to the client stream.
+     *
+     * @private
+     * @async
+     * @param {StreamId} agentOSStreamId - The ID of the AgentOS stream.
+     * @param {ActiveStreamContext} streamContext - The context for the current active stream.
+     * @param {GMIOutput} gmiOutput - The GMI output object to process.
+     * @param {boolean} isContinuationAfterTool - Indicates if this output is a direct result of processing a tool.
+     * @returns {Promise<void>}
+     */
+    private processGMIOutput;
+    /**
+     * Transforms a single `GMIOutputChunk` from the GMI's stream into one or more
+     * `AgentOSResponse` chunks and pushes them to the client via the `StreamingManager`.
+     *
+     * @private
+     * @async
+     * @param {StreamId} agentOSStreamId - The ID of the AgentOS stream.
+     * @param {ActiveStreamContext} streamContext - The context for the current active stream.
+     * @param {GMIOutputChunk} gmiChunk - The chunk of output received from the GMI.
+     * @returns {Promise<void>}
+     */
+    private transformAndPushGMIChunk;
+    /**
+     * Gracefully shuts down the AgentOSOrchestrator.
+     * This involves notifying and closing any active streams managed by the associated `StreamingManager`
+     * and clearing internal state. Dependencies like `GMIManager` are assumed to be shut down
+     * by the main `AgentOS` service.
+     *
+     * @public
+     * @async
+     * @returns {Promise<void>} A promise that resolves when the shutdown process is complete.
+     */
+    shutdown(): Promise<void>;
+}
+//# sourceMappingURL=AgentOrchestrator.d.ts.map

package/dist/core/orchestration/AgentOrchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentOrchestrator.d.ts","sourceRoot":"","sources":["../../../src/core/orchestration/AgentOrchestrator.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,YAAY,EAAqB,MAAM,8BAA8B,CAAC;AAe/E,OAAO,EAAE,UAAU,EAAE,MAAM,sCAAsC,CAAC;AAclE,OAAO,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAE1E,OAAO,EAAE,gBAAgB,IAAI,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAMzF,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAG3E;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;;;OAKG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAE/B;;;;;;OAMG;IACH,yBAAyB,CAAC,EAAE,MAAM,CAAC;IAEnC;;;;;;OAMG;IACH,+BAA+B,CAAC,EAAE,OAAO,CAAC;IAC1C,wEAAwE;IACxE,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;GAKG;AACH,MAAM,WAAW,+BAA+B;IAC9C,oFAAoF;IACpF,UAAU,EAAE,UAAU,CAAC;IACvB,gFAAgF;IAChF,gBAAgB,EAAE,wBAAwB,CAAC;IAC3C,6EAA6E;IAC7E,mBAAmB,EAAE,mBAAmB,CAAC;IACzC,mFAAmF;IACnF,gBAAgB,EAAE,gBAAgB,CAAC;CACpC;AA2BD;;;;;;;;GAQG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,WAAW,CAAkB;IACrC,OAAO,CAAC,MAAM,CAAiD;IAC/D,OAAO,CAAC,YAAY,CAA6C;IAEjE;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAqC;IAE1E;;;OAGG;;IAKH;;;;;;;;;;;OAWG;IACU,UAAU,CACrB,MAAM,EAAE,yBAAyB,EACjC,YAAY,EAAE,+BAA+B,GAC5C,OAAO,CAAC,IAAI,CAAC;IA+BhB;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAUzB;;;;;;;;;;;OAWG;YACW,iBAAiB;IA2E/B;;;;;;;;;;OAUG;YACW,cAAc;IAe5B;;;;;;;;;;;;;;OAcG;IACU,eAAe,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,QAAQ,CAAC;IAgCpE;;;;;;;;;OASG;IACH,OAAO,CAAC,qBAAqB;IAyD7B;;;;;;;;;;OAUG;YACW,oBAAoB;IAyHlC;;;;;;;;;;;;;;;OAeG;IACU,qBAAqB,CAChC,eAAe,EAAE,QAAQ,EACzB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,GAAG,EACf,SAAS,EAAE,OAAO,EAClB,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,IAAI,CAAC;IAyDhB;;;;;;;;;;;;OAYG;YACW,gBAAgB;IA+E9B;;;;;;;;;;OAUG;YACW,wBAAwB;IAmGtC;;;;;;;;;OASG;IACU,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CA2BvC"}