Authoring a plugin

export interface PluginModule<T = unknown> {
  manifest: PluginManifest;
  create(config?: Record<string, unknown>): T;
  detect?(): boolean;
}

export interface PluginManifest {
  name: string;        // must match the package-name suffix (see below)
  slot: PluginSlot;    // use "as const" to preserve the literal type
  description: string;
  version: string;
  displayName?: string;
}

import type { PluginModule, Notifier } from "@aoagents/ao-core";

export const manifest = {
  name: "my-notifier",
  slot: "notifier" as const,
  description: "Send alerts to My Service",
  version: "0.1.0",
};

export function create(config?: Record<string, unknown>): Notifier {
  // validate here, return interface implementation
}

export function detect(): boolean {
  return Boolean(process.env["MY_SERVICE_TOKEN"]);
}

export default { manifest, create, detect } satisfies PluginModule<Notifier>;

export function create(config?: Record<string, unknown>): Notifier {
  // Resolve config or fall back to an environment variable.
  const url = (config?.url as string | undefined) ?? process.env["WEBHOOK_URL"];

  if (!url) {
    // Warn for missing optional config — don't throw.
    // Throw only when a required field is missing at method call time.
    console.warn("[notifier-webhook] No url configured — notifications will be no-ops");
  } else {
    validateUrl(url, "notifier-webhook");  // throws on malformed URL
  }

  // Custom headers are optional — silently ignore non-string values.
  const customHeaders: Record<string, string> = {};
  const rawHeaders = config?.headers;
  if (rawHeaders && typeof rawHeaders === "object" && !Array.isArray(rawHeaders)) {
    for (const [k, v] of Object.entries(rawHeaders)) {
      if (typeof v === "string") customHeaders[k] = v;
    }
  }

  return {
    name: "webhook",
    async notify(event) {
      if (!url) return;
      await fetch(url, {
        method: "POST",
        headers: { "Content-Type": "application/json", ...customHeaders },
        body: JSON.stringify({ type: "notification", event }),
      });
    },
  };
}

plugins:
  - name: pagerduty
    source: registry
    package: "ao-plugin-notifier-pagerduty"
    version: "^1.0.0"

plugins:
  - name: pagerduty
    source: local
    path: ./plugins/pagerduty

projects:
  myapp:
    tracker:
      package: "@acme/ao-plugin-tracker-jira"
      version: "^1.0.0"
      projectKey: "MYAPP"

projects:
  myapp:
    tracker:
      plugin: jira
      package: "@acme/ao-plugin-tracker-jira"
      version: "^1.0.0"

import { describe, it, expect, vi, beforeEach } from "vitest";
import pluginModule from "../index.js";

vi.mock("node:fs/promises", () => ({ readFile: vi.fn() }));

describe("manifest", () => {
  it("has correct slot and name", () => {
    expect(pluginModule.manifest.slot).toBe("notifier");
    expect(pluginModule.manifest.name).toBe("pagerduty");
  });
});

describe("create()", () => {
  beforeEach(() => vi.clearAllMocks());

  it("throws when routing_key is missing", () => {
    expect(() => pluginModule.create({})).toThrow("routing_key");
  });

  it("returns a notifier with notify()", () => {
    const notifier = pluginModule.create({ routing_key: "test-key" });
    expect(typeof notifier.notify).toBe("function");
  });
});

async getActivityState(session, readyThresholdMs?): Promise<ActivityDetection | null> {
  const threshold = readyThresholdMs ?? DEFAULT_READY_THRESHOLD_MS;

  // 1. PROCESS CHECK — always first
  const running = await this.isProcessRunning(session.runtimeHandle!);
  if (!running) return { state: "exited", timestamp: new Date() };

  // 2. ACTIONABLE STATES — waiting_input / blocked from JSONL
  const activityResult = await readLastActivityEntry(session.workspacePath);
  const actionable = checkActivityLogState(activityResult);
  if (actionable) return actionable;

  // 3. NATIVE SIGNAL — agent-specific API (preferred when available)
  try {
    const nativeTimestamp = await this.getNativeTimestamp(session);
    if (nativeTimestamp) {
      const age = Date.now() - nativeTimestamp.getTime();
      const activeWindowMs = Math.min(DEFAULT_ACTIVE_WINDOW_MS, threshold);
      const state = age < activeWindowMs ? "active" : age < threshold ? "ready" : "idle";
      return { state, timestamp: nativeTimestamp };
    }
  } catch {
    // fall through to JSONL fallback
  }

  // 4. JSONL ENTRY FALLBACK — mandatory safety net
  const activeWindowMs = Math.min(DEFAULT_ACTIVE_WINDOW_MS, threshold);
  const fallback = getActivityFallbackState(activityResult, activeWindowMs, threshold);
  if (fallback) return fallback;

  // 5. No data at all
  return null;
}