Trigger API Reference

Repository triggers use the generated ansight/triggers/ansight-trigger.d.ts contract. The copy generated by your installed CLI is authoritative for that version. The linked source and this guide provide an online reference.

Module shape

Every trigger exports a JSON-compatible descriptor and one default function:

import type {
  TriggerContext,
  TriggerDefinition
} from "./ansight-trigger.d.ts";

type Payload = {
  priority: string;
  message?: string;
};

export const trigger = {
  schemaVersion: 1,
  eventKind: "session.log.received",
  conditions: [
    {
      field: "payload.priority",
      operator: "equals",
      value: "Error"
    }
  ]
} satisfies TriggerDefinition<"session.log.received">;

export default function run({ event, app }: TriggerContext<Payload>) {
  return app.artifacts.request({
    providerId: "example.diagnostics",
    artifactId: "state",
    arguments: { message: event.payload.message ?? "" }
  });
}

The function returns nothing or exactly one declarative action. Version 1 supports app-tool actions; version 2 also supports host evidence actions. The function does not execute the action itself.

TriggerDefinition<TEventKind>

The descriptor is extracted without importing the module. Keep it a static object literal without variables, functions, spreads, or computed values.

TriggerContext<TPayload, TEventKind>

Host evidence actions without the SDK

Version 2 triggers can return one of these host-owned actions:

Declare requirements in the trigger descriptor. ansight.capabilities is the snapshot supplied to that invocation, with mode, app availability, and provider details; it is not the task API’s asynchronous snapshot() method. SDK app actions remain unavailable without an SDK provider. Missing capabilities are reported as capability_unavailable with no retry.

See the native-log trigger example for android-logcat and apple-unified-log conditions. Host capture actions still require their provider to be available when the action runs; a finalized session cannot supply a new live screenshot or sandbox read.

TriggerRun

EventEnvelope<TPayload, TEventKind>

EventKind

Each event links to its timing, payload, and usage guidance.

Condition

The CLI evaluates conditions before running the trigger.

interface Condition {
  field: ConditionField;
  operator: ConditionOperator;
  value?: unknown;
  ignoreCase?: boolean;
}

Top-level field values are eventId, kind, occurredAtUtc, appId, sessionId, correlationId, and causationId. Nested payload fields use payload.<path>.

ignoreCase enables ordinal case-insensitive string comparison. Every condition must pass; there is no executable predicate or OR group in contract version 1.

RetryPolicy

Only failed and timed-out attempts retry. Each attempt runs the handler again and keeps the same run, event, and correlation identity.

app: action factories

These methods return an AppToolAction; they do not return a promise and do not call the app inside TypeScript. Return one action from the function so the CLI can validate, authorize, audit, and dispatch it.

Clipboard factories return declarative actions backed by the native Clipboard suite. Reads require Read policy; set and clear require Write policy. See Clipboard Tools for registration, limits, and platform behavior.

The App Tool API explains what each method does. In a trigger, return one factory result; the host executes it after the function returns.

Returning app.files.beginBinaryDownload({ root, path }) streams the selected sandboxed file to the host. After the binary transfer completes, the host retains the file as an artifact on the originating session.

AppToolAction<TArguments>

Every factory produces the same declarative shape:

interface AppToolAction<TArguments extends AppToolArguments> {
  type: "appTool";
  toolId: string;
  arguments: TArguments;
}

The host preserves the matched event’s session and correlation identity. The action is rejected if no live session is available, the tool is absent, its arguments are invalid, or the app’s guard denies it.

Return contract

type TriggerFunction<TPayload, TEventKind> = (
  invocation: TriggerContext<TPayload, TEventKind>
) =>
  | AppToolAction
  | null
  | void
  | Promise<AppToolAction | null | void>;

Return null or nothing for a match that needs local computation only. A trigger cannot execute host-owned UI APIs, dispatch multiple app actions, register new event sources, or supply an executable predicate.

Execution rules

• The exact App ID, event kind, and every condition are matched before the trigger runs.
• The function timeout and action timeout are separate.
• Repository trigger code is trusted local code, not a filesystem or network sandbox.
• App actions retain the connected app’s grants and critical-tool policy.
• Trigger catalogs must be explicitly connected before they receive events.
• A repository can define up to 256 triggers; each module is limited to 1 MiB.

Related docs

• Triggers guide
• App Tool API
• Task API Reference
• Workspace Execution Security
• CLI Command Reference
• Tooling and Validation