@framers/agentos 0.1.0

package/dist/core/tools/permissions/ToolPermissionManager.js

@@ -0,0 +1,298 @@
+// File: backend/agentos/core/tools/permissions/ToolPermissionManager.ts
+/**
+ * @file ToolPermissionManager.ts
+ * @module backend/agentos/core/tools/permissions/ToolPermissionManager
+ * @version 1.2.1
+ *
+ * @description
+ * This module implements the `IToolPermissionManager` interface, providing a robust and
+ * configurable system for managing permissions related to tool execution within the AgentOS ecosystem.
+ * The `ToolPermissionManager` is a critical component for enforcing authorization policies,
+ * evaluating requests against Persona capabilities, user subscription features (via `ISubscriptionService`),
+ * and any other defined contextual rules. Its design emphasizes clarity, extensibility, and
+ * adherence to SOTA TypeScript practices.
+ *
+ * Key Responsibilities:
+ * - Initialization with a detailed configuration (`ToolPermissionManagerConfig`) and essential
+ * dependent services such as `IAuthService` and `ISubscriptionService`.
+ * - Authoritatively checking if a tool execution is permitted based on a comprehensive
+ * `PermissionCheckContext`, which includes the tool in question, the invoking Persona's
+ * profile, and the end-user's context.
+ * - Verifying that the invoking Persona possesses all `requiredCapabilities` specified by the tool,
+ * if `strictCapabilityChecking` is enabled.
+ * - Interacting with the `ISubscriptionService` to determine if the user's current subscription
+ * tier grants access to specific features that may be prerequisites for using certain tools.
+ * - Providing clear, actionable reasons and detailed metadata for all permission decisions,
+ * aiding in debugging, auditing, and user feedback.
+ * - Centralizing tool access logic to enhance security and maintainability across the platform.
+ * - Offering configurable logging for permission checks via `logToolCalls` in its configuration.
+ *
+ * Architectural Tenets Applied:
+ * - Interface-Driven Design: Implements `IToolPermissionManager`.
+ * - Dependency Injection: `IAuthService` and `ISubscriptionService` are injected.
+ * - Comprehensive JSDoc: All public and significant private members are documented.
+ * - Robust Error Handling: Uses standardized `GMIError` and `GMIErrorCode`.
+ * - Configuration Management: Behavior is driven by `ToolPermissionManagerConfig`.
+ * - Strict Type Safety: Leverages TypeScript's type system to prevent common errors.
+ *
+ * @see {@link ./IToolPermissionManager.ts} for the interface definition and related types (including `FeatureFlag` and `ToolPermissionManagerConfig`).
+ * @see {@link ../ITool.ts} for `ITool` and `ToolDefinition` which include `requiredCapabilities`.
+ * @see {@link ../../../cognitive_substrate/IGMI.ts} for `UserContext` definition.
+ * @see {@link ../../../../services/user_auth/SubscriptionService.ts} for `ISubscriptionService` and `ISubscriptionTier`.
+ * @see {@link @framers/agentos/utils/errors.ts} for `GMIError` and `GMIErrorCode`.
+ */
+import { GMIError, GMIErrorCode, createGMIErrorFromError } from '../../../utils/errors.js';
+import { uuidv4 } from '../../../utils/uuid.js';
+/**
+ * @class ToolPermissionManager
+ * @implements {IToolPermissionManager}
+ * @description
+ * Manages and enforces permissions for tool usage within the AgentOS ecosystem.
+ * It evaluates tool execution requests against configured policies, Persona capabilities,
+ * and user subscription entitlements to determine authorization. This class provides a
+ * centralized point of control for tool access, enhancing security and feature gating
+ * across the platform.
+ */
+export class ToolPermissionManager {
+    /**
+     * Constructs a `ToolPermissionManager` instance.
+     * The instance is not fully operational until the `initialize` method is called
+     * with the necessary configuration and optional service dependencies. This ensures
+     * that the manager always starts in a predictable, uninitialized state.
+     */
+    constructor() {
+        /**
+         * Flag indicating if the manager has been successfully initialized.
+         * Operations that depend on configuration or services are blocked until initialization is complete,
+         * ensuring the manager operates in a valid state.
+         * @private
+         * @type {boolean}
+         */
+        this.isInitialized = false;
+        this.managerId = `tpm-${uuidv4()}`;
+    }
+    /**
+     * Initializes the `ToolPermissionManager` with its configuration and dependent services.
+     * This method must be called and successfully awaited before any permission checks can be performed.
+     * It establishes the manager's operational parameters and links it to essential external services
+     * like authentication and subscription management if they are provided, ensuring all dependencies
+     * are ready for use.
+     *
+     * @public
+     * @async
+     * @param {ToolPermissionManagerConfig} config - The configuration object that defines how
+     * tool permissions are to be evaluated (e.g., strictness of capability checks,
+     * tool-to-feature mappings, logging verbosity). Must not be null or undefined.
+     * @param {IAuthService} [authService] - Optional. An instance of the authentication service,
+     * conforming to the `IAuthService` interface. If provided, it can be used for advanced,
+     * identity-based permission rules not covered by `UserContext` alone.
+     * @param {ISubscriptionService} [subscriptionService] - Optional. An instance of the subscription service,
+     * conforming to the `ISubscriptionService` interface. If provided, it's used to check if a user's
+     * subscription entitles them to use specific tools based on feature flags.
+     * @returns {Promise<void>} A promise that resolves when the manager is fully initialized and ready
+     * to process permission requests.
+     * @throws {GMIError} If the provided `config` is null or undefined, a `GMIError` with
+     * `GMIErrorCode.CONFIGURATION_ERROR` is thrown, preventing initialization with invalid parameters.
+     */
+    async initialize(config, authService, subscriptionService) {
+        if (this.isInitialized) {
+            console.warn(`ToolPermissionManager (ID: ${this.managerId}): Attempting to re-initialize an already initialized instance. The current configuration will be replaced. This may affect ongoing operations if not handled carefully at the application level.`);
+        }
+        if (!config) {
+            throw new GMIError('ToolPermissionManagerConfig cannot be null or undefined during initialization.', GMIErrorCode.CONFIGURATION_ERROR, { managerId: this.managerId, detail: 'Configuration object is missing.' });
+        }
+        this.config = Object.freeze({
+            strictCapabilityChecking: config.strictCapabilityChecking ?? true,
+            toolToSubscriptionFeatures: config.toolToSubscriptionFeatures || {},
+            logToolCalls: config.logToolCalls ?? false, // Default for logToolCalls
+            ...config, // Spread last to allow overrides from config object
+        });
+        this.authService = authService;
+        this.subscriptionService = subscriptionService;
+        if (Object.keys(this.config.toolToSubscriptionFeatures).length > 0 && !this.subscriptionService) {
+            console.warn(`ToolPermissionManager (ID: ${this.managerId}): WARNING - 'toolToSubscriptionFeatures' are configured, but no ISubscriptionService instance was provided. Subscription-based tool access checks will default to denial for tools requiring features. This might be a deployment or configuration oversight.`);
+        }
+        this.isInitialized = true;
+        console.log(`ToolPermissionManager (ID: ${this.managerId}) initialized successfully. Strict capability checking: ${this.config.strictCapabilityChecking}. Logging tool calls: ${this.config.logToolCalls}. Mapped tools to features: ${Object.keys(this.config.toolToSubscriptionFeatures).length}.`);
+    }
+    /**
+     * Ensures that the permission manager has been properly initialized before attempting
+     * to perform any operations that rely on its configuration or injected services.
+     * This is a critical check to prevent runtime errors due to an unconfigured state.
+     *
+     * @private
+     * @throws {GMIError} If the manager is not initialized, an error with
+     * `GMIErrorCode.NOT_INITIALIZED` is thrown, detailing that an operation was
+     * attempted on an uninitialized manager.
+     */
+    ensureInitialized() {
+        if (!this.isInitialized) {
+            throw new GMIError(`ToolPermissionManager (ID: ${this.managerId}) is not initialized. Operations cannot be performed until initialize() is called with a valid configuration.`, GMIErrorCode.NOT_INITIALIZED, { component: 'ToolPermissionManager', managerId: this.managerId, attemptedOperationRequiresInitialization: true });
+        }
+    }
+    /**
+     * Checks if a Persona possesses all capabilities explicitly required by a tool.
+     * This is a fundamental building block for the overall permission decision in `isExecutionAllowed`.
+     * An empty or undefined `toolRequiredCapabilities` array means the tool has no specific capability prerequisites.
+     *
+     * @public
+     * @param {string[]} personaCapabilities - An array of capability strings (e.g., "filesystem:read", "api:weather")
+     * currently possessed by the Persona. It's expected these are valid, non-empty strings.
+     * @param {string[] | undefined} toolRequiredCapabilities - An array of capability strings defined by the tool
+     * as prerequisites for its execution. If `undefined` or empty, the tool is considered to have no
+     * specific capability requirements, and this check will pass by default.
+     * @returns {boolean} `true` if the Persona possesses all capabilities required by the tool,
+     * or if the tool requires no specific capabilities. Returns `false` if any required capability is missing,
+     * or if the Persona has no capabilities listed when some are required.
+     */
+    hasRequiredCapabilities(personaCapabilities, toolRequiredCapabilities) {
+        this.ensureInitialized();
+        if (!toolRequiredCapabilities || toolRequiredCapabilities.length === 0) {
+            return true;
+        }
+        if (!personaCapabilities || personaCapabilities.length === 0) {
+            return false;
+        }
+        const personaCapabilitiesSet = new Set(personaCapabilities.filter(cap => typeof cap === 'string' && cap.trim() !== ''));
+        const validToolRequiredCaps = toolRequiredCapabilities.filter(cap => typeof cap === 'string' && cap.trim() !== '');
+        for (const requiredCap of validToolRequiredCaps) {
+            if (!personaCapabilitiesSet.has(requiredCap)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Retrieves the list of `FeatureFlag`s that are configured as being required for a specific tool.
+     * These feature flags typically map to user subscription tiers or special entitlements.
+     * The information is sourced directly from the `toolToSubscriptionFeatures` mapping
+     * provided in the manager's runtime configuration.
+     *
+     * @public
+     * @param {string} toolIdOrName - The unique ID (`ITool.id`) or functional name (`ITool.name`) of the tool.
+     * The manager will attempt to find a mapping using this identifier. Using `tool.id` is generally preferred
+     * for more stable mappings if tool names might change or be overloaded.
+     * @returns {FeatureFlag[] | undefined} An array of `FeatureFlag` objects (each with a `flag` string
+     * and optional `description`) required for the tool. Returns `undefined` if no specific features
+     * are mapped as required for this tool in the current configuration.
+     */
+    getRequiredFeaturesForTool(toolIdOrName) {
+        this.ensureInitialized();
+        return this.config.toolToSubscriptionFeatures?.[toolIdOrName];
+    }
+    /**
+     * Checks if a user's current subscription grants them access to the specific features
+     * required by a particular tool. This method relies on an injected `ISubscriptionService`
+     * to fetch user tier information and validate feature entitlements.
+     *
+     * @public
+     * @async
+     * @param {string} userId - The ID of the user whose subscription entitlements are being verified.
+     * @param {string} toolIdOrName - The unique ID (`ITool.id`) or functional name (`ITool.name`) of the tool.
+     * This identifier is used to look up any feature flag prerequisites from the manager's configuration.
+     * @returns {Promise<{isAllowed: boolean, missingFeatures?: FeatureFlag[], reason?: string}>}
+     * An object detailing the outcome of the subscription check.
+     * @throws {GMIError} If critical services are misconfigured or if interaction with `ISubscriptionService` fails.
+     */
+    async checkToolSubscriptionAccess(userId, toolIdOrName) {
+        this.ensureInitialized();
+        const requiredFeatureFlags = this.getRequiredFeaturesForTool(toolIdOrName);
+        if (!requiredFeatureFlags || requiredFeatureFlags.length === 0) {
+            return { isAllowed: true, reason: `Tool '${toolIdOrName}' does not require specific subscription features.` };
+        }
+        if (!this.subscriptionService) {
+            const reason = `Tool '${toolIdOrName}' requires subscription features [${requiredFeatureFlags.map(f => f.flag).join(', ')}], but ISubscriptionService is not configured. To enable subscription-based access control, inject a subscription service via AgentOSConfig or use @framers/agentos-extensions/auth. Defaulting to ALLOW.`;
+            console.warn(`ToolPermissionManager (ID: ${this.managerId}, User: ${userId}): ${reason}`);
+            // Default to allowing access when no subscription service configured
+            return { isAllowed: true, reason: `No subscription service configured - access allowed by default` };
+        }
+        try {
+            const userTier = (this.subscriptionService.getUserSubscriptionTier
+                ? await this.subscriptionService.getUserSubscriptionTier(userId)
+                : await this.subscriptionService.getUserSubscription(userId));
+            if (!userTier) {
+                const reason = `User (ID: ${userId}) does not have an identifiable or active subscription tier. Access to tool '${toolIdOrName}' requiring features [${requiredFeatureFlags.map(f => f.flag).join(', ')}] is denied.`;
+                return { isAllowed: false, missingFeatures: requiredFeatureFlags, reason };
+            }
+            const userTierFeatureStrings = new Set(userTier.features || []);
+            const missingFeaturesAccumulator = [];
+            for (const requiredFeature of requiredFeatureFlags) {
+                if (!userTierFeatureStrings.has(requiredFeature.flag)) {
+                    missingFeaturesAccumulator.push(requiredFeature);
+                }
+            }
+            if (missingFeaturesAccumulator.length > 0) {
+                const reason = `User (ID: ${userId}) lacks required subscription features for tool '${toolIdOrName}': [${missingFeaturesAccumulator.map(f => `'${f.flag}'`).join(', ')}]. Current tier: '${userTier.name}'.`;
+                return { isAllowed: false, missingFeatures: missingFeaturesAccumulator, reason };
+            }
+            return { isAllowed: true, reason: `User (ID: ${userId}) possesses all required subscription features for tool '${toolIdOrName}' via tier '${userTier.name}'.` };
+        }
+        catch (error) {
+            const wrappedError = createGMIErrorFromError(error, GMIErrorCode.SUBSCRIPTION_ERROR, { userId, toolIdOrName, serviceCalled: 'ISubscriptionService.getUserSubscriptionTier' }, `An error occurred while checking subscription features for tool '${toolIdOrName}'.`, this.managerId);
+            console.error(`ToolPermissionManager (ID: ${this.managerId}): ${wrappedError.message}`, wrappedError.toJSON());
+            throw wrappedError;
+        }
+    }
+    /**
+     * Determines if a tool execution is permitted based on the comprehensive provided context.
+     * This is the primary method for authorizing tool calls.
+     *
+     * @public
+     * @async
+     * @param {PermissionCheckContext} context - The context for the permission check.
+     * @returns {Promise<PermissionCheckResult>} A promise resolving to a `PermissionCheckResult`.
+     * @throws {GMIError} If the manager is not initialized or if an unrecoverable error occurs.
+     */
+    async isExecutionAllowed(context) {
+        this.ensureInitialized();
+        const { tool, personaId, personaCapabilities, userContext, gmiId } = context;
+        const logPreamble = `ToolPermissionManager (ID: ${this.managerId}, GMI: ${gmiId || 'N/A'}, Persona: ${personaId}, User: ${userContext.userId}, Tool: ${tool.name} [ID: ${tool.id}])`;
+        if (this.config.strictCapabilityChecking) {
+            if (!this.hasRequiredCapabilities(personaCapabilities, tool.requiredCapabilities)) {
+                const missingCaps = tool.requiredCapabilities?.filter(rc => !personaCapabilities.includes(rc)) || [];
+                const reason = `Permission Denied: Persona (ID: '${personaId}') lacks required capabilities for tool '${tool.name}'. Missing: [${missingCaps.join(', ')}]. Required: [${tool.requiredCapabilities?.join(', ')}].`;
+                if (this.config.logToolCalls) {
+                    console.warn(`${logPreamble}: Strict capability check FAILED. ${reason}`);
+                }
+                return {
+                    isAllowed: false,
+                    reason,
+                    details: { checkType: "personaCapabilities", required: tool.requiredCapabilities, possessed: personaCapabilities, missing: missingCaps },
+                };
+            }
+            if (this.config.logToolCalls) {
+                console.info(`${logPreamble}: Persona capability check PASSED.`);
+            }
+        }
+        else {
+            if (this.config.logToolCalls) {
+                console.warn(`${logPreamble}: Strict capability checking is DISABLED by configuration. Persona capability validation for tool '${tool.name}' was skipped.`);
+            }
+        }
+        const toolIdentifierForFeatureLookup = tool.id || tool.name;
+        const requiredFeatures = this.getRequiredFeaturesForTool(toolIdentifierForFeatureLookup);
+        if (requiredFeatures && requiredFeatures.length > 0) {
+            const subscriptionAccessResult = await this.checkToolSubscriptionAccess(userContext.userId, toolIdentifierForFeatureLookup);
+            if (!subscriptionAccessResult.isAllowed) {
+                const reason = subscriptionAccessResult.reason || `User (ID: '${userContext.userId}') subscription does not grant access to tool '${tool.name}'.`;
+                if (this.config.logToolCalls) {
+                    console.warn(`${logPreamble}: User subscription feature check FAILED. ${reason}`, subscriptionAccessResult.missingFeatures);
+                }
+                return {
+                    isAllowed: false,
+                    reason,
+                    details: { checkType: "userSubscriptionFeatures", requiredFeatures: requiredFeatures.map(f => f.flag), missingFeatures: subscriptionAccessResult.missingFeatures?.map(f => f.flag), toolIdentifier: toolIdentifierForFeatureLookup }
+                };
+            }
+            if (this.config.logToolCalls) {
+                console.info(`${logPreamble}: User subscription feature check PASSED.`);
+            }
+        }
+        const successReason = `Execution of tool '${tool.name}' (ID: ${tool.id}) is permitted. All configured permission checks passed.`;
+        if (this.config.logToolCalls) {
+            console.log(`${logPreamble}: All permission checks PASSED. ${successReason}`);
+        }
+        return { isAllowed: true, reason: successReason };
+    }
+}
+//# sourceMappingURL=ToolPermissionManager.js.map

package/dist/core/tools/permissions/ToolPermissionManager.js.map

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

package/dist/core/ui/IUIComponent.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Minimal UI component spec placeholder. Concrete UI frameworks can extend this
+ * interface to render tool/agent output in custom shells.
+ */
+export interface UIComponentSpecification {
+    id: string;
+    type: string;
+    data: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+}
+//# sourceMappingURL=IUIComponent.d.ts.map

package/dist/core/ui/IUIComponent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IUIComponent.d.ts","sourceRoot":"","sources":["../../../src/core/ui/IUIComponent.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC"}

package/dist/core/ui/IUIComponent.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=IUIComponent.js.map

package/dist/core/ui/IUIComponent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IUIComponent.js","sourceRoot":"","sources":["../../../src/core/ui/IUIComponent.ts"],"names":[],"mappings":""}

package/dist/core/usage/UsageLedger.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @fileoverview Aggregates model usage (tokens, cost) across sessions, personas, and providers.
+ * Serves as a foundational accounting component for later billing, analytics, and dynamic routing decisions.
+ *
+ * Design Goals:
+ * 1. Low Overhead: Pure in-memory by default; pluggable persistence adapter for durability.
+ * 2. Incremental Updates: Accept partial usage metrics from streaming chunks; finalize on terminal chunk.
+ * 3. Query Flexibility: Summaries per session, persona, provider, model.
+ * 4. Cost Normalization: Uses `ModelUsage.costUSD` when present; can apply fallback pricing from a model catalog.
+ */
+import { ModelCompletionResponse, ModelUsage } from '../llm/providers/IProvider';
+/** Canonical key dimensions tracked for each usage record. */
+export interface UsageDimensions {
+    sessionId: string;
+    personaId?: string;
+    providerId?: string;
+    modelId?: string;
+}
+/** Internal mutable aggregation bucket. */
+interface UsageBucket extends UsageDimensions {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    costUSD: number;
+    calls: number;
+}
+/** Result returned by summary queries. */
+export type UsageSummary = UsageBucket;
+/** Persistence adapter contract enabling storage engines. */
+export interface IUsageLedgerPersistence {
+    save(bucket: UsageBucket): Promise<void>;
+    loadAll(): Promise<UsageBucket[]>;
+}
+/** Options for UsageLedger behavior. */
+export interface UsageLedgerOptions {
+    /** When true, interim streaming usage (non-final chunks) will contribute estimated tokens. */
+    includeInterimStreamingUsage?: boolean;
+    /** Optional pricing fallback map: modelId -> { inputPer1M, outputPer1M }. */
+    pricingFallbacks?: Record<string, {
+        inputPer1M?: number;
+        outputPer1M?: number;
+        totalPer1M?: number;
+    }>;
+    /** Persistence adapter for durability (undefined => in-memory only). */
+    persistenceAdapter?: IUsageLedgerPersistence;
+}
+/**
+ * UsageLedger accumulates usage metrics from provider responses.
+ * Usage ingestion MUST be called for final streaming chunks or any non-streaming responses.
+ */
+export declare class UsageLedger {
+    private buckets;
+    private options;
+    constructor(options?: UsageLedgerOptions);
+    /** Compose a stable bucket key from dimensions. */
+    private bucketKey;
+    /** Ensure bucket exists. */
+    private getOrCreateBucket;
+    /**
+     * Ingest a completion response chunk (streaming final or single shot) updating usage aggregates.
+     * Non-final streaming chunks are ignored unless includeInterimStreamingUsage=true.
+     */
+    ingestCompletionChunk(dim: UsageDimensions, chunk: ModelCompletionResponse): void;
+    /** Manual ingestion for custom usage objects (e.g. embeddings). */
+    ingestUsage(dim: UsageDimensions, usage: ModelUsage & {
+        modelId?: string;
+        isFinal?: boolean;
+    }): void;
+    /** Return all summaries. */
+    listAllSummaries(): UsageSummary[];
+    /** Query by session id. */
+    getSummariesBySession(sessionId: string): UsageSummary[];
+    /** Aggregate totals across all buckets for a session. */
+    getSessionAggregate(sessionId: string): UsageSummary | undefined;
+    /** Persist current buckets if an adapter is configured. */
+    flush(): Promise<void>;
+    /** Load all buckets from persistence (merging into existing). */
+    bootstrapFromPersistence(): Promise<void>;
+}
+export default UsageLedger;
+//# sourceMappingURL=UsageLedger.d.ts.map

package/dist/core/usage/UsageLedger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"UsageLedger.d.ts","sourceRoot":"","sources":["../../../src/core/usage/UsageLedger.ts"],"names":[],"mappings":"AACA;;;;;;;;;GASG;AACH,OAAO,EAAE,uBAAuB,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAEjF,8DAA8D;AAC9D,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,2CAA2C;AAC3C,UAAU,WAAY,SAAQ,eAAe;IAC3C,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,0CAA0C;AAC1C,MAAM,MAAM,YAAY,GAAG,WAAW,CAAC;AAEvC,6DAA6D;AAC7D,MAAM,WAAW,uBAAuB;IACtC,IAAI,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,OAAO,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;CACnC;AAED,wCAAwC;AACxC,MAAM,WAAW,kBAAkB;IACjC,8FAA8F;IAC9F,4BAA4B,CAAC,EAAE,OAAO,CAAC;IACvC,6EAA6E;IAC7E,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACtG,wEAAwE;IACxE,kBAAkB,CAAC,EAAE,uBAAuB,CAAC;CAC9C;AAED;;;GAGG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,OAAO,CAAuC;IACtD,OAAO,CAAC,OAAO,CAAqB;gBAExB,OAAO,GAAE,kBAAuB;IAI5C,mDAAmD;IACnD,OAAO,CAAC,SAAS;IAIjB,4BAA4B;IAC5B,OAAO,CAAC,iBAAiB;IAUzB;;;OAGG;IACH,qBAAqB,CAAC,GAAG,EAAE,eAAe,EAAE,KAAK,EAAE,uBAAuB,GAAG,IAAI;IA+BjF,mEAAmE;IACnE,WAAW,CAAC,GAAG,EAAE,eAAe,EAAE,KAAK,EAAE,UAAU,GAAG;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI;IAsBpG,4BAA4B;IAC5B,gBAAgB,IAAI,YAAY,EAAE;IAIlC,2BAA2B;IAC3B,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,EAAE;IAIxD,yDAAyD;IACzD,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAgBhE,2DAA2D;IACrD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAO5B,iEAAiE;IAC3D,wBAAwB,IAAI,OAAO,CAAC,IAAI,CAAC;CAYhD;AAED,eAAe,WAAW,CAAC"}

package/dist/core/usage/UsageLedger.js

@@ -0,0 +1,135 @@
+/**
+ * UsageLedger accumulates usage metrics from provider responses.
+ * Usage ingestion MUST be called for final streaming chunks or any non-streaming responses.
+ */
+export class UsageLedger {
+    constructor(options = {}) {
+        this.buckets = new Map();
+        this.options = options;
+    }
+    /** Compose a stable bucket key from dimensions. */
+    bucketKey(dim) {
+        return [dim.sessionId, dim.personaId || '-', dim.providerId || '-', dim.modelId || '-'].join('|');
+    }
+    /** Ensure bucket exists. */
+    getOrCreateBucket(dim) {
+        const key = this.bucketKey(dim);
+        let b = this.buckets.get(key);
+        if (!b) {
+            b = { ...dim, promptTokens: 0, completionTokens: 0, totalTokens: 0, costUSD: 0, calls: 0 };
+            this.buckets.set(key, b);
+        }
+        return b;
+    }
+    /**
+     * Ingest a completion response chunk (streaming final or single shot) updating usage aggregates.
+     * Non-final streaming chunks are ignored unless includeInterimStreamingUsage=true.
+     */
+    ingestCompletionChunk(dim, chunk) {
+        if (!chunk.usage)
+            return; // Nothing to record
+        if (!chunk.isFinal && !this.options.includeInterimStreamingUsage)
+            return;
+        const usage = chunk.usage;
+        const b = this.getOrCreateBucket({ ...dim, modelId: chunk.modelId });
+        // Interim usage may be partial; we accumulate naive sums.
+        b.promptTokens += usage.promptTokens || 0;
+        b.completionTokens += usage.completionTokens || 0;
+        b.totalTokens += usage.totalTokens || 0;
+        // Cost: prefer provided costUSD else derive from fallback pricing.
+        let cost = usage.costUSD || 0;
+        if (!usage.costUSD && this.options.pricingFallbacks) {
+            const p = this.options.pricingFallbacks[b.modelId || ''];
+            if (p) {
+                // If provider splits prompt/completion tokens we can estimate using input/output rates.
+                if (p.totalPer1M) {
+                    cost += (usage.totalTokens / 1000000) * p.totalPer1M;
+                }
+                else {
+                    if (p.inputPer1M && usage.promptTokens)
+                        cost += (usage.promptTokens / 1000000) * p.inputPer1M;
+                    if (p.outputPer1M && usage.completionTokens)
+                        cost += (usage.completionTokens / 1000000) * p.outputPer1M;
+                }
+            }
+        }
+        b.costUSD += cost;
+        if (chunk.isFinal)
+            b.calls += 1;
+    }
+    /** Manual ingestion for custom usage objects (e.g. embeddings). */
+    ingestUsage(dim, usage) {
+        const b = this.getOrCreateBucket({ ...dim, modelId: usage.modelId });
+        b.promptTokens += usage.promptTokens || 0;
+        b.completionTokens += usage.completionTokens || 0;
+        b.totalTokens += usage.totalTokens || 0;
+        let cost = usage.costUSD || 0;
+        if (!usage.costUSD && this.options.pricingFallbacks) {
+            const p = this.options.pricingFallbacks[b.modelId || ''];
+            if (p) {
+                if (p.totalPer1M) {
+                    cost += (usage.totalTokens / 1000000) * p.totalPer1M;
+                }
+                else {
+                    if (p.inputPer1M && usage.promptTokens)
+                        cost += (usage.promptTokens / 1000000) * p.inputPer1M;
+                    if (p.outputPer1M && usage.completionTokens)
+                        cost += (usage.completionTokens / 1000000) * p.outputPer1M;
+                }
+            }
+        }
+        b.costUSD += cost;
+        if (usage.isFinal)
+            b.calls += 1;
+    }
+    /** Return all summaries. */
+    listAllSummaries() {
+        return Array.from(this.buckets.values()).map(b => ({ ...b }));
+    }
+    /** Query by session id. */
+    getSummariesBySession(sessionId) {
+        return this.listAllSummaries().filter(b => b.sessionId === sessionId);
+    }
+    /** Aggregate totals across all buckets for a session. */
+    getSessionAggregate(sessionId) {
+        const buckets = this.getSummariesBySession(sessionId);
+        if (!buckets.length)
+            return undefined;
+        return buckets.reduce((acc, b, i) => {
+            if (i === 0)
+                acc = { ...b };
+            else {
+                acc.promptTokens += b.promptTokens;
+                acc.completionTokens += b.completionTokens;
+                acc.totalTokens += b.totalTokens;
+                acc.costUSD += b.costUSD;
+                acc.calls += b.calls;
+            }
+            return acc;
+        }, buckets[0]);
+    }
+    /** Persist current buckets if an adapter is configured. */
+    async flush() {
+        if (!this.options.persistenceAdapter)
+            return;
+        for (const b of this.buckets.values()) {
+            await this.options.persistenceAdapter.save(b);
+        }
+    }
+    /** Load all buckets from persistence (merging into existing). */
+    async bootstrapFromPersistence() {
+        if (!this.options.persistenceAdapter)
+            return;
+        const loaded = await this.options.persistenceAdapter.loadAll();
+        for (const b of loaded) {
+            const existing = this.getOrCreateBucket(b);
+            existing.promptTokens += b.promptTokens;
+            existing.completionTokens += b.completionTokens;
+            existing.totalTokens += b.totalTokens;
+            existing.costUSD += b.costUSD;
+            existing.calls += b.calls;
+        }
+    }
+}
+export default UsageLedger;
+//# sourceMappingURL=UsageLedger.js.map

package/dist/core/usage/UsageLedger.js.map

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

package/dist/core/workflows/IWorkflowEngine.d.ts

@@ -0,0 +1,42 @@
+import type { AgentOSInput } from '../../api/types/AgentOSInput';
+import type { WorkflowDefinition, WorkflowDescriptorPayload, WorkflowEvent, WorkflowInstance, WorkflowProgressUpdate, WorkflowStatus } from './WorkflowTypes';
+import type { WorkflowQueryOptions, IWorkflowStore, WorkflowTaskUpdate } from './storage/IWorkflowStore';
+import type { ILogger } from '../../logging/ILogger';
+export interface WorkflowEngineConfig {
+    maxConcurrentWorkflows?: number;
+    defaultWorkflowTimeoutSeconds?: number;
+}
+export interface StartWorkflowOptions {
+    input: AgentOSInput;
+    definition: WorkflowDefinition;
+    workflowId?: string;
+    conversationId?: string;
+    createdByUserId?: string;
+    context?: Record<string, unknown>;
+    roleAssignments?: Record<string, string>;
+    metadata?: Record<string, unknown>;
+}
+export interface WorkflowEngineDependencies {
+    store: IWorkflowStore;
+    logger?: ILogger;
+}
+export interface WorkflowEngineEventListener {
+    (event: WorkflowEvent): void | Promise<void>;
+}
+export interface IWorkflowEngine {
+    initialize(config: WorkflowEngineConfig, deps: WorkflowEngineDependencies): Promise<void>;
+    registerWorkflowDescriptor(descriptor: WorkflowDescriptorPayload): Promise<void>;
+    unregisterWorkflowDescriptor(workflowDefinitionId: string): Promise<void>;
+    listWorkflowDefinitions(): WorkflowDefinition[];
+    startWorkflow(options: StartWorkflowOptions): Promise<WorkflowInstance>;
+    getWorkflow(workflowId: string): Promise<WorkflowInstance | null>;
+    updateWorkflowStatus(workflowId: string, status: WorkflowStatus): Promise<WorkflowInstance | null>;
+    applyTaskUpdates(workflowId: string, updates: WorkflowTaskUpdate[]): Promise<WorkflowInstance | null>;
+    recordEvents(events: WorkflowEvent[]): Promise<void>;
+    updateWorkflowAgencyState(workflowId: string, agencyState: WorkflowInstance['agencyState']): Promise<WorkflowInstance | null>;
+    listWorkflows(options?: WorkflowQueryOptions): Promise<WorkflowInstance[]>;
+    getWorkflowProgress(workflowId: string, sinceTimestamp?: string): Promise<WorkflowProgressUpdate | null>;
+    onEvent(listener: WorkflowEngineEventListener): void;
+    offEvent(listener: WorkflowEngineEventListener): void;
+}
+//# sourceMappingURL=IWorkflowEngine.d.ts.map

package/dist/core/workflows/IWorkflowEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IWorkflowEngine.d.ts","sourceRoot":"","sources":["../../../src/core/workflows/IWorkflowEngine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,KAAK,EACV,kBAAkB,EAClB,yBAAyB,EACzB,aAAa,EACb,gBAAgB,EAChB,sBAAsB,EACtB,cAAc,EACf,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,oBAAoB,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACzG,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAErD,MAAM,WAAW,oBAAoB;IACnC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,6BAA6B,CAAC,EAAE,MAAM,CAAC;CACxC;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,YAAY,CAAC;IACpB,UAAU,EAAE,kBAAkB,CAAC;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,0BAA0B;IACzC,KAAK,EAAE,cAAc,CAAC;IACtB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,2BAA2B;IAC1C,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9C;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,CAAC,MAAM,EAAE,oBAAoB,EAAE,IAAI,EAAE,0BAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1F,0BAA0B,CAAC,UAAU,EAAE,yBAAyB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjF,4BAA4B,CAAC,oBAAoB,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1E,uBAAuB,IAAI,kBAAkB,EAAE,CAAC;IAEhD,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAExE,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;IAElE,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;IAEnG,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,EAAE,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;IAEtG,YAAY,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,yBAAyB,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,gBAAgB,CAAC,aAAa,CAAC,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;IAE9H,aAAa,CAAC,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAAC;IAE3E,mBAAmB,CAAC,UAAU,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC,CAAC;IAEzG,OAAO,CAAC,QAAQ,EAAE,2BAA2B,GAAG,IAAI,CAAC;IAErD,QAAQ,CAAC,QAAQ,EAAE,2BAA2B,GAAG,IAAI,CAAC;CACvD"}

package/dist/core/workflows/IWorkflowEngine.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=IWorkflowEngine.js.map

package/dist/core/workflows/IWorkflowEngine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IWorkflowEngine.js","sourceRoot":"","sources":["../../../src/core/workflows/IWorkflowEngine.ts"],"names":[],"mappings":""}