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

package/dist/index-BGfWS6GE.d.mts

@@ -0,0 +1,483 @@
+import { TransportPeerContext } from "@makaio/framework/core";
+import { IMakaioBus } from "@makaio/framework/bus";
+import * as _$_makaio_contracts0 from "@makaio/framework/contracts";
+import { MakaioNodeExtension, PendingRequest, SubagentConfig, SubagentConstraints, SubagentStatus } from "@makaio/framework/contracts";
+import { BaseService } from "@makaio/framework/service-base";
+
+//#region services/core/src/subagent/spawn-delegation.d.ts
+/**
+ * Set of authenticated peer identities that are authorised to request
+ * subagent spawning or execution on behalf of a remote caller.
+ *
+ * Entries are keyed on the `kind:id` pair of the peer (for example
+ * `workflow-execution:exec-abc-123`). The empty set denies all remote callers.
+ */
+type SpawnDelegationAllowSet = Set<string>;
+/**
+ * Determine whether a remote peer is authorised to request subagent
+ * spawning / execution on this node.
+ *
+ * Workflow execution peers are authorised by identity because they represent
+ * the runner that owns the workflow agent step. Other peer kinds are
+ * authorised only when their `kind:id` pair matches the explicit allow-set.
+ * @param peer - Authenticated peer context from the incoming transport message.
+ * @param allowSet - Allow-set configured for this SubagentService instance.
+ * @returns `true` when the peer may delegate spawn/execute requests.
+ */
+declare function isPeerAuthorizedToDelegate(peer: TransportPeerContext | undefined, allowSet: SpawnDelegationAllowSet): boolean;
+//#endregion
+//#region services/core/src/subagent/subagent-service.d.ts
+/**
+ * Orchestrates subagent execution lifecycle.
+ *
+ * Owns SubagentManager and handles:
+ * - Session creation on spawn
+ * - Adapter startup on spawn
+ * - Message routing (toChild \> child session)
+ * - Cleanup on completion/cancellation
+ */
+declare class SubagentService extends BaseService {
+  private readonly machineId?;
+  private readonly delegationAllowSet;
+  /** Manager is now private - tools use RPCs to interact with state */
+  private readonly manager;
+  private readonly pendingChildSessionClose;
+  /**
+   * Creates a new SubagentService instance.
+   * @param bus - The event bus for inter-service communication
+   * @param constraints - Subagent execution constraints
+   * @param machineId - Optional machine ID for adapter resolution
+   * @param delegationAllowSet - Set of peer identities permitted to request
+   *   spawn or execute on this node from a remote origin. Authenticated
+   *   `workflow-execution` peers are allowed by identity; this set is for
+   *   additional delegated peer kinds.
+   */
+  constructor(bus?: IMakaioBus, constraints?: SubagentConstraints, machineId?: string | undefined, delegationAllowSet?: SpawnDelegationAllowSet);
+  /**
+   * Grant an authenticated peer permission to delegate spawn/execute requests.
+   *
+   * Adds the canonical `kind:id` key to the allow-set so subsequent remote
+   * calls from this peer pass the delegation guard.
+   * @param kind - Peer kind (e.g. `'workflow-execution'`)
+   * @param id - Peer identifier
+   */
+  grantDelegation(kind: string, id: string): void;
+  /**
+   * Revoke delegation permission for an authenticated peer.
+   *
+   * Removes the canonical `kind:id` key from the allow-set. Subsequent
+   * remote calls from this peer will be denied by the delegation guard.
+   * @param kind - Peer kind (e.g. `'workflow-execution'`)
+   * @param id - Peer identifier
+   */
+  revokeDelegation(kind: string, id: string): void;
+  /**
+   * Register bus handlers for subagent lifecycle management.
+   */
+  protected onInit(): void;
+  /**
+   * Wire periodic sweep and cleanup interval.
+   * Uses addCleanup so interval is cleared on destroy().
+   */
+  private wirePeriodicSweep;
+  /**
+   * Register RPC handlers for state operations.
+   * Tools interact with subagent state through these RPCs.
+   */
+  private registerRpcHandlers;
+  /** Clear deferred close state when the service lifecycle shuts down. */
+  protected onDestroy(): void;
+  /**
+   * Handle spawned event - create session and start agent.
+   * @param payload - Spawned event payload
+   * @returns Error message on failure, undefined on success
+   */
+  private handleSpawned;
+  /**
+   * Creates the child session and updates tracked subagent state.
+   * @param subagentId - Subagent identifier
+   * @param parentSessionId - Parent session identifier
+   * @param config - Parsed subagent config
+   * @param executionTargetId - Resolved execution target ID
+   * @param resolutionParams - Framework execution-target fallback fields
+   * @param spawningToolCallId - Tool call ID that triggered the spawn, if available
+   * @returns Created child session ID
+   */
+  private createChildSessionForSpawn;
+  /**
+   * Starts the adapter agent in the newly created child session.
+   * @param adapterName - Adapter type name
+   * @param config - Parsed subagent config
+   * @param sessionId - Child session ID
+   * @param task - Initial task message
+   * @returns Resolves when adapter start succeeds
+   * @throws Error when adapter startup fails
+   */
+  private startAdapterForSubagent;
+  /**
+   * Marks subagent spawn as failed and emits the lifecycle failure event.
+   * @param subagentId - Subagent identifier
+   * @param parentSessionId - Parent session identifier
+   * @param phase - Spawn phase where failure occurred
+   * @param reason - Error object or message
+   * @returns Normalized error message
+   */
+  private failSpawn;
+  /**
+   * Build execution-target resolution parameters for subagent spawn.
+   *
+   * Priority:
+   * 1. Explicit subagent `executionTargetId`
+   * 2. Parent session stamped target + context
+   * @param parentSessionId - Parent session used as fallback context.
+   * @param executionTargetId - Optional explicit target override from subagent config.
+   * @returns Resolution parameters for `ExecutionTargetSubjects.resolve`.
+   */
+  private buildExecutionTargetResolutionParams;
+  /**
+   * Build child session creation payload from subagent config.
+   *
+   * `parentSessionId` always records the session graph relation. The separate
+   * contextInheritance field controls whether parent conversation history is
+   * assembled for the child's first turn.
+   * @param parentSessionId - Parent session identifier from the spawn request
+   * @param config - Parsed subagent config
+   * @param executionTargetId - Resolved execution target to stamp on child session
+   * @param spawningToolCallId - Tool call ID that triggered the spawn, if available
+   * @returns Session.create payload for the child session
+   */
+  private buildChildSessionCreatePayload;
+  private handleExecute;
+  /**
+   * Route a message from parent to child subagent session.
+   * @param payload - Message routing payload
+   */
+  private handleToChild;
+  /**
+   * Handle terminal successful subagent completion.
+   * @param subagentId - Completed subagent identifier.
+   */
+  private handleCompleted;
+  /**
+   * Handle terminal subagent cancellation.
+   * @param subagentId - Cancelled subagent identifier.
+   */
+  private handleCancelled;
+  /**
+   * Close a subagent child session once the subagent reaches a terminal state.
+   *
+   * The close operation is best-effort because subagent state has already
+   * transitioned terminal; a session-close failure should not undo completion
+   * or cancellation.
+   * @param subagentId - Subagent whose child session should be closed.
+   */
+  private closeChildSession;
+  /**
+   * Check whether a subagent has reached a terminal status.
+   * @param status - Subagent status to inspect.
+   * @returns True when the subagent should no longer start or route child work.
+   */
+  private isTerminalSubagentStatus;
+  /**
+   * Handle adapter session close events to detect dead child processes.
+   *
+   * When an adapter session closes, find any tracked subagent whose
+   * childSessionId matches and transition it to failed if still active.
+   * @param sessionId - The session ID reported by the adapter as closed
+   */
+  private handleAdapterSessionClosed;
+  /**
+   * Return true when a handler may proceed.
+   *
+   * Local callers always proceed. Remote callers proceed only when they are an
+   * authenticated workflow execution peer or their authenticated peer appears
+   * in the delegation allow-set.
+   * @param ctx - Incoming message context
+   * @returns True when the handler should process the request
+   */
+  private isRemoteDelegationAllowed;
+  private emitExecutionFailed;
+}
+//#endregion
+//#region services/core/src/subagent/package.d.ts
+/** Token for the framework subagent orchestration service. */
+declare const SubagentServiceToken: _$_makaio_contracts0.ExtensionToken<SubagentService>;
+/**
+ * MakaioNodeExtension<IMakaioBus> manifest for {@link SubagentService}.
+ *
+ * Subagent orchestration runs in headless mode — it does not require a UI
+ * shell but does require the node runtime for process management.
+ * The services-core manifest intentionally uses a service-specific export
+ * name; `@makaio/extension-subagent` continues to own the tool-extension
+ * `subagentPackage` export.
+ */
+declare const subagentServicePackage: MakaioNodeExtension<IMakaioBus>;
+//#endregion
+//#region services/core/src/subagent/utils/ring-buffer.d.ts
+/**
+ * Simple ring buffer with fixed maximum size.
+ * When full, oldest items are dropped to make room for new ones.
+ * @typeParam T - Type of items stored in the buffer
+ */
+declare class RingBuffer<T> {
+  private readonly maxSize;
+  private items;
+  /**
+   * Creates a new RingBuffer.
+   * @param maxSize - Maximum number of items to store (default: 50)
+   */
+  constructor(maxSize?: number);
+  /**
+   * Add an item to the buffer.
+   * If at capacity, the oldest item is dropped.
+   * @param item - Item to add
+   */
+  push(item: T): void;
+  /**
+   * Get all items as an array (oldest first).
+   * @returns Copy of the internal array
+   */
+  toArray(): T[];
+  /**
+   * Current number of items in the buffer.
+   * @returns Number of items currently stored
+   */
+  get length(): number;
+  /**
+   * Remove all items from the buffer.
+   */
+  clear(): void;
+}
+//#endregion
+//#region services/core/src/subagent/manager/types.d.ts
+/**
+ * Internal resolver type for pending request_input.
+ * Called with the response string, or null if timed out or cancelled.
+ */
+type InputResolver = (response: string | null) => void;
+/**
+ * Internal pending request with resolver callback.
+ */
+interface InternalPendingRequest extends PendingRequest {
+  /** Callback to resolve the pending request_input promise. */
+  resolver: InputResolver;
+}
+/**
+ * Tracked runtime state for a spawned subagent.
+ */
+interface TrackedSubagent {
+  /** Unique identifier for this subagent. */
+  subagentId: string;
+  /** Parent session that spawned this subagent. */
+  parentSessionId: string;
+  /** Child session running this subagent. */
+  childSessionId?: string;
+  /** Current status of the subagent. */
+  status: SubagentStatus;
+  /** Configuration used to spawn this subagent. */
+  config: SubagentConfig;
+  /** Nesting depth in the subagent hierarchy. */
+  depth: number;
+  /** Active request_input state, if the child is waiting for parent input. */
+  pendingRequest?: InternalPendingRequest;
+  /** Recent progress updates. */
+  progressUpdates: RingBuffer<string>;
+  /** Final result if completed successfully. */
+  result?: string;
+  /** Optional completion summary. */
+  summary?: string;
+  /** Error message if failed. */
+  error?: string;
+  /** Timestamp when the subagent was spawned. */
+  startTime: number;
+  /** Timestamp when the subagent reached a terminal state. */
+  endTime?: number;
+  /** Timestamp of the last state mutation. */
+  lastActivityAt: number;
+}
+/**
+ * Options for spawning a subagent.
+ */
+interface SpawnOptions extends SubagentConfig {
+  /** Parent session spawning this subagent. */
+  parentSessionId: string;
+}
+/**
+ * Result from awaiting subagent completion.
+ */
+interface AwaitResult {
+  /** Final status when await returned. */
+  status: 'completed' | 'failed' | 'waiting_input' | 'timeout' | 'cancelled';
+  /** Result if completed successfully. */
+  result?: string;
+  /** Pending request if status is waiting_input. */
+  pendingRequest?: PendingRequest;
+  /** Error message if failed. */
+  error?: string;
+}
+//#endregion
+//#region services/core/src/subagent/manager/subagent-manager.d.ts
+/**
+ * Options for tracking a new subagent.
+ */
+interface TrackOptions {
+  /** Unique identifier for the subagent */
+  subagentId: string;
+  /** Parent session that spawned this subagent */
+  parentSessionId: string;
+  /** Configuration used to spawn this subagent */
+  config: SubagentConfig;
+  /** Nesting depth in subagent hierarchy */
+  depth: number;
+}
+/**
+ * Manages tracked subagent state.
+ *
+ * Similar pattern to ShellManager - tracks active subagents, handles lifecycle.
+ * Responsible for:
+ * - Tracking subagent state
+ * - Managing pending request_input
+ * - Coordinating awaiters for completion
+ * - Cleanup of stale completed subagents
+ */
+declare class SubagentManager {
+  readonly constraints: SubagentConstraints;
+  private subagents;
+  private awaiters;
+  constructor(constraints: SubagentConstraints);
+  /**
+   * Track a new subagent.
+   * childSessionId is set later by SubagentService after session creation.
+   * @param options - Tracking options
+   * @returns The tracked subagent state
+   */
+  track(options: TrackOptions): TrackedSubagent;
+  /**
+   * Set the child session ID after session creation.
+   * Called by SubagentService after creating the session.
+   * @param subagentId - ID of the subagent
+   * @param childSessionId - Session ID created by session service
+   */
+  setChildSessionId(subagentId: string, childSessionId: string): void;
+  /**
+   * Get tracked subagent by ID.
+   * @param subagentId - ID of the subagent
+   * @returns The tracked subagent, or undefined if not found
+   */
+  get(subagentId: string): TrackedSubagent | undefined;
+  /**
+   * Return all non-terminal subagents as an array.
+   *
+   * Non-terminal means any status not in `TERMINAL_STATES` (`completed`, `failed`, `cancelled`).
+   * This includes `'hung'`, so results (and derived counts from `countActiveBySession`
+   * and `countTotalActive`) represent "not terminal" rather than "currently doing useful work".
+   *
+   * Used for lookups that need to scan active state (e.g. session close detection).
+   * @returns Array of tracked subagents not yet in a terminal state
+   */
+  getAllNonTerminal(): TrackedSubagent[];
+  /**
+   * Count non-terminal subagents for a parent session.
+   *
+   * Includes `'hung'` because `'hung'` is not part of `TERMINAL_STATES`.
+   * @param parentSessionId - Parent session ID
+   * @returns Count of non-terminal subagents
+   */
+  countActiveBySession(parentSessionId: string): number;
+  /**
+   * Count total non-terminal subagents across all sessions.
+   *
+   * Includes `'hung'` because `'hung'` is not part of `TERMINAL_STATES`.
+   * @returns Total count of non-terminal subagents
+   */
+  countTotalActive(): number;
+  /**
+   * Update subagent status.
+   * Sets endTime if transitioning to a terminal state.
+   * @param subagentId - ID of the subagent
+   * @param status - New status
+   */
+  updateStatus(subagentId: string, status: SubagentStatus): void;
+  /**
+   * Add a progress update to the subagent's ring buffer.
+   * @param subagentId - ID of the subagent
+   * @param update - Progress update message
+   */
+  addProgress(subagentId: string, update: string): void;
+  /**
+   * Set pending request (enforces single-request invariant).
+   * @param subagentId - ID of the subagent
+   * @param request - The pending request with resolver
+   * @throws SubagentError if subagent not found or request already pending
+   */
+  setPendingRequest(subagentId: string, request: InternalPendingRequest): void;
+  /**
+   * Resolve pending request with response.
+   * @param subagentId - ID of the subagent
+   * @param response - Response string, or null if timed out/cancelled
+   */
+  resolvePendingRequest(subagentId: string, response: string | null): void;
+  /**
+   * Mark subagent as completed.
+   * @param subagentId - ID of the subagent
+   * @param result - Result string
+   * @param summary - Optional summary of the result
+   * @throws SubagentError if subagent not found or already in terminal state
+   */
+  markCompleted(subagentId: string, result: string, summary?: string): void;
+  /**
+   * Mark subagent as failed.
+   * Does nothing if subagent not found or already in a terminal state.
+   * @param subagentId - ID of the subagent
+   * @param error - Error message
+   */
+  markFailed(subagentId: string, error: string): void;
+  /**
+   * Mark subagent as cancelled.
+   * Resolves any pending request with null.
+   * @param subagentId - ID of the subagent
+   * @returns true if cancelled, false if not found or already terminal
+   */
+  markCancelled(subagentId: string): boolean;
+  /**
+   * Register an awaiter callback for subagent completion.
+   * @param subagentId - ID of the subagent
+   * @param callback - Callback to invoke when subagent reaches terminal state
+   */
+  addAwaiter(subagentId: string, callback: (result: AwaitResult) => void): void;
+  /**
+   * Remove an awaiter callback for a subagent.
+   * Used for cleanup when await times out before subagent reaches terminal state.
+   * @param subagentId - ID of the subagent
+   * @param callback - The callback to remove
+   * @returns true if the callback was found and removed
+   */
+  removeAwaiter(subagentId: string, callback: (result: AwaitResult) => void): boolean;
+  /**
+   * Resolve all awaiters for a subagent.
+   * @param subagentId - ID of the subagent
+   */
+  private resolveAwaiters;
+  /**
+   * Cleanup old completed subagents based on retention TTL.
+   * @returns Number of subagents cleaned up
+   */
+  cleanup(): number;
+  /**
+   * Sweep for hung subagents that have had no state activity within the timeout window.
+   *
+   * Transitions `spawning` and `running` subagents to `'hung'` (non-terminal).
+   * `waiting_input` subagents are skipped — `request_input` owns their timeout.
+   * Already-hung subagents are also skipped to avoid redundant transitions.
+   *
+   * The coordinator observes `'hung'` via `getStatus` and decides whether to kill
+   * and retry or abort. Awaiters are NOT resolved — `'hung'` is non-terminal.
+   *
+   * When `inactivityTimeoutMs` is less than or equal to 0 this is a no-op (sweep is opt-in).
+   * @param inactivityTimeoutMs - Inactivity threshold in milliseconds. Values less than or equal to 0 disable sweep.
+   * @returns Number of subagents transitioned to `'hung'`
+   */
+  sweepHung(inactivityTimeoutMs: number): number;
+}
+//#endregion
+export { InternalPendingRequest as a, SubagentServiceToken as c, SpawnDelegationAllowSet as d, isPeerAuthorizedToDelegate as f, InputResolver as i, subagentServicePackage as l, TrackOptions as n, SpawnOptions as o, AwaitResult as r, TrackedSubagent as s, SubagentManager as t, SubagentService as u };

package/dist/index-BVgfS-AJ.d.mts

@@ -0,0 +1,109 @@
+import { IMakaioBus } from "@makaio/framework/bus";
+import { HarnessDefinition, MakaioSessionAgent } from "@makaio/framework/contracts";
+import { BaseService } from "@makaio/framework/service-base";
+import { FileAccessRuleProvider } from "@makaio/framework/tools";
+
+//#region services/core/src/tool-approval/tool-approval-types.d.ts
+/** Configuration options for {@link ToolApprovalService}. */
+interface ToolApprovalServiceOptions {
+  /**
+   * Provider for file access rules derived from `.makaioignore` files.
+   * When supplied, enforces file-access restrictions as an absolute pre-check
+   * that runs before any policy cascade — including `full-access` policies.
+   */
+  fileAccessRuleProvider?: FileAccessRuleProvider;
+}
+//#endregion
+//#region services/core/src/tool-approval/tool-approval-service.d.ts
+/**
+ * Resolves and applies tool approval policies based on the
+ * persona → profile → harness → system default cascade.
+ *
+ * Replaces the blanket auto-approve handler that was previously
+ * in bus-server. Registered in the core runtime lifecycle.
+ *
+ * When a file access rule provider is configured,
+ * `.makaioignore` rules are evaluated before the policy cascade as an absolute
+ * deny layer — no policy (not even `full-access`) can bypass them.
+ */
+declare class ToolApprovalService extends BaseService {
+  /** Minimal logger seam so policy-resolution failures are observable in tests and production. */
+  private readonly logger;
+  private readonly options;
+  /**
+   * Creates a new ToolApprovalService instance.
+   * @param bus - Bus instance used to resolve policy data and register approval handlers
+   * @param options - Optional configuration including a file access rule provider
+   */
+  constructor(bus: IMakaioBus, options?: ToolApprovalServiceOptions);
+  /**
+   * Register the tool approval handler.
+   */
+  protected onInit(): Promise<void>;
+  /**
+   * Dispatch an `always-ask` approval request to the approval queue.
+   * Subscribes to the agent session-closed event so that a pending approval
+   * is automatically cancelled when the agent disconnects. The subscription is
+   * cleaned up in the `finally` block regardless of outcome.
+   * @param payload - Tool approval request payload
+   * @param setResult - Callback to set the handler result on the request context
+   * @param resolved - Pre-resolved policy context used to enrich the request
+   */
+  private dispatchAlwaysAskApproval;
+  /**
+   * Evaluate `.makaioignore` file access rules before policy cascade handling.
+   * @param payload - Incoming tool approval payload
+   * @param context - CWD and directory constraints for rule evaluation
+   * @returns Deny message when access should be blocked, otherwise undefined
+   */
+  private checkFileAccessDenyReason;
+  /**
+   * Execute the `approval.resolveEnrichedPolicy` RPC exactly once and return the
+   * raw discriminated result. Callers apply their own fail-closed semantics.
+   * Errors are logged here since this is the single call site for the RPC.
+   * @param personaId - Optional persona ID from agent metadata
+   * @param profileId - Optional profile ID from agent metadata
+   * @param toolName - Tool name forwarded to the RPC
+   * @returns Handled result with response data, or unhandled sentinel on failure
+   */
+  private fetchRawEnrichedPolicy;
+  /**
+   * Resolves the effective approval policy for a tool approval request,
+   * returning the policy alongside cached harness context.
+   *
+   * Policy cascade: persona/profile (via host-tier RPC) → harness → system default.
+   * After resolving the base policy, applies capability-based overrides from
+   * the harness using most-restrictive-wins semantics.
+   * @param request - Adapter name and tool name from the approval payload
+   * @param agent - Pre-fetched agent metadata, or null if unavailable
+   * @param rawEnrichedPolicy - Pre-fetched enriched-policy RPC result shared with the file-access check
+   * @returns Resolved policy and associated context
+   */
+  private resolvePolicyWithContext;
+  /**
+   * Look up agent metadata from storage by agentId.
+   * @param agentId - The agent identifier
+   * @param sessionId - Optional session ID for scoped lookup
+   * @returns Agent metadata, or null if not found
+   */
+  private getAgentMetadata;
+  /**
+   * Check for a session-level approval policy override.
+   * Uses `requestOptional` so that when no session storage handler is registered
+   * (e.g., in tests or lightweight runtimes) the method gracefully returns
+   * `undefined` and the existing policy cascade runs unchanged.
+   * @param sessionId - Session to check
+   * @returns Override policy or undefined when not set or unavailable
+   */
+  private resolveSessionOverride;
+  /**
+   * Resolve harness policy for the given adapter; returns undefined on failure.
+   * @param adapterName - Adapter type name
+   * @param harnessId - Explicit harness ID; overrides the default harness lookup
+   * @param clientId - Client ID for client-scoped harness resolution
+   * @returns Harness resolution carrying base policy and capability override data, or undefined when resolution fails
+   */
+  private resolveHarnessPolicy;
+}
+//#endregion
+export { ToolApprovalService as t };