import type { CrossChannelToFn } from "#channel/cross-channel-receive.js";
import type { SessionAuthContext } from "#channel/types.js";
import type { ExactDefinition } from "#public/definitions/exact.js";
import type { GenericScheduleDefinition, GenericScheduleRunHandler, GenericScheduleDefinitionFields } from "#shared/schedule-definition.js";
export type { InferReceiveTarget, TypedReceiveTarget } from "#channel/receive-target.js";
/** Selects a proactive target channel from a schedule handler. */
export type ScheduleToFn = CrossChannelToFn;
/**
 * Arguments passed to a schedule's `run` handler. A tight subset of a route
 * handler's args: `to` selects another channel and `waitUntil`
 * extends the task lifetime.
 */
export interface ScheduleHandlerArgs {
    /**
     * Selects a proactive target on another channel. Call `.send(message, options)`
     * on the returned handle.
     */
    readonly to: ScheduleToFn;
    /**
     * Extends the cron task's lifetime past handler return so the runtime awaits
     * background work (the parked workflow session, in-flight fetches, etc.)
     * before the Nitro task ends.
     */
    readonly waitUntil: (task: Promise<unknown>) => void;
    /**
     * Pre-built APP auth context. Pass this to `to(channel, target).send(message, { auth })`
     * for schedules that run on behalf of the agent itself.
     */
    readonly appAuth: SessionAuthContext;
}
/**
 * The `run` form of {@link ScheduleDefinition} invokes this handler when a
 * schedule's cron fires. It receives {@link ScheduleHandlerArgs} (`to`,
 * `waitUntil`, `appAuth`) and may return synchronously or as a promise.
 */
export type ScheduleRunHandler = GenericScheduleRunHandler<ScheduleHandlerArgs>;
/**
 * Public definition for a schedule authored in TypeScript. Provide a required
 * `cron` expression plus exactly one of `markdown` or `run`:
 *
 * - `markdown`: fire-and-forget agent invocation. The framework runs the agent
 *   on the prompt and discards the output (equivalent to the `<name>.md`
 *   markdown form).
 * - `run`: full handler ({@link ScheduleRunHandler}). Receives
 *   `{ to, waitUntil, appAuth }` and decides what to do.
 *
 * Identity is derived from the file path under `agent/schedules/`; authored
 * definitions do not carry a `name` field.
 */
export type ScheduleDefinition = GenericScheduleDefinition<ScheduleHandlerArgs>;
/**
 * Defines a schedule in TypeScript. Export as the default from
 * `agent/schedules/<name>.ts`. Pass a `cron` expression plus exactly one of
 * `markdown` (fire-and-forget prompt) or `run` (handler); the schedule name
 * comes from the file path under `agent/schedules/`.
 *
 * @example Start a session on Slack:
 * ```ts
 * import { defineSchedule } from "eve/schedules";
 * import slack from "../channels/slack.js";
 *
 * export default defineSchedule({
 *   cron: "0 9 * * 1-5",
 *   async run({ to, waitUntil, appAuth }) {
 *     waitUntil(to(slack, { channelId: "C0123ABC" }).send(
 *       "Post the daily standup summary.",
 *       { auth: appAuth },
 *     ));
 *   },
 * });
 * ```
 *
 * @example Fire-and-forget:
 * ```ts
 * export default defineSchedule({
 *   // The real value is "asterisk-slash-5 * * * *" (every 5 minutes). The
 *   // space below is only here so the literal stays inside this block comment.
 *   cron: "* / 5 * * * *",
 *   markdown: "Sync open Linear issues to the metrics dashboard.",
 * });
 * ```
 */
export declare function defineSchedule<TSchedule extends ScheduleDefinition>(definition: ExactDefinition<TSchedule, GenericScheduleDefinitionFields<ScheduleHandlerArgs>>): TSchedule;