Trigger API Reference

Repository triggers use the generated ansight/triggers/ansight-automation.d.ts contract. That file is authoritative for the installed Ansight version; this page provides a navigable reference.

Module shape

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

import type {
  TriggerContext,
  TriggerDefinition
} from "./ansight-automation.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 app-tool action. It 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>

TriggerRun

EventEnvelope<TPayload, TEventKind>

EventKind

Condition

Conditions are evaluated by the host before Node starts.

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 starts a new process but 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 C# host can validate, authorize, audit, and dispatch it.

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 Studio-owned host 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 Node starts.
• 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
• Task API Reference
• Workspace Node.js Security
• CLI Command Reference
• Authoring and Validation
• CLI Command Reference