/** * The parts of a handoff that decide *what the target sees* and *whether the * handoff is allowed to happen at all*: the context-policy filter, the * invocation-scoped history seeding, and the per-chain state that cycle and * depth checks read. * * This lives beside `handoff.ts` rather than inside it so the handoff class * gains calls instead of blocks. Nothing here imports `handoff.ts`: the policy * is taken as a plain string and the errors are raised by the caller, which * keeps the two modules acyclic under CommonJS. * * Python parity with praisonaiagents/agent/handoff.py: * - `Handoff._prepare_context` -> `selectHandoffMessages` * - `Handoff._seed_target_history` -> `withSeededHistory` * - `_handoff_chain_var` / `_get_handoff_chain` / `_push_handoff` * -> `currentHandoffChain` / `runWithHandoffChain` */ /** * How many non-system messages the `summary` policy keeps. Python hard-codes * `other_msgs[-3:]` in `_prepare_context`; `max_context_messages` applies to * `last_n` only, so the two are deliberately not the same knob. */ export declare const SUMMARY_MESSAGE_COUNT = 3; /** The settings `selectHandoffMessages` reads off a resolved handoff config. */ export interface HandoffContextSelection { /** One of `full` | `summary` | `none` | `last_n` (Python: `ContextPolicy`). */ contextPolicy: string; /** Messages kept by the `last_n` policy. */ maxContextMessages: number; /** Token ceiling for the selected context; `<= 0` disables the ceiling. */ maxContextTokens: number; /** Keep `system` messages regardless of the slice. */ preserveSystem: boolean; } /** * Trim a message list to `maxTokens` estimated tokens by dropping the oldest * messages first. With `preserveSystem` the `system` messages are never * dropped, so a system prompt larger than the budget is kept in full rather * than leaving the target with no instructions at all. * * The estimate is the SDK's own heuristic (`estimateMessagesTokens`), the same * one the context-compaction policy uses, so a handoff and a compaction agree * about how big a conversation is. * * Note on parity: Python declares `HandoffConfig.max_context_tokens`, * serialises it in `to_dict()` and never reads it — no code path in * praisonaiagents consults the field. TypeScript honours the documented * meaning ("Maximum tokens to include in context") instead of copying the * omission, so this is the one handoff setting where TypeScript does more * than Python rather than the same. */ export declare function fitToTokenBudget(messages: readonly T[], maxTokens: number, preserveSystem: boolean): T[]; /** * The messages a handoff target should see, from the source conversation and * the configured context policy. Python parity with the policy block of * `Handoff._prepare_context`: * * - `none` -> nothing * - `last_n` -> the last `maxContextMessages` * - `summary` -> the last {@link SUMMARY_MESSAGE_COUNT} * - `full` -> everything * * With `preserveSystem` (the default) the slice is taken over the non-system * messages and every `system` message is prepended, so trimming a long * conversation never silently drops the target's instructions. Without it the * slice is taken over the raw list, exactly as Python does. * * `maxContextTokens` is applied last, to whatever the policy selected. */ export declare function selectHandoffMessages(messages: readonly any[] | null | undefined, selection: HandoffContextSelection): any[]; /** * Run `fn` with `prior` prepended to the target agent's conversation, then put * the agent's history back exactly as it was — on failure too. Python parity * with the `_seed_target_history` context manager. * * Without this the target only ever sees the handoff prompt string and the * configured context policy has nothing to act on. The seeding is * invocation-scoped so handoff context cannot leak into the next handoff or * into an ordinary chat that reuses the same agent. Seeding is also serialised * per target (see {@link serialisePerTarget}) so concurrent handoffs to one * agent cannot read each other's context or restore a stale snapshot. * * Two history shapes are supported: a plain `chatHistory`/`chat_history` array * (Python's shape, and what a stub target uses) and the simple `Agent`'s * `getHistory()`/`setHistory()` pair. `setHistory` validates what it is given * and throws on a history it cannot represent (a second `system` message, an * orphaned tool result); such a seed is skipped rather than failing the * handoff. An agent with neither shape — an `EnhancedAgent`, whose messages * live in a `Session` with no restore API — runs unseeded. */ export declare function withSeededHistory(agent: unknown, prior: readonly any[], fn: () => Promise): Promise; /** The chain in force for the current execution. Python: `_get_handoff_chain()`. */ export declare function currentHandoffChain(): readonly string[]; /** How deep the current execution already is. Python: `_get_handoff_depth()`. */ export declare function currentHandoffDepth(): number; /** * Run `fn` with `chain` as the current handoff chain, restoring the previous * one afterwards. Python's `_push_handoff`/`_pop_handoff` pair, expressed as a * scope so no `finally` can be forgotten, and copy-on-write for the same * reason Python is: a push inside a nested handoff must not leak back out. */ export declare function runWithHandoffChain(chain: readonly string[], fn: () => Promise): Promise; /** Test helper: forget any chain left behind by the fallback path. */ export declare function resetHandoffChain(): void;