/**
 * loop tools — compatibility shims over the LoopCoordinator.
 *
 * Phase C removed these tools and consolidated multi-round work into the
 * graph_* engine. They were re-approved for restoration as thin compatibility
 * shims that keep the imperative loop_* surface working for callers who still
 * use it. The graph_* tools remain untouched — loop_* and graph_* are
 * independent namespaces that coexist.
 *
 * Each factory delegates to the corresponding LoopCoordinator method, so no
 * loop lifecycle logic is duplicated here. The coordinator is the single
 * source of truth for loop state (register / getAllLoopStates / getLoopState /
 * cancelNow / getLoopDescendants / getAdvancingLockState).
 *
 * Recovered from commit 810f6d3 (src/loop/loop-tools.ts + the createLoopStartTool
 * from src/platform/adapters/pi/loop-tool.ts), adapted to the current
 * LoopCoordinator API and made platform-agnostic so it can be assembled by the
 * shared tool-assembly layer (no Pi/OpenCode SDK imports).
 */
import { z } from "zod";
import type { LoopCoordinator } from "./coordinator.ts";
import type { LoopPhase } from "./types.ts";
import type { ISessionClient } from "../platform/ports/session-client.ts";
import type { CanonicalToolDef } from "../platform/types.ts";
/**
 * Human-readable snapshot of a single loop's runtime state.
 * Mirrors LoopState fields surfaced to tool consumers.
 */
export interface LoopStatusSnapshot {
    originSessionId: string;
    agent: string;
    mode: string;
    total: number;
    current: number;
    phase: LoopPhase;
    cancelRequested: boolean;
    errorReason?: string;
    startedAt: number;
    updatedAt: number;
    roundStartedAt: number;
    activeWorkerTaskId?: string;
    activeWorkerSessionId?: string;
    roundCount: number;
    lastSummary?: string;
}
/**
 * Record of a single loop round for tool output.
 * Mirrors RoundRecord with simplified fields.
 */
export interface LoopHistoryEntry {
    round: number;
    workerTaskId: string;
    workerSessionId: string;
    startedAt: number;
    completedAt?: number;
    durationMs?: number;
    status: string;
}
/**
 * Aggregate metrics across all tracked loop instances.
 * Provides a high-level view of loop subsystem health.
 */
export interface LoopMetricsSnapshot {
    totalLoops: number;
    activeLoops: number;
    terminalLoops: number;
    byPhase: Record<string, number>;
    advancingLockState: {
        activeLocks: number;
        staleLocks: number;
    };
}
/**
 * loop_start — Register a sequential multi-session loop with the coordinator.
 *
 * The coordinator runs the rounds asynchronously via background dispatch; this
 * tool returns immediately (non-blocking). On success it returns the origin
 * session ID so callers can track progress with loop_status / loop_output /
 * loop_history. On rejection it forwards the coordinator's RegisterResult
 * error back to the agent as a correction.
 *
 * The origin session ID and acting agent are resolved from the canonical tool
 * context (sessionID / agent), mirroring the dispatch tool's pattern. On
 * platforms that do not populate context.agent, `fallbackAgent` is used.
 */
export declare function createLoopStartTool(coordinator: LoopCoordinator, opts?: {
    fallbackAgent?: () => string;
}): CanonicalToolDef;
/**
 * loop_status — Inspect a single loop or return aggregate metrics.
 *
 * Without session_id: returns a LoopMetricsSnapshot across all loops.
 * With session_id: returns a detailed LoopStatusSnapshot for that loop.
 */
export declare function createLoopStatusTool(coordinator: LoopCoordinator): CanonicalToolDef<{
    session_id: z.ZodOptional<z.ZodString>;
}>;
/**
 * loop_cancel — Cancel a running loop.
 *
 * Accepts either an origin session ID or a worker session ID.
 * Calls coordinator.cancelNow() which resolves worker→origin internally.
 */
export declare function createLoopCancelTool(coordinator: LoopCoordinator): CanonicalToolDef<{
    session_id: z.ZodString;
}>;
/**
 * loop_output — Retrieve worker output for a specific round of a loop.
 *
 * Parallels dispatch_output: accepts round number or resolves worker session
 * from the provided session_id. Reads the worker's session messages and
 * supports max_chars / offset / tail pagination. Falls back to reading
 * session messages via the ISessionClient when available.
 */
export declare function createLoopOutputTool(coordinator: LoopCoordinator, sessionClient?: ISessionClient): CanonicalToolDef<{
    session_id: z.ZodString;
    round: z.ZodOptional<z.ZodNumber>;
    max_chars: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
    offset: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
    limit: z.ZodOptional<z.ZodNumber>;
    tail: z.ZodOptional<z.ZodBoolean>;
}>;
/**
 * loop_history — Retrieve full round-by-round execution history.
 *
 * Returns an array of LoopHistoryEntry records for all completed rounds
 * of the given loop.
 */
export declare function createLoopHistoryTool(coordinator: LoopCoordinator): CanonicalToolDef<{
    session_id: z.ZodString;
    round: z.ZodOptional<z.ZodNumber>;
}>;
/**
 * loop_list — List all tracked loop instances.
 *
 * Returns a markdown table (or JSON) of all loops with session ID,
 * agent, phase, round progress, elapsed time, and mode.
 * Supports optional filtering by phase (running/terminal) and agent name.
 */
export declare function createLoopListTool(coordinator: LoopCoordinator): CanonicalToolDef<{
    phase: z.ZodOptional<z.ZodEnum<{
        running: "running";
        terminal: "terminal";
    }>>;
    agent: z.ZodOptional<z.ZodString>;
    format: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
        json: "json";
        summary: "summary";
    }>>>;
}>;
/**
 * Register all loop tool factories into a named record.
 *
 * Returns an object suitable for merging into a platform tool registry:
 *
 *   const loopTools = createLoopTools(coordinator, sessionClient);
 *
 * Keys: loop_start, loop_status, loop_list, loop_history, loop_output, loop_cancel.
 * These are real CanonicalToolDefs backed by the provided LoopCoordinator.
 */
export declare function createLoopTools(coordinator: LoopCoordinator, sessionClient?: ISessionClient, opts?: {
    fallbackAgent?: () => string;
}): Record<string, CanonicalToolDef>;
//# sourceMappingURL=loop-tools.d.ts.map