// Generated from types/*.ts — do not edit.
// Regenerate with: npm run generate:typescript

/**
 * Automation Catalogue Channel State Types for `ahp-automations://`.
 *
 * Stability: 1.0 - Early development
 *
 * @module channels-automation/state
 */

import type { Message, MessageKind } from '../channels-chat/state.js';
import type { ConfigSchema, URI } from '../common/state.js';
import type {
  AutomationRunSummary,
  AutomationTriggeredRunOrigin,
} from '../channels-automation-run/state.js';
import type { ResolveSessionConfigResult } from '../channels-root/commands.js';
import type { AgentInfo, ModelSelection, SessionModelInfo } from '../channels-root/state.js';
import type { CreateSessionParams } from '../channels-session/commands.js';
import type { AgentSelection } from '../channels-session/state.js';
import type {
  AutomationRemovedAction,
  AutomationSetAction,
  AutomationUpdateRequestedAction,
} from './actions.js';
import type {
  FetchAutomationRunsParams,
  ListAutomationTriggerDefinitionsParams,
  RunAutomationParams,
} from './commands.js';

/**
 * Operations the host currently permits for an automation.
 *
 * The list on {@link AutomationEntry.operations} is authoritative and may
 * change over time. Clients MUST NOT infer permission from capabilities alone:
 * capabilities describe what the host implementation can support, while
 * operations describe what is allowed for this particular automation now.
 *
 * @category Automation State
 * @nonexhaustive
 */
export const enum AutomationOperation {
  /** Replace editable fields using {@link AutomationUpdateRequestedAction | `automation/updateRequested`}. */
  Update = 'update',
  /** Permanently remove the automation using {@link AutomationRemovedAction | `automation/removed`}. */
  Remove = 'remove',
  /** Start a manual run using {@link RunAutomationParams | runAutomation}. */
  Run = 'run',
}

/**
 * A portable recurring schedule evaluated in a named time zone.
 *
 * The expression uses exactly five whitespace-separated fields, in this
 * order:
 *
 * | Field | Values |
 * | --- | --- |
 * | minute | `0`–`59` |
 * | hour | `0`–`23` |
 * | day of month | `1`–`31` |
 * | month | `1`–`12` or `JAN`–`DEC` |
 * | day of week | `0`–`7` or `SUN`–`SAT`; both `0` and `7` mean Sunday |
 *
 * Month and weekday names are ASCII and case-insensitive. Each field accepts
 * `*`, a single value, an inclusive range (`1-5`), a comma-separated list of
 * values or ranges (`1,3,8-10`), or a step applied to `*` or a range (for
 * example, */15 or `1-30/2`). A step MUST be a positive integer. AHP does
 * not support seconds, years, macros such as `@daily`, or Quartz extensions
 * such as `?`, `L`, `W`, and `#`.
 *
 * Minute, hour, and month must all match. When both day-of-month and
 * day-of-week are restricted (not `*`), an occurrence matches when either day
 * field matches, following Unix cron semantics.
 *
 * @example
 * `30 9 * * 1-5` runs at 09:30 every weekday.
 *
 * @category Automation State
 */
export interface AutomationSchedule {
  /** Five-field AHP cron expression described by {@link AutomationSchedule}. */
  expression: string;
  /**
   * IANA Time Zone Database identifier used to interpret the expression, for
   * example `"UTC"` or `"Europe/Berlin"`.
   */
  timeZone: string;
}

/**
 * How a host handles schedule occurrences missed while automatic execution was
 * unavailable.
 *
 * @category Automation State
 * @nonexhaustive
 */
export const enum AutomationMisfirePolicy {
  /** Discard missed occurrences and wait for the next future occurrence. */
  Skip = 'skip',
  /**
   * Start at most one catch-up run when execution becomes available, regardless
   * of how many occurrences were missed.
   */
  RunOnce = 'runOnce',
}

/**
 * Discriminant for automatic trigger definitions.
 *
 * @category Automation State
 * @exhaustive
 */
export const enum AutomationTriggerKind {
  /** A portable recurring {@link AutomationSchedule}. */
  Schedule = 'schedule',
  /** A host-defined external event discovered from trigger definitions. */
  Event = 'event',
}

/**
 * Starts runs from a recurring cron schedule evaluated by the host.
 *
 * @category Automation State
 */
export interface AutomationScheduleTrigger {
  /**
   * Identifier unique and stable within this automation definition. Recorded in
   * {@link AutomationTriggeredRunOrigin.triggerId} when this trigger creates a
   * run.
   */
  id: string;
  kind: AutomationTriggerKind.Schedule;
  /** Recurrence and time zone evaluated by the host. */
  schedule: AutomationSchedule;
  /**
   * Policy for missed occurrences. Omission is equivalent to
   * {@link AutomationMisfirePolicy.RunOnce}.
   */
  misfirePolicy?: AutomationMisfirePolicy;
}

/**
 * Starts runs from events understood by the owning host.
 *
 * Event trigger types, events, and configuration are discovered through
 * {@link ListAutomationTriggerDefinitionsParams |
 * listAutomationTriggerDefinitions}. The saved trigger includes the matching
 * human-readable metadata so it remains displayable without repeating
 * discovery.
 *
 * @category Automation State
 */
export interface AutomationEventTrigger {
  /**
   * Identifier unique and stable within this automation definition. Recorded in
   * {@link AutomationTriggeredRunOrigin.triggerId} when this trigger creates a
   * run.
   */
  id: string;
  kind: AutomationTriggerKind.Event;
  /** Matches {@link AutomationTriggerDefinition.type}. */
  type: string;
  /** Host-normalized human-readable trigger type name. */
  title: string;
  /** Optional host-normalized explanation of the trigger source. */
  description?: string;
  /**
   * Selected events for this trigger type.
   *
   * Event ids carry the trigger semantics. Titles and descriptions are
   * last-known display metadata and do not indicate current availability.
   */
  events: AutomationTriggerEventDefinition[];
  /**
   * Values described by {@link AutomationTriggerDefinition.configSchema}.
   * Clients MUST preserve unknown entries when editing other fields.
   */
  config?: Record<string, unknown>;
}

/**
 * An automatic trigger that can create runs for an enabled automation.
 *
 * Manual execution is not represented as a trigger. An empty trigger list
 * therefore means the automation is manual-only.
 *
 * @category Automation State
 */
export type AutomationTrigger =
  | AutomationScheduleTrigger
  | AutomationEventTrigger;

/**
 * Describes one host-defined trigger event.
 *
 * @category Automation State
 */
export interface AutomationTriggerEventDefinition {
  /** Stable event id. */
  id: string;
  /** Human-readable event name. */
  title: string;
  /** Optional longer explanation of when this event fires. */
  description?: string;
}

/**
 * Describes one host-defined event trigger type available for a prospective
 * automation session template.
 *
 * Trigger definitions are discovery metadata, not durable automation state.
 * Hosts may return different definitions for different providers, working
 * directories, or session configuration.
 *
 * @category Automation State
 */
export interface AutomationTriggerDefinition {
  /** Stable type id stored in {@link AutomationEventTrigger.type}. */
  type: string;
  /** Human-readable trigger type name. */
  title: string;
  /** Optional longer explanation of the trigger source. */
  description?: string;
  /** Events available for selection. Saved triggers retain their selected event descriptors. */
  events: AutomationTriggerEventDefinition[];
  /** Optional schema for {@link AutomationEventTrigger.config}. */
  configSchema?: ConfigSchema;
}

/**
 * Template from which the host creates a fresh session for each automation run.
 *
 * The host revalidates every selection when the run starts. Definitions never
 * carry credentials, confirmation decisions, or durable permission grants.
 *
 * @category Automation State
 */
export interface AutomationSessionTemplate {
  /** Provider id matching {@link AgentInfo.provider}. Omit to use the host's default provider. */
  provider?: string;
  /**
   * Optional model selection resolved when a run starts. Its
   * {@link ModelSelection.id} matches a {@link SessionModelInfo.id} advertised
   * by the selected provider.
   */
  model?: ModelSelection;
  /** Optional custom agent selection identified by {@link AgentSelection.uri}. */
  agent?: AgentSelection;
  /**
   * Ordered working-directory URIs for each created session, equivalent to
   * {@link CreateSessionParams.workingDirectories}. Absence means a
   * workspace-less session.
   */
  workingDirectories?: URI[];
  /**
   * Session configuration values equivalent to
   * {@link CreateSessionParams.config}, normally obtained from
   * {@link ResolveSessionConfigResult.values}.
   */
  config?: Record<string, unknown>;
}

/**
 * Durable, client-editable definition of an automation.
 *
 * A definition combines the initial automation message, the session template
 * used for each run, and zero or more automatic triggers. Run history,
 * timestamps, and currently allowed operations live on
 * {@link AutomationEntry} rather than in the definition.
 *
 * @category Automation State
 */
export interface AutomationDefinition {
  /** Human-readable automation name. */
  title: string;
  /**
   * Initial message sent to every newly created run session. Its
   * {@link Message.origin} kind MUST be {@link MessageKind.Automation}.
   */
  message: Message;
  /** Template used to create fresh sessions for each run. */
  session: AutomationSessionTemplate;
  /**
   * Whether automatic triggers may create runs. Manual runs remain available
   * whenever {@link AutomationOperation.Run} is advertised.
   */
  enabled: boolean;
  /** Automatic triggers. An empty list means manual-only. */
  triggers: AutomationTrigger[];
  /**
   * Opaque implementation-defined metadata. Clients MUST preserve unknown
   * entries when updating the definition.
   */
  _meta?: Record<string, unknown>;
}

/**
 * Authoritative state of one automation in {@link AutomationState.entries}.
 *
 * The host owns trigger evaluation, run claims, run retention, and operation
 * availability. Clients render this state and submit actions or commands; they
 * never run a fallback scheduler for a host-owned definition.
 *
 * @category Automation State
 */
export interface AutomationEntry {
  /** Stable `ahp-automation:/<id>` resource identifier. */
  resource: URI;
  /** Current durable definition. */
  definition: AutomationDefinition;
  /** Earliest schedule occurrence awaiting evaluation, as an ISO 8601 timestamp. It may be in the past while catch-up is pending. */
  nextRunAt?: string;
  /**
   * Newest-first retained run summaries. This is a bounded window; use
   * {@link FetchAutomationRunsParams | fetchAutomationRuns} when
   * {@link AutomationEntry.runsNextCursor} is present.
   */
  runs: AutomationRunSummary[];
  /** Opaque cursor passed as {@link FetchAutomationRunsParams.cursor} for the next older run-history page. */
  runsNextCursor?: string;
  /** Operations currently permitted for this automation. */
  operations: AutomationOperation[];
  /** Creation timestamp in ISO 8601 format. */
  createdAt: string;
  /** Last definition modification timestamp in ISO 8601 format. */
  modifiedAt: string;
  /** Opaque host-defined state metadata. */
  _meta?: Record<string, unknown>;
}

/**
 * Authoritative automation catalogue exposed on the `ahp-automations://`
 * channel.
 *
 * A subscription snapshot contains every automation visible to the client.
 * Subsequent {@link AutomationSetAction | `automation/set`} and
 * {@link AutomationRemovedAction | `automation/removed`} actions keep the
 * catalogue synchronized and participate in normal reconnect replay.
 *
 * @category Automation State
 */
export interface AutomationState {
  /** Full automation entries keyed by {@link AutomationEntry.resource}. */
  entries: AutomationEntry[];
  /** Opaque host-defined catalogue metadata. */
  _meta?: Record<string, unknown>;
}