@makaio/framework 1.0.0-dev-1781022866275 → 1.0.0-dev-1781023871421

package/dist/index-DGBu6bHi2.d.mts

@@ -0,0 +1,438 @@
+import { IMakaioBus } from "@makaio/framework/bus";
+import { IMakaioSession, MakaioSessionAgent, Message, MessageInput, ResponseSchemaDescriptor, SessionContext, TurnInitiator } from "@makaio/framework/contracts";
+
+//#region services/core/src/session/entities/turn.d.ts
+/**
+ * Result of a completed turn.
+ */
+interface TurnResult {
+  /** Whether all agents completed successfully */
+  success: boolean;
+  /** Error messages from agents that failed */
+  errors: string[];
+}
+/**
+ * State change returned by Turn mutation methods.
+ * Orchestrator uses this to decide whether to emit turn.completed.
+ */
+type TurnStateChange = {
+  turnComplete: false;
+} | {
+  turnComplete: true;
+  result: TurnResult;
+};
+/**
+ * Context for dispatching messages to agents.
+ * Passed to agent.sendMessage for context propagation.
+ */
+interface TurnContext {
+  /** Turn identifier */
+  turnId: string;
+  /** Current/latest message ID in this turn */
+  messageId: string;
+}
+/**
+ * Configuration for creating a Turn.
+ */
+interface TurnConfig {
+  /** Session this turn belongs to */
+  sessionId: string;
+  /** Agents participating in this turn */
+  agentIds: string[];
+  /** Monotonic per-session ordinal (1-based), assigned by turn storage. */
+  turnNumber: number;
+  /** Optional turn ID (generated if not provided) */
+  turnId?: string;
+  /** Optional start timestamp (defaults to Date.now()) */
+  startedAt?: number;
+  /** Origin of this turn (for loop prevention and audit). Defaults to user-initiated. */
+  initiator?: TurnInitiator;
+}
+/**
+ * Represents a single turn in a session.
+ *
+ * A turn is a semantic bracket: user message(s) → agent response(s).
+ * Turn encapsulates state and logic, while SessionOrchestrator handles
+ * bus events and emissions.
+ *
+ * Design:
+ * - Immutable identity (turnId, sessionId, agentIds set at creation)
+ * - Mutable state (messages, completion tracking)
+ * - State changes return results for orchestrator to act on
+ * - No bus dependency (testable in isolation)
+ * @example
+ * ```typescript
+ * const turn = new Turn({ sessionId: 'sess1', agentIds: ['agent1', 'agent2'] });
+ * turn.addMessage('msg1');
+ *
+ * const change = turn.markAgentCompleted('agent1');
+ * // change.turnComplete === false (agent2 still pending)
+ *
+ * const change2 = turn.markAgentCompleted('agent2');
+ * // change2.turnComplete === true, change2.result.success === true
+ * ```
+ */
+declare class Turn$1 {
+  /** Unique turn identifier */
+  readonly turnId: string;
+  /** Session this turn belongs to */
+  readonly sessionId: string;
+  /** Monotonic per-session ordinal (1-based). */
+  readonly turnNumber: number;
+  /** Timestamp when turn was created */
+  readonly startedAt: number;
+  /** Origin of this turn, used for loop prevention and audit. */
+  private readonly _initiator;
+  /** Agents participating in this turn (immutable after creation) */
+  private readonly _agentIds;
+  /** Messages sent during this turn */
+  private readonly _messageIds;
+  /** Agents that have completed successfully */
+  private readonly _completedAgents;
+  /** Agents that errored (agentId → error message) */
+  private readonly _erroredAgents;
+  constructor(config: TurnConfig);
+  /**
+   * Agents participating in this turn.
+   * @returns Immutable array of agent IDs
+   */
+  get agentIds(): readonly string[];
+  /**
+   * Origin of this turn for loop prevention and audit.
+   * Returned as a defensive copy to avoid external mutation of internal state.
+   * @returns Defensive copy of turn initiator metadata
+   */
+  get initiator(): TurnInitiator;
+  /**
+   * Messages sent during this turn.
+   * @returns Immutable array of message IDs
+   */
+  get messageIds(): readonly string[];
+  /**
+   * Agents that have completed successfully.
+   * @returns Read-only set of completed agent IDs
+   */
+  get completedAgents(): ReadonlySet<string>;
+  /**
+   * Agents that errored.
+   * @returns Read-only map of agent ID to error message
+   */
+  get erroredAgents(): ReadonlyMap<string, string>;
+  /**
+   * Add a message to this turn.
+   * @param messageId - The message ID to add
+   */
+  addMessage(messageId: string): void;
+  /**
+   * Mark an agent as completed successfully.
+   * @param agentId - The agent that completed
+   * @returns State change indicating if turn is now complete
+   */
+  markAgentCompleted(agentId: string): TurnStateChange;
+  /**
+   * Mark an agent as errored.
+   * @param agentId - The agent that errored
+   * @param error - Error message
+   * @returns State change indicating if turn is now complete
+   */
+  markAgentErrored(agentId: string, error: string): TurnStateChange;
+  /**
+   * Check if an agent is part of this turn.
+   * @param agentId - The agent ID to check
+   * @returns True if agent is participating in this turn
+   */
+  hasAgent(agentId: string): boolean;
+  /**
+   * Check if the turn is complete (all agents finished).
+   * @returns True if all agents have completed or errored
+   */
+  isComplete(): boolean;
+  /**
+   * Get the turn result (only meaningful when turn is complete).
+   * @returns Turn result with success status and any errors
+   */
+  getResult(): TurnResult;
+  /**
+   * Get context for agent dispatch.
+   * Used when sending messages to agents for context propagation.
+   * @returns Turn context with turnId and current messageId
+   * @throws Error if no messages have been added yet
+   */
+  getContext(): TurnContext;
+  /**
+   * Get context for a specific message (for events emitted per-message).
+   * @param messageId - The message ID to get context for
+   * @returns Turn context with turnId and the specified messageId
+   */
+  getContextForMessage(messageId: string): TurnContext;
+  /**
+   * Check if turn should complete and return appropriate state change.
+   * @returns State change indicating completion status and result if complete
+   */
+  private checkCompletion;
+}
+//#endregion
+//#region services/core/src/session/session-turn-manager.d.ts
+/**
+ * Result of a completed turn.
+ */
+interface TurnCompletionResult {
+  /** Whether all agents completed successfully. */
+  success: boolean;
+  /** Error messages from agents that failed. */
+  errors: string[];
+}
+/**
+ * Callback invoked when a turn completes (all agents finished).
+ * @param turn - The completed turn
+ * @param result - Success/error status with error messages
+ */
+type TurnCompleteCallback = (turn: Turn$1, result: TurnCompletionResult) => Promise<void>;
+/**
+ * Composable turn lifecycle manager.
+ *
+ * Owns all stateful turn tracking: active turns, usage accumulation,
+ * completion guards, and buffered-usage-during-completion. Both the
+ * framework `SessionOrchestrator` and host-provided orchestrators create their
+ * own instance.
+ *
+ * Storage calls use `bus.requestOptional` so the manager degrades
+ * gracefully in ephemeral mode (no storage handlers registered). When
+ * `TurnStorageSubjects.create` is unhandled, synthetic IDs are generated
+ * locally. When `TurnStorageSubjects.complete` is unhandled, the turn is
+ * still cleared from memory and `session.turn.completed` is emitted.
+ */
+declare class SessionTurnManager {
+  private readonly bus;
+  /** Active turns keyed by sessionId (one turn per session). */
+  private readonly activeTurns;
+  /** Per-session usage accumulators, parallel to activeTurns. */
+  private readonly usageAccumulators;
+  /** Sessions currently persisting turn completion (prevents concurrent writes). */
+  private readonly completingSessions;
+  /** Usage events received while completion persistence is in-flight. */
+  private readonly bufferedUsageDuringCompletion;
+  /**
+   * Synthetic turn number counters for ephemeral mode (no storage handlers).
+   * Keyed by sessionId, incremented on each turn creation.
+   *
+   * Intentionally never pruned: turn numbers must be monotonically increasing
+   * across all turns in a session. Pruning after a turn completes would reset
+   * the counter and cause duplicate turn numbers if the session continues.
+   */
+  private readonly syntheticTurnCounters;
+  /** Bus subscription cleanup functions. */
+  private readonly cleanups;
+  /**
+   * @param bus - Event bus used for storage RPCs and event emission
+   */
+  constructor(bus: IMakaioBus);
+  /**
+   * Create a new turn, tracking it as active.
+   *
+   * Calls `TurnStorageSubjects.create` via `requestOptional`. If no storage
+   * handler is registered (ephemeral mode), generates a synthetic UUID turn ID
+   * and a per-session incrementing turn number.
+   * @param sessionId - Session the turn belongs to
+   * @param agentIds - Agents participating in this turn
+   * @param initiator - Turn origin metadata (user, plugin, system)
+   * @param turnId - Optional pre-assigned turn ID (passed through to storage)
+   * @returns The newly created and activated Turn entity
+   */
+  createTurn(sessionId: string, agentIds: string[], initiator?: TurnInitiator, turnId?: string): Promise<Turn$1>;
+  /**
+   * Register bus listeners for `agent.usage` and `agent.complete` events.
+   *
+   * Must be called once during initialisation. The `onTurnComplete` callback
+   * is invoked when all agents in a turn have finished (success or error);
+   * typically the orchestrator passes its own `completeTurn` method.
+   * @param onTurnComplete - Callback invoked when all agents in a turn finish
+   */
+  registerCompletionHandlers(onTurnComplete: TurnCompleteCallback): void;
+  /**
+   * Complete a turn: persist via storage, emit `session.turn.completed`, clear state.
+   *
+   * A concurrent-completion guard prevents duplicate writes when two agent
+   * completions race. The second call is a no-op.
+   *
+   * Usage is snapshotted before the storage call. Any usage events that arrive
+   * while persistence is in-flight are buffered and merged into a second
+   * `TurnStorageSubjects.complete` call. State is cleared only after durable
+   * persistence succeeds; if persistence fails, the state remains intact so
+   * completion can be retried.
+   * @param turn - The turn to complete
+   * @param result - Turn result (success status and error messages)
+   */
+  completeTurn(turn: Turn$1, result: TurnCompletionResult): Promise<void>;
+  /**
+   * Get the active turn for a session, if any.
+   * @param sessionId - Session identifier
+   * @returns Active turn, or `undefined` if no turn is in progress
+   */
+  getActiveTurn(sessionId: string): Turn$1 | undefined;
+  /**
+   * Expose the active turns map for handlers that need direct access.
+   *
+   * Used by `registerAttachHandler` which tracks turns started via
+   * `session.agent.attach` (with an `initialMessage`) in the shared map so
+   * that the completion handler can detect when the attached turn finishes.
+   * @returns Reference to the internal active turns map
+   */
+  getActiveTurnsMap(): Map<string, Turn$1>;
+  /**
+   * Find an active turn by turn ID (scans all sessions).
+   *
+   * Used to correlate `agent.usage` events that carry a `turnId` rather
+   * than a `sessionId`.
+   * @param turnId - Turn identifier from an agent event payload
+   * @returns Matching active turn, or `undefined` if not found
+   */
+  findActiveTurnByTurnId(turnId: string): Turn$1 | undefined;
+  /**
+   * Cancel all bus subscriptions and clear all in-memory state.
+   *
+   * Call when the owning orchestrator is destroyed.
+   */
+  destroy(): void;
+  /**
+   * Handle an agent completing (success or error).
+   *
+   * Marks the agent on the turn, emits `user_message.completed` for each
+   * message in the turn, then calls `onTurnComplete` when all agents are done.
+   * @param agentId - The agent that completed
+   * @param success - Whether the agent completed successfully
+   * @param error - Error message if the agent failed
+   * @param onTurnComplete - Callback to invoke when the turn is complete
+   */
+  private handleAgentCompletion;
+  /**
+   * Buffer a usage event that arrived while turn completion persistence is in-flight.
+   * @param sessionId - Session whose turn is currently completing
+   * @param usageEvent - Usage event to defer until after persistence
+   */
+  private bufferUsageDuringCompletion;
+}
+//#endregion
+//#region services/core/src/session/handlers/abandon-handler.d.ts
+/**
+ * Registers the session.abandon RPC handler.
+ *
+ * Abandons a child session without merging (no handoff).
+ * @param bus - Bus instance for communication
+ * @returns Cleanup function to unsubscribe
+ */
+declare function registerAbandonHandler(bus: IMakaioBus): () => void;
+//#endregion
+//#region services/core/src/session/handlers/attach-handler.d.ts
+/**
+ * Registers the session.agent.attach RPC handler.
+ *
+ * Explicitly attaches a fresh agent to a session with full control over:
+ * - Role assignment (lead vs member)
+ * - Optional initial message
+ *
+ * For branching conversations (fork), use session.fork to create a new session
+ * with copied history, then attach agents to the new session.
+ * @param bus - Bus instance for communication
+ * @param activeTurns - Shared turn state map
+ * @param machineId - Optional machine ID for deterministic adapter resolution
+ * @returns Cleanup function to unsubscribe
+ */
+declare function registerAttachHandler(bus: IMakaioBus, activeTurns: Map<string, Turn$1>, machineId?: string): () => void;
+//#endregion
+//#region services/core/src/session/handlers/compress-handler.d.ts
+/**
+ * Registers the session.compress RPC handler.
+ *
+ * Executes a pipeline on session messages and inserts a squash event.
+ * The squash event marks a context boundary - messages before it
+ * are summarized by the context JSON.
+ * @param bus - Bus instance
+ * @returns Cleanup function
+ */
+declare function registerCompressHandler(bus: IMakaioBus): () => void;
+//#endregion
+//#region services/core/src/session/handlers/fork-handler.d.ts
+/**
+ * Registers the session.fork RPC handler.
+ *
+ * Creates a new session with parent reference. The forked session starts
+ * empty - its full conversation is assembled by traversing the parent chain.
+ * @param bus - Bus instance for communication
+ * @returns Cleanup function to unsubscribe
+ */
+declare function registerForkHandler(bus: IMakaioBus): () => void;
+//#endregion
+//#region services/core/src/session/handlers/merge-handler.d.ts
+/**
+ * Registers the session.merge RPC handler.
+ *
+ * Merges a child session's work back into parent with a handoff summary.
+ * @param bus - Bus instance for communication
+ * @returns Cleanup function to unsubscribe
+ */
+declare function registerMergeHandler(bus: IMakaioBus): () => void;
+//#endregion
+//#region services/core/src/session/handlers/route-to-agents.d.ts
+/**
+ * Interface for turn context enrichment.
+ * Implemented by TurnContextEnricher in orchestration package.
+ */
+interface ITurnContextEnricher {
+  enrichForDeliveryMode(originalHistory: Message[] | undefined, turnId: string, deliveryMode: 'enqueue' | 'immediate' | 'replace' | undefined): Promise<Message[] | undefined>;
+}
+interface CwdSwapMeta {
+  previousCwd: string;
+  newCwd: string;
+}
+/**
+ * Route a message to target agents via agent.sendMessage.
+ *
+ * Fans out to all agents in parallel. On routing failure, marks agent as errored
+ * and checks for turn completion.
+ *
+ * For fork sessions on their first turn, assembles projected context from parent chain.
+ * @param bus - Bus instance for communication
+ * @param session - Session metadata (for fork detection)
+ * @param agents - Target agents to route to
+ * @param message - Message content to send
+ * @param messageId - Message identifier
+ * @param turn - Turn tracking object
+ * @param deliveryMode - How to deliver the message
+ * @param onTurnComplete - Callback when turn completes (all agents done)
+ * @param sessionContext - Session context with curated messageHistory and decision signals
+ * @param turnContextEnricher - Optional enricher for immediate message context
+ * @param isNewTurn - Whether this is the first message in a new turn
+ * @param recoveryContext - Context enriched with messageHistory for agents that were just recovered
+ * @param recoveredAgentIds - Set of agent IDs that were recovered in this handler invocation
+ * @param swappedAgentIds - Set of agent IDs that swapped connector due to cwd mismatch
+ * @param swappedAgentCwd - Previous/new cwd metadata keyed by agent ID
+ * @param freshMessageHistory - Curated history for agents forced into fresh mode
+ * @param responseSchema - Optional structured output descriptor for the turn
+ */
+declare function routeToAgents(bus: IMakaioBus, session: IMakaioSession, agents: MakaioSessionAgent[], message: MessageInput, messageId: string, turn: Turn$1, deliveryMode: 'enqueue' | 'immediate' | undefined, onTurnComplete: (turn: Turn$1, result: {
+  success: boolean;
+  errors: string[];
+}) => Promise<void>, sessionContext?: SessionContext, turnContextEnricher?: ITurnContextEnricher, isNewTurn?: boolean, recoveryContext?: SessionContext, recoveredAgentIds?: ReadonlySet<string>, swappedAgentIds?: ReadonlySet<string>, swappedAgentCwd?: ReadonlyMap<string, CwdSwapMeta>, freshMessageHistory?: Message[], responseSchema?: ResponseSchemaDescriptor): Promise<void>;
+//#endregion
+//#region services/core/src/session/handlers/route-to-agents-core.d.ts
+/**
+ * Route a message to target agents using a single shared session context.
+ *
+ * Fans out to all agents in parallel. On routing failure, marks the agent
+ * as errored and checks for turn completion. On `HookAbortError`, marks
+ * the agent as completed with `cancelled` outcome.
+ * @param bus - Bus instance for communication
+ * @param session - Session metadata (for session ID)
+ * @param agents - Target agents to route to
+ * @param message - Message content to send
+ * @param messageId - Message identifier
+ * @param turn - Turn tracking object
+ * @param deliveryMode - How to deliver the message to the agent
+ * @param onTurnComplete - Callback invoked when the turn completes (all agents done)
+ * @param sessionContext - Optional shared session context forwarded to all agents
+ * @param responseSchema - Optional structured output descriptor for the turn
+ */
+declare function routeToAgentsCore(bus: IMakaioBus, session: IMakaioSession, agents: MakaioSessionAgent[], message: MessageInput, messageId: string, turn: Turn$1, deliveryMode: 'enqueue' | 'immediate' | undefined, onTurnComplete: TurnCompleteCallback, sessionContext?: SessionContext, responseSchema?: ResponseSchemaDescriptor): Promise<void>;
+//#endregion
+export { registerCompressHandler as a, SessionTurnManager as c, Turn$1 as d, TurnConfig as f, TurnStateChange as h, registerForkHandler as i, TurnCompleteCallback as l, TurnResult as m, routeToAgents as n, registerAttachHandler as o, TurnContext as p, registerMergeHandler as r, registerAbandonHandler as s, routeToAgentsCore as t, TurnCompletionResult as u };

package/dist/index-DKC62dY5.d.mts

@@ -0,0 +1,146 @@
+import * as _$zod from "zod";
+import { z } from "zod";
+import * as _$_makaio_core0 from "@makaio/framework/core";
+import * as _$zod_v4_core0 from "zod/v4/core";
+
+//#region core/contracts/src/telemetry/namespace.d.ts
+/** Framework contract namespace for sanitized bus subject telemetry facts. */
+declare const SubjectTelemetryNamespace: _$_makaio_core0.BusNamespaceDefinition<"subject-telemetry", {
+  fact: _$_makaio_core0.CollectorOnlySubjectSchema<_$zod.ZodObject<{
+    factId: _$zod.ZodString;
+    observedAt: _$zod.ZodNumber;
+    machineId: _$zod.ZodOptional<_$zod.ZodString>;
+    namespace: _$zod.ZodString;
+    subject: _$zod.ZodString;
+    messageType: _$zod.ZodEnum<{
+      request: "request";
+      event: "event";
+      broadcast: "broadcast";
+    }>;
+    direction: _$zod.ZodEnum<{
+      local: "local";
+      outbound: "outbound";
+      inbound: "inbound";
+    }>;
+    messageId: _$zod.ZodString;
+    correlationId: _$zod.ZodOptional<_$zod.ZodString>;
+    attributes: _$zod.ZodRecord<_$zod.ZodString, _$zod.ZodUnion<readonly [_$zod.ZodString, _$zod.ZodNumber, _$zod.ZodBoolean, _$zod.ZodNull, _$zod.ZodArray<_$zod.ZodString>, _$zod.ZodArray<_$zod.ZodNumber>, _$zod.ZodArray<_$zod.ZodBoolean>, _$zod.ZodArray<_$zod.ZodNull>]>>;
+  }, _$zod_v4_core0.$strict>>;
+}>;
+/** Typed subjects for sanitized bus subject telemetry facts. */
+declare const SubjectTelemetrySubjects: _$_makaio_core0.BusSubjects<_$_makaio_core0.FlatSubjectDefinitions<"subject-telemetry", {
+  fact: _$_makaio_core0.CollectorOnlySubjectSchema<_$zod.ZodObject<{
+    factId: _$zod.ZodString;
+    observedAt: _$zod.ZodNumber;
+    machineId: _$zod.ZodOptional<_$zod.ZodString>;
+    namespace: _$zod.ZodString;
+    subject: _$zod.ZodString;
+    messageType: _$zod.ZodEnum<{
+      request: "request";
+      event: "event";
+      broadcast: "broadcast";
+    }>;
+    direction: _$zod.ZodEnum<{
+      local: "local";
+      outbound: "outbound";
+      inbound: "inbound";
+    }>;
+    messageId: _$zod.ZodString;
+    correlationId: _$zod.ZodOptional<_$zod.ZodString>;
+    attributes: _$zod.ZodRecord<_$zod.ZodString, _$zod.ZodUnion<readonly [_$zod.ZodString, _$zod.ZodNumber, _$zod.ZodBoolean, _$zod.ZodNull, _$zod.ZodArray<_$zod.ZodString>, _$zod.ZodArray<_$zod.ZodNumber>, _$zod.ZodArray<_$zod.ZodBoolean>, _$zod.ZodArray<_$zod.ZodNull>]>>;
+  }, _$zod_v4_core0.$strict>>;
+}>, "subject-telemetry">;
+//#endregion
+//#region core/contracts/src/telemetry/schemas.d.ts
+/**
+ * Scalar attribute value allowed in a telemetry fact.
+ *
+ * Restricted to primitives and homogeneous primitive arrays so that the
+ * telemetry sink can safely serialize without inspecting arbitrary objects.
+ */
+declare const SubjectTelemetryAttributeValueSchema: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodArray<z.ZodString>, z.ZodArray<z.ZodNumber>, z.ZodArray<z.ZodBoolean>, z.ZodArray<z.ZodNull>]>;
+/** Inferred TypeScript type for a sanitized attribute value. */
+type SubjectTelemetryAttributeValue = z.infer<typeof SubjectTelemetryAttributeValueSchema>;
+/**
+ * Bus message kind projected into a telemetry fact.
+ * Covers local bus API entrypoints observed by this MVP.
+ */
+declare const SubjectTelemetryMessageTypeSchema: z.ZodEnum<{
+  request: "request";
+  event: "event";
+  broadcast: "broadcast";
+}>;
+/**
+ * Flow direction of the observed message at the source runtime.
+ *
+ * - `local` — originated and consumed within the same runtime.
+ * - `outbound` — dispatched to a remote peer.
+ * - `inbound` — received from a remote peer.
+ */
+declare const SubjectTelemetryDirectionSchema: z.ZodEnum<{
+  local: "local";
+  outbound: "outbound";
+  inbound: "inbound";
+}>;
+/**
+ * Sanitized bus subject telemetry fact schema.
+ *
+ * A fact captures the observable, non-sensitive metadata of a single bus
+ * message. All payload content is excluded; only correlation handles and
+ * namespace-approved scalar attributes are present.
+ */
+declare const SubjectTelemetryFactSchema: z.ZodObject<{
+  factId: z.ZodString;
+  observedAt: z.ZodNumber;
+  machineId: z.ZodOptional<z.ZodString>;
+  namespace: z.ZodString;
+  subject: z.ZodString;
+  messageType: z.ZodEnum<{
+    request: "request";
+    event: "event";
+    broadcast: "broadcast";
+  }>;
+  direction: z.ZodEnum<{
+    local: "local";
+    outbound: "outbound";
+    inbound: "inbound";
+  }>;
+  messageId: z.ZodString;
+  correlationId: z.ZodOptional<z.ZodString>;
+  attributes: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodArray<z.ZodString>, z.ZodArray<z.ZodNumber>, z.ZodArray<z.ZodBoolean>, z.ZodArray<z.ZodNull>]>>;
+}, z.core.$strict>;
+/** Inferred TypeScript type for a sanitized bus subject telemetry fact. */
+type SubjectTelemetryFact = z.infer<typeof SubjectTelemetryFactSchema>;
+/**
+ * Subject telemetry domain bus schemas aggregate.
+ *
+ * Each key becomes a subject identifier as `subject-telemetry.<key>`.
+ */
+declare const SubjectTelemetrySchemas: {
+  /**
+   * A single sanitized telemetry fact emitted by the projection layer.
+   * Event: transport-ingestable by collectors, never laterally relayed.
+   */
+  fact: _$_makaio_core0.CollectorOnlySubjectSchema<z.ZodObject<{
+    factId: z.ZodString;
+    observedAt: z.ZodNumber;
+    machineId: z.ZodOptional<z.ZodString>;
+    namespace: z.ZodString;
+    subject: z.ZodString;
+    messageType: z.ZodEnum<{
+      request: "request";
+      event: "event";
+      broadcast: "broadcast";
+    }>;
+    direction: z.ZodEnum<{
+      local: "local";
+      outbound: "outbound";
+      inbound: "inbound";
+    }>;
+    messageId: z.ZodString;
+    correlationId: z.ZodOptional<z.ZodString>;
+    attributes: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodArray<z.ZodString>, z.ZodArray<z.ZodNumber>, z.ZodArray<z.ZodBoolean>, z.ZodArray<z.ZodNull>]>>;
+  }, z.core.$strict>>;
+};
+//#endregion
+export { SubjectTelemetryFactSchema as a, SubjectTelemetryNamespace as c, SubjectTelemetryFact as i, SubjectTelemetrySubjects as l, SubjectTelemetryAttributeValueSchema as n, SubjectTelemetryMessageTypeSchema as o, SubjectTelemetryDirectionSchema as r, SubjectTelemetrySchemas as s, SubjectTelemetryAttributeValue as t };

package/dist/index-DKia0MX1.d.mts

@@ -0,0 +1,43 @@
+import { IMakaioBus } from "@makaio/framework/bus";
+import { BaseService } from "@makaio/framework/service-base";
+
+//#region services/core/src/tray-menu/tray-menu-service.d.ts
+/**
+ * In-memory registry for package-contributed tray menu entries.
+ *
+ * Registrations are idempotent and keyed by owning package. The service owns
+ * tray menu state for every host surface; renderers consume it through the
+ * `host:tray.list` RPC and observe mutations through `host:tray.changed`.
+ */
+declare class TrayMenuService extends BaseService {
+  /** Dependency tokens required before this service. */
+  static readonly needs: readonly [];
+  static readonly critical: true;
+  /**
+   * Factory for DI container startup.
+   * @param ctx - Start context providing the bus
+   * @returns Initialized TrayMenuService instance
+   */
+  static create(ctx: {
+    bus: IMakaioBus;
+  }): Promise<TrayMenuService>;
+  private readonly entries;
+  private readonly groups;
+  private readonly groupEntryIds;
+  /**
+   * Create a tray menu service.
+   * @param bus - Bus instance used for tray menu subjects
+   */
+  constructor(bus: IMakaioBus);
+  protected onInit(): void;
+  protected onDestroy(): void;
+  private listEntries;
+  private assertEntryCanRegister;
+  private assertGroupCanRegister;
+  private collectGroupEntryIds;
+  private emitChanged;
+  private entryKey;
+  private groupKey;
+}
+//#endregion
+export { TrayMenuService as t };

package/dist/index-DMKnON5s.d.mts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+
+//#region core/contracts/src/timeout/schemas.d.ts
+/**
+ * Categories of timeouts in the adapter lifecycle.
+ */
+type TimeoutCategory = 'initialization' | 'acknowledgement' | 'completion' | 'toolApproval' | 'eventWait';
+/**
+ * Complete timeout configuration where all categories are required.
+ */
+type RequiredTimeoutConfig = Record<TimeoutCategory, number>;
+/**
+ * Partial timeout configuration for user overrides.
+ */
+type TimeoutConfig = Partial<RequiredTimeoutConfig>;
+/**
+ * Zod schema for timeout configuration validation.
+ *
+ * Each field represents a distinct phase in the adapter lifecycle
+ * with different performance characteristics and failure modes.
+ * All values are in milliseconds.
+ *
+ * Contracts owns this public shape so downstream consumers do not need utility
+ * implementation packages to resolve generated declarations.
+ */
+declare const TimeoutConfigSchema: z.ZodType<TimeoutConfig>;
+//#endregion
+export { TimeoutConfigSchema as i, TimeoutCategory as n, TimeoutConfig as r, RequiredTimeoutConfig as t };