@framers/agentos 0.1.0

package/dist/core/agency/AgencyRegistry.d.ts

@@ -0,0 +1,100 @@
+/**
+ * @file AgencyRegistry.ts
+ * @description Registry for tracking active Agency sessions in the AgentOS runtime.
+ * @module AgentOS/Agency
+ */
+import type { ILogger } from '../../logging/ILogger';
+import type { AgencySeatHistoryEntry, AgencySeatRegistrationArgs, AgencySeatState, AgencySession, AgencyUpsertArgs } from './AgencyTypes';
+/**
+ * Tracks the Agencies (multi-GMI collectives) active inside the AgentOS runtime.
+ *
+ * @remarks
+ * The registry is intentionally ephemeral; durable state should be captured via
+ * workflow persistence. For shared memory, use {@link AgencyMemoryManager}.
+ *
+ * @example
+ * ```typescript
+ * const registry = new AgencyRegistry(logger);
+ *
+ * // Create agency with shared memory enabled
+ * const session = registry.upsertAgency({
+ *   workflowId: 'workflow-123',
+ *   conversationId: 'conv-456',
+ *   memoryConfig: { enabled: true },
+ * });
+ *
+ * // Register GMI seats
+ * registry.registerSeat({
+ *   agencyId: session.agencyId,
+ *   roleId: 'researcher',
+ *   gmiInstanceId: 'gmi-789',
+ *   personaId: 'research-persona',
+ * });
+ * ```
+ */
+export declare class AgencyRegistry {
+    private readonly logger?;
+    /** Active agency sessions keyed by agency ID */
+    private readonly agencies;
+    /** Workflow to agency mapping for quick lookup */
+    private readonly workflowToAgency;
+    /**
+     * Creates a new AgencyRegistry instance.
+     * @param logger - Optional logger for diagnostics
+     */
+    constructor(logger?: ILogger | undefined);
+    /**
+     * Creates or updates an agency session associated with a workflow.
+     *
+     * @param args - Upsert payload containing workflow linkage, memory config, and optional metadata.
+     * @returns The upserted agency session.
+     *
+     * @example
+     * ```typescript
+     * const session = registry.upsertAgency({
+     *   workflowId: 'workflow-123',
+     *   conversationId: 'conv-456',
+     *   memoryConfig: {
+     *     enabled: true,
+     *     autoIngestCommunications: true,
+     *   },
+     * });
+     * ```
+     */
+    upsertAgency(args: AgencyUpsertArgs): AgencySession;
+    /**
+     * Retrieves an agency session by identifier.
+     * @param agencyId - Target Agency identifier.
+     * @returns The matching agency session or `undefined` when absent.
+     */
+    getAgency(agencyId: string): AgencySession | undefined;
+    /**
+     * Resolves the agency session associated with a workflow instance (if any).
+     * @param workflowId - Workflow instance identifier.
+     * @returns The agency session mapped to the workflow, if present.
+     */
+    getAgencyByWorkflow(workflowId: string): AgencySession | undefined;
+    /**
+     * Registers or updates a seat inside the agency.
+     * @param args - Seat registration payload.
+     * @returns Updated agency session after the seat registration.
+     * @throws {Error} When attempting to register against an unknown agency.
+     */
+    registerSeat(args: AgencySeatRegistrationArgs): AgencySession;
+    /**
+     * Removes an agency entirely (e.g., when the workflow reaches a terminal state).
+     * @param agencyId - Agency identifier to remove.
+     * @returns `true` when the agency existed and was removed.
+     */
+    removeAgency(agencyId: string): boolean;
+    /**
+     * Appends a history entry to the specified seat and returns the updated state.
+     */
+    appendSeatHistory(agencyId: string, roleId: string, entry: AgencySeatHistoryEntry, maxEntries?: number): AgencySeatState | undefined;
+    /**
+     * Merges metadata onto a seat without altering other properties.
+     */
+    mergeSeatMetadata(agencyId: string, roleId: string, metadata: Record<string, unknown>): AgencySeatState | undefined;
+    private mutateSeat;
+}
+//# sourceMappingURL=AgencyRegistry.d.ts.map

package/dist/core/agency/AgencyRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgencyRegistry.d.ts","sourceRoot":"","sources":["../../../src/core/agency/AgencyRegistry.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,KAAK,EACV,sBAAsB,EACtB,0BAA0B,EAC1B,eAAe,EACf,aAAa,EACb,gBAAgB,EACjB,MAAM,eAAe,CAAC;AAEvB;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,cAAc;IAWb,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IAVpC,gDAAgD;IAChD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoC;IAE7D,kDAAkD;IAClD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA6B;IAE9D;;;OAGG;gBAC0B,MAAM,CAAC,EAAE,OAAO,YAAA;IAE7C;;;;;;;;;;;;;;;;;OAiBG;IACI,YAAY,CAAC,IAAI,EAAE,gBAAgB,GAAG,aAAa;IA4C1D;;;;OAIG;IACI,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAI7D;;;;OAIG;IACI,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAKzE;;;;;OAKG;IACI,YAAY,CAAC,IAAI,EAAE,0BAA0B,GAAG,aAAa;IAyBpE;;;;OAIG;IACI,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAc9C;;OAEG;IACI,iBAAiB,CACtB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,sBAAsB,EAC7B,UAAU,SAAK,GACd,eAAe,GAAG,SAAS;IAU9B;;OAEG;IACI,iBAAiB,CACtB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,eAAe,GAAG,SAAS;IAU9B,OAAO,CAAC,UAAU;CAkBnB"}

package/dist/core/agency/AgencyRegistry.js

@@ -0,0 +1,209 @@
+/**
+ * @file AgencyRegistry.ts
+ * @description Registry for tracking active Agency sessions in the AgentOS runtime.
+ * @module AgentOS/Agency
+ */
+import { uuidv4 } from '../../utils/uuid.js';
+/**
+ * Tracks the Agencies (multi-GMI collectives) active inside the AgentOS runtime.
+ *
+ * @remarks
+ * The registry is intentionally ephemeral; durable state should be captured via
+ * workflow persistence. For shared memory, use {@link AgencyMemoryManager}.
+ *
+ * @example
+ * ```typescript
+ * const registry = new AgencyRegistry(logger);
+ *
+ * // Create agency with shared memory enabled
+ * const session = registry.upsertAgency({
+ *   workflowId: 'workflow-123',
+ *   conversationId: 'conv-456',
+ *   memoryConfig: { enabled: true },
+ * });
+ *
+ * // Register GMI seats
+ * registry.registerSeat({
+ *   agencyId: session.agencyId,
+ *   roleId: 'researcher',
+ *   gmiInstanceId: 'gmi-789',
+ *   personaId: 'research-persona',
+ * });
+ * ```
+ */
+export class AgencyRegistry {
+    /**
+     * Creates a new AgencyRegistry instance.
+     * @param logger - Optional logger for diagnostics
+     */
+    constructor(logger) {
+        this.logger = logger;
+        /** Active agency sessions keyed by agency ID */
+        this.agencies = new Map();
+        /** Workflow to agency mapping for quick lookup */
+        this.workflowToAgency = new Map();
+    }
+    /**
+     * Creates or updates an agency session associated with a workflow.
+     *
+     * @param args - Upsert payload containing workflow linkage, memory config, and optional metadata.
+     * @returns The upserted agency session.
+     *
+     * @example
+     * ```typescript
+     * const session = registry.upsertAgency({
+     *   workflowId: 'workflow-123',
+     *   conversationId: 'conv-456',
+     *   memoryConfig: {
+     *     enabled: true,
+     *     autoIngestCommunications: true,
+     *   },
+     * });
+     * ```
+     */
+    upsertAgency(args) {
+        const existingId = args.agencyId ?? this.workflowToAgency.get(args.workflowId);
+        const now = new Date().toISOString();
+        if (existingId && this.agencies.has(existingId)) {
+            const session = this.agencies.get(existingId);
+            session.updatedAt = now;
+            session.metadata = {
+                ...session.metadata,
+                ...args.metadata,
+            };
+            // Merge memory config if provided
+            if (args.memoryConfig) {
+                session.memoryConfig = {
+                    ...session.memoryConfig,
+                    ...args.memoryConfig,
+                };
+            }
+            this.workflowToAgency.set(args.workflowId, session.agencyId);
+            return session;
+        }
+        const agencyId = existingId ?? `agency-${uuidv4()}`;
+        const session = {
+            agencyId,
+            workflowId: args.workflowId,
+            conversationId: args.conversationId,
+            createdAt: now,
+            updatedAt: now,
+            seats: {},
+            metadata: args.metadata ?? {},
+            memoryConfig: args.memoryConfig,
+        };
+        this.agencies.set(agencyId, session);
+        this.workflowToAgency.set(args.workflowId, agencyId);
+        this.logger?.info?.('Created Agency session', {
+            agencyId,
+            workflowId: args.workflowId,
+            conversationId: args.conversationId,
+            memoryEnabled: args.memoryConfig?.enabled ?? false,
+        });
+        return session;
+    }
+    /**
+     * Retrieves an agency session by identifier.
+     * @param agencyId - Target Agency identifier.
+     * @returns The matching agency session or `undefined` when absent.
+     */
+    getAgency(agencyId) {
+        return this.agencies.get(agencyId);
+    }
+    /**
+     * Resolves the agency session associated with a workflow instance (if any).
+     * @param workflowId - Workflow instance identifier.
+     * @returns The agency session mapped to the workflow, if present.
+     */
+    getAgencyByWorkflow(workflowId) {
+        const agencyId = this.workflowToAgency.get(workflowId);
+        return agencyId ? this.agencies.get(agencyId) : undefined;
+    }
+    /**
+     * Registers or updates a seat inside the agency.
+     * @param args - Seat registration payload.
+     * @returns Updated agency session after the seat registration.
+     * @throws {Error} When attempting to register against an unknown agency.
+     */
+    registerSeat(args) {
+        const session = this.getAgency(args.agencyId);
+        if (!session) {
+            throw new Error(`AgencyRegistry.registerSeat called with unknown agencyId '${args.agencyId}'.`);
+        }
+        const now = new Date().toISOString();
+        const existingSeat = session.seats[args.roleId];
+        const seat = {
+            roleId: args.roleId,
+            gmiInstanceId: args.gmiInstanceId,
+            personaId: args.personaId,
+            metadata: args.metadata,
+            attachedAt: now,
+            history: existingSeat?.history ?? [],
+        };
+        session.seats[args.roleId] = seat;
+        session.updatedAt = now;
+        this.logger?.debug?.('Registered Agency seat', {
+            agencyId: args.agencyId,
+            roleId: args.roleId,
+            gmiInstanceId: args.gmiInstanceId,
+        });
+        return session;
+    }
+    /**
+     * Removes an agency entirely (e.g., when the workflow reaches a terminal state).
+     * @param agencyId - Agency identifier to remove.
+     * @returns `true` when the agency existed and was removed.
+     */
+    removeAgency(agencyId) {
+        const session = this.agencies.get(agencyId);
+        if (!session) {
+            return false;
+        }
+        this.agencies.delete(agencyId);
+        this.workflowToAgency.delete(session.workflowId);
+        this.logger?.info?.('Removed Agency session', {
+            agencyId,
+            workflowId: session.workflowId,
+        });
+        return true;
+    }
+    /**
+     * Appends a history entry to the specified seat and returns the updated state.
+     */
+    appendSeatHistory(agencyId, roleId, entry, maxEntries = 20) {
+        return this.mutateSeat(agencyId, roleId, (seat) => {
+            const history = seat.history ? [...seat.history, entry] : [entry];
+            if (history.length > maxEntries) {
+                history.splice(0, history.length - maxEntries);
+            }
+            return { ...seat, history };
+        });
+    }
+    /**
+     * Merges metadata onto a seat without altering other properties.
+     */
+    mergeSeatMetadata(agencyId, roleId, metadata) {
+        return this.mutateSeat(agencyId, roleId, (seat) => ({
+            ...seat,
+            metadata: {
+                ...(seat.metadata ?? {}),
+                ...metadata,
+            },
+        }));
+    }
+    mutateSeat(agencyId, roleId, updater) {
+        const session = this.agencies.get(agencyId);
+        if (!session) {
+            return undefined;
+        }
+        const seat = session.seats[roleId];
+        if (!seat) {
+            return undefined;
+        }
+        const updated = updater(seat);
+        session.seats[roleId] = updated;
+        session.updatedAt = new Date().toISOString();
+        return updated;
+    }
+}
+//# sourceMappingURL=AgencyRegistry.js.map

package/dist/core/agency/AgencyRegistry.js.map

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

package/dist/core/agency/AgencyTypes.d.ts

@@ -0,0 +1,200 @@
+/**
+ * @file AgencyTypes.ts
+ * @description Type definitions for Agency (multi-GMI collective) management.
+ * @module AgentOS/Agency
+ */
+/**
+ * Captures the runtime state of a single seat within an Agency.
+ * A seat represents a role filled by a specific GMI instance.
+ */
+export interface AgencySeatState {
+    /** Unique role identifier within the agency */
+    roleId: string;
+    /** GMI instance currently filling this seat */
+    gmiInstanceId: string;
+    /** Persona configuration for this seat */
+    personaId: string;
+    /** ISO timestamp when GMI was attached to this seat */
+    attachedAt: string;
+    /** Custom metadata for this seat */
+    metadata?: Record<string, unknown>;
+    /** Historical record of seat activity */
+    history?: AgencySeatHistoryEntry[];
+}
+/**
+ * Single history entry for seat activity tracking.
+ */
+export interface AgencySeatHistoryEntry {
+    /** Associated task identifier */
+    taskId?: string;
+    /** ISO timestamp of this entry */
+    timestamp: string;
+    /** Current status of the task */
+    status?: 'pending' | 'running' | 'completed' | 'failed';
+    /** Preview of task output */
+    outputPreview?: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Configuration for agency-level shared RAG memory.
+ * Enables GMIs within an agency to share context and collaborate effectively.
+ */
+export interface AgencyMemoryConfig {
+    /**
+     * Enable shared RAG memory for the agency.
+     * When enabled, all GMIs in the agency can read/write to shared collections.
+     * @default false
+     */
+    enabled: boolean;
+    /**
+     * Dedicated data source ID for agency shared memory.
+     * Auto-generated if not provided when enabled.
+     */
+    sharedDataSourceId?: string;
+    /**
+     * Control which roles can write to shared memory.
+     * If empty/undefined, all roles can write.
+     */
+    writeRoles?: string[];
+    /**
+     * Control which roles can read from shared memory.
+     * If empty/undefined, all roles can read.
+     */
+    readRoles?: string[];
+    /**
+     * Automatically ingest cross-GMI communications to shared memory.
+     * @default false
+     */
+    autoIngestCommunications?: boolean;
+    /**
+     * Retention policy for shared memory documents.
+     */
+    retentionPolicy?: AgencyMemoryRetentionPolicy;
+    /**
+     * Memory scoping configuration.
+     */
+    scoping?: AgencyMemoryScopingConfig;
+}
+/**
+ * Retention policy for agency shared memory.
+ */
+export interface AgencyMemoryRetentionPolicy {
+    /** Maximum age of documents in days before eviction */
+    maxAgeDays?: number;
+    /** Maximum number of documents to retain */
+    maxDocuments?: number;
+    /** Maximum total storage in bytes */
+    maxStorageBytes?: number;
+    /** Strategy for eviction when limits are reached */
+    evictionStrategy?: 'oldest_first' | 'least_accessed' | 'lowest_importance';
+}
+/**
+ * Controls how GMIs scope their RAG queries within an agency.
+ */
+export interface AgencyMemoryScopingConfig {
+    /**
+     * Include agency shared memory in GMI RAG queries.
+     * @default true when agency memory is enabled
+     */
+    includeSharedInQueries?: boolean;
+    /**
+     * Include other GMIs' personal memory in queries (with permission).
+     * @default false
+     */
+    allowCrossGMIQueries?: boolean;
+    /**
+     * Priority weight for shared memory vs personal memory in results.
+     * 0 = personal only, 1 = shared only, 0.5 = equal weight.
+     * @default 0.3
+     */
+    sharedMemoryWeight?: number;
+}
+/**
+ * Represents a collective of GMIs collaborating under a single Agency identity.
+ * Agencies enable multi-agent workflows with shared context and memory.
+ */
+export interface AgencySession {
+    /** Unique agency identifier */
+    agencyId: string;
+    /** Associated workflow instance */
+    workflowId: string;
+    /** Conversation context for this agency */
+    conversationId: string;
+    /** ISO timestamp of creation */
+    createdAt: string;
+    /** ISO timestamp of last update */
+    updatedAt: string;
+    /** GMI seats keyed by role ID */
+    seats: Record<string, AgencySeatState>;
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+    /**
+     * Shared memory configuration for this agency.
+     * @see AgencyMemoryConfig
+     */
+    memoryConfig?: AgencyMemoryConfig;
+}
+/**
+ * Arguments for creating or updating an agency session.
+ */
+export interface AgencyUpsertArgs {
+    /** Associated workflow instance */
+    workflowId: string;
+    /** Conversation context */
+    conversationId: string;
+    /** Explicit agency ID (auto-generated if omitted) */
+    agencyId?: string;
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+    /** Shared memory configuration */
+    memoryConfig?: AgencyMemoryConfig;
+}
+/**
+ * Arguments for registering a GMI to an agency seat.
+ */
+export interface AgencySeatRegistrationArgs {
+    /** Target agency */
+    agencyId: string;
+    /** Role to fill */
+    roleId: string;
+    /** GMI instance to assign */
+    gmiInstanceId: string;
+    /** Persona configuration */
+    personaId: string;
+    /** Seat-specific metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Result of an agency memory operation.
+ */
+export interface AgencyMemoryOperationResult {
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** Number of documents affected */
+    documentsAffected: number;
+    /** Error message if failed */
+    error?: string;
+    /** Operation metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Query options for agency shared memory.
+ */
+export interface AgencyMemoryQueryOptions {
+    /** Query text */
+    query: string;
+    /** Requesting GMI instance ID */
+    requestingGmiId: string;
+    /** Requesting role ID */
+    requestingRoleId: string;
+    /** Maximum results */
+    topK?: number;
+    /** Minimum similarity threshold */
+    threshold?: number;
+    /** Include personal memory in results */
+    includePersonalMemory?: boolean;
+    /** Filter by specific roles' contributions */
+    fromRoles?: string[];
+}
+//# sourceMappingURL=AgencyTypes.d.ts.map

package/dist/core/agency/AgencyTypes.d.ts.map

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

package/dist/core/agency/AgencyTypes.js

@@ -0,0 +1,7 @@
+/**
+ * @file AgencyTypes.ts
+ * @description Type definitions for Agency (multi-GMI collective) management.
+ * @module AgentOS/Agency
+ */
+export {};
+//# sourceMappingURL=AgencyTypes.js.map

package/dist/core/agency/AgencyTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgencyTypes.js","sourceRoot":"","sources":["../../../src/core/agency/AgencyTypes.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}