@dollhousemcp/mcp-server
Version:
DollhouseMCP - A Model Context Protocol (MCP) server that enables dynamic AI persona management from markdown files, allowing Claude and other compatible AI assistants to activate and switch between different behavioral personas.
119 lines • 4.13 kB
TypeScript
/**
* Handoff Service — Session handoff for agent execution.
*
* Enables agent executions to be paused, serialized, and resumed
* across session boundaries. Builds on GatheredData (#68) for
* execution state aggregation.
*
* Part of the Agentic Loop Completion (Epic #380, Issues #69, #71).
*
* @since v2.0.0
*/
import type { GatheredData, GatheredDataEntry } from './gatheredData.js';
/**
* Complete handoff state snapshot for session transfer.
*
* Contains everything needed to resume an agent execution:
* - Goal progress and status
* - Gathered data (decisions, findings, metrics)
* - Active element context
* - Continuation instructions
*/
export interface HandoffState {
/** Schema version for forward compatibility */
version: string;
/** Agent name */
agentName: string;
/** Goal ID being handed off */
goalId: string;
/** ISO 8601 timestamp when handoff was prepared */
preparedAt: string;
/** SHA-256 checksum of the data payload (excludes checksum field itself) */
checksum: string;
/** Goal progress snapshot */
goalProgress: {
description: string;
status: string;
stepsCompleted: number;
successCriteria: string[];
};
/** Aggregated execution data from GatheredData */
gatheredDataSummary: {
totalEntries: number;
/** Last N entries (most recent, capped for size) */
recentEntries: GatheredDataEntry[];
/** Summary statistics */
summary: GatheredData['summary'];
};
/** Recent decision history (last 10) */
decisionHistory: Array<{
decision: string;
reasoning: string;
outcome?: string;
confidence: number;
timestamp: string;
}>;
/** Active elements at time of handoff */
activeElements: Record<string, string[]>;
/** Human-readable continuation instructions */
continuationInstructions: string;
}
/**
* Prepare a handoff state from gathered data and execution context.
*
* @param agentName - Agent name
* @param gatheredData - Aggregated execution data from getGatheredData()
* @param activeElements - Currently active elements (from execute result or state)
* @param successCriteria - Goal success criteria
* @returns Complete HandoffState with checksum
*/
export declare function prepareHandoffState(agentName: string, gatheredData: GatheredData, activeElements: Record<string, string[]>, successCriteria?: string[]): HandoffState;
/**
* Validate a handoff state's checksum integrity.
*
* @param state - HandoffState to validate
* @returns true if checksum is valid
*/
export declare function validateHandoffChecksum(state: HandoffState): boolean;
/**
* Generate a copy-pasteable handoff block with human-readable summary
* and machine-readable compressed payload.
*
* The block format:
* ```
* ╔════════...════╗
* ║ AGENT HANDOFF — {agentName}
* ║ Goal: {description}
* ║ Status: {status} | Steps: {n} | Confidence: {avg}
* ║
* ║ Next Steps:
* ║ {continuationInstructions}
* ╚════════...════╝
* --- HANDOFF PAYLOAD START ---
* {base64-compressed-json}
* --- HANDOFF PAYLOAD END ---
* ```
*
* @param state - HandoffState to encode
* @returns Formatted handoff block string
*/
export declare function generateHandoffBlock(state: HandoffState): string;
/**
* Parse a handoff block and extract the HandoffState.
*
* @param text - Raw text containing a handoff block
* @returns Parsed and validated HandoffState
* @throws Error if block is malformed, payload is corrupted, or checksum fails
*/
export declare function parseHandoffBlock(text: string): HandoffState;
/**
* Compress a HandoffState to a base64-encoded gzip string.
* JSON → gzip → base64 for compact copy/paste.
*/
export declare function compressHandoffState(state: HandoffState): string;
/**
* Decompress a base64-encoded gzip string back to HandoffState.
* base64 → gunzip → JSON.parse
*/
export declare function decompressHandoffState(encoded: string): HandoffState;
//# sourceMappingURL=handoff.d.ts.map