Let plugins customize agent creation and observe lifecycle events (#4435)

* feat(plugins): expose agent and workspace lifecycle hooks

* test(plugins): verify lifecycle examples with version requirements

* fix(plugins): publish archive hooks for closed agents

* test(plugins): remove diagnostic catch from lifecycle test

* refactor(plugins): define hook handlers in lifecycle module

packages/plugin/src/contracts.ts

@@ -1,3 +1,4 @@
+import type { PluginLifecycleRegistration } from "./lifecycle.js";
 import type { ComponentType } from "react";
 import type { PaseoApi } from "@getpaseo/client";
 import type { AgentTimelineItem, JsonValue } from "@getpaseo/protocol/agent-types";
@@ -319,7 +320,7 @@ export interface PluginHandlerContext {
   paseo: PaseoApi;
 }
 
-export interface PluginServerContext {
+export interface PluginServerContext extends PluginLifecycleRegistration {
   registerSettings<Schema extends ZodType>(
     definition: import("./settings.js").SettingsDefinition<Schema>,
   ): void;

packages/plugin/src/index.ts

@@ -66,3 +66,14 @@ export type {
 export { usePaseo } from "./paseo-context.js";
 export { useAgent, useWorkspace } from "./client-state.js";
 export { useRpc } from "./rpc-context.js";
+
+export type {
+  PluginBeforeRequests,
+  PluginHookAgent,
+  PluginHookContext,
+  PluginHookWorkspace,
+  PluginLifecycleEvents,
+  PluginLifecycleRegistration,
+  PluginSessionOpenRequest,
+  PluginTurnOutcome,
+} from "./lifecycle.js";

packages/plugin/src/lifecycle.ts

@@ -0,0 +1,88 @@
+import type {
+  AgentPermissionRequest,
+  AgentPermissionResponse,
+  AgentTimelineItem,
+  AgentSessionConfig,
+} from "@getpaseo/protocol/agent-types";
+import type { PaseoApi } from "@getpaseo/client";
+import type { WorkspaceCreateRequest } from "@getpaseo/protocol/messages";
+
+export interface PluginHookContext {
+  paseo: PaseoApi;
+  signal: AbortSignal;
+}
+
+export interface PluginHookWorkspace {
+  id: string;
+  projectId: string;
+  cwd: string;
+  name: string | null;
+  archivedAt: string | null;
+}
+
+export interface PluginHookAgent {
+  id: string;
+  workspaceId: string | null;
+  parentAgentId: string | null;
+  provider: string;
+  cwd: string;
+  title: string | null;
+}
+
+export interface PluginSessionOpenRequest {
+  agentId: string;
+  workspaceId: string | null;
+  provider: string;
+  cwd: string;
+  reason: "create" | "resume" | "refresh" | "import";
+  purpose: "interactive" | "history";
+  env: Record<string, string>;
+}
+
+export type PluginTurnOutcome =
+  | { kind: "completed" }
+  | { kind: "failed"; error: { message: string; code?: string } }
+  | { kind: "canceled"; reason: string };
+
+export interface PluginLifecycleEvents {
+  "agent.turn_started": { agent: PluginHookAgent; turnId: string | null };
+  "agent.turn_ended": {
+    agent: PluginHookAgent;
+    turnId: string | null;
+    outcome: PluginTurnOutcome;
+    timeline: readonly AgentTimelineItem[];
+  };
+  "agent.permission_requested": { agent: PluginHookAgent; request: AgentPermissionRequest };
+  "agent.permission_resolved": {
+    agent: PluginHookAgent;
+    requestId: string;
+    resolution: AgentPermissionResponse;
+  };
+  "agent.archived": { agent: PluginHookAgent; archivedAt: string };
+  "agent.created": { agent: PluginHookAgent };
+  "workspace.created": { workspace: PluginHookWorkspace };
+  "workspace.archived": { workspace: PluginHookWorkspace };
+}
+
+export interface PluginBeforeRequests {
+  "agent.create": { config: AgentSessionConfig; env?: Record<string, string> };
+  "agent.session_open": PluginSessionOpenRequest;
+  "workspace.create": Omit<WorkspaceCreateRequest, "type" | "requestId">;
+}
+
+export interface PluginLifecycleRegistration {
+  on<Name extends keyof PluginLifecycleEvents>(
+    name: Name,
+    handler: (
+      event: PluginLifecycleEvents[Name],
+      context: PluginHookContext,
+    ) => void | Promise<void>,
+  ): () => void;
+  before<Name extends keyof PluginBeforeRequests>(
+    name: Name,
+    handler: (
+      input: { request: PluginBeforeRequests[Name] },
+      context: PluginHookContext,
+    ) => PluginBeforeRequests[Name] | void | Promise<PluginBeforeRequests[Name] | void>,
+  ): () => void;
+}

packages/plugin/src/server.ts

@@ -1 +1,12 @@
 export type { PluginHandlerContext } from "./contracts.js";
+
+export type {
+  PluginBeforeRequests,
+  PluginHookAgent,
+  PluginHookContext,
+  PluginHookWorkspace,
+  PluginLifecycleEvents,
+  PluginLifecycleRegistration,
+  PluginSessionOpenRequest,
+  PluginTurnOutcome,
+} from "./lifecycle.js";