Wire FluxAgent lifecycle hooks (init, error, shutdown)

[Aditya (adityajha2005)]

Summary

This PR adds optional lifecycle hook support to FluxAgent and wires those hooks into the existing execution flow.

What’s included

• Adds optional onInit, onError, and onShutdown hooks to FluxAgent
• Invokes onInit when an agent is loaded
• Invokes onError when invoke throws (local and prod)
• Invokes onShutdown on graceful shutdown (local readline close and SIGINT in prod)
• Minor formatting fixes for consistency

Why

This enables agents to:

• Perform setup on startup (e.g. initialize clients or state)
• Handle errors in a structured way
• Clean up resources on shutdown

All hooks are optional and fully backwards-compatible with existing agents.

Notes

• No behavioral changes for agents that don’t implement lifecycle hooks
• Lifecycle wiring is scoped to existing runtime boundaries (loader, local CLI, prod signal handling)

[Copilot]

Pull request overview

This PR introduces optional lifecycle hook support to the FluxAgent interface, enabling agents to perform setup, error handling, and cleanup operations. The hooks are wired into the existing execution flow for both local and production environments.

• Added three optional lifecycle methods (onInit, onError, onShutdown) to the FluxAgent interface
• Integrated lifecycle hook invocations at appropriate points: agent loading, error handling, and graceful shutdown
• Maintained backward compatibility by making all hooks optional

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.

File	Description
src/agent-type.ts	Added optional lifecycle hook method signatures (onInit, onError, onShutdown) to FluxAgent interface with documentation
src/agent-loader.ts	Invokes onInit hook after loading agent module to enable initialization logic
src/index.ts	Wires onError hook into local error handling and onShutdown hook into both local readline close and production SIGINT handlers for graceful shutdown

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Documentation comment for onError lifecycle hook is missing. While onInit and onShutdown have comments explaining when they are called, onError lacks this documentation. For consistency and clarity, add a comment explaining when onError is invoked, such as "onError is called when invoke throws an error."

[Copilot]

The onInit hook should be wrapped in a try-catch block to handle potential initialization errors gracefully. If onInit throws an error, it will currently cause an unhandled promise rejection and the agent will fail to load without clear feedback to the user about what went wrong during initialization.

Suggested change

	await agent.onInit();
	try {
	await agent.onInit();
	} catch (error) {
	console.error("[FLUX] Agent onInit hook failed:", error);
	throw error;
	}

[Copilot]

The onError hook should be wrapped in a try-catch block to prevent errors within the error handler from causing unhandled promise rejections. If onError itself throws an error, it could lead to cascading failures and unclear error messages for users.

Suggested change

	await agent.onError(error);
	try {
	await agent.onError(error);
	} catch (handlerError) {
	console.error("[FLUX] Error in agent.onError handler:", handlerError);
	}

[Copilot]

The onShutdown hook should be wrapped in a try-catch block to ensure the process can exit gracefully even if the shutdown hook throws an error. Without this protection, errors in onShutdown could prevent the application from exiting properly or cause unclear error messages during shutdown.

Suggested change

	await agent.onShutdown();
	try {
	await agent.onShutdown();
	} catch (error: any) {
	console.error(`[FLUX] Error during shutdown: ${error?.message ?? error}`);
	}

[Copilot]

The onShutdown hook should be wrapped in a try-catch block to ensure the process can exit gracefully even if the shutdown hook throws an error. Without this protection, errors in onShutdown could prevent flux.disconnect() from being called or cause unclear error messages during shutdown.

Suggested change

	if (agent.onShutdown) {
	await agent.onShutdown();
	}
	await flux.disconnect();
	process.exit(0);
	try {
	if (agent.onShutdown) {
	await agent.onShutdown();
	}
	} catch (error: any) {
	console.error("[FLUX] Error during agent shutdown:", error?.message ?? error);
	} finally {
	await flux.disconnect();
	process.exit(0);
	}

[Gary Gao (garygao333)]

Thank you! I think this is great, and something that we'll definitely consider adding in the future.

[Aditya (adityajha2005)]

Thank you! I think this is great, and something that we'll definitely consider adding in the future.

works, do you think any particular issue the repo has, or can you tell what kinda contribution is exactly needed in this repo as of now? Gary Gao (@garygao333)

[Gary Gao (garygao333)]

Thanks for offering to help! I don't currently have any contributions in mind, but please feel free to use the CLI to build some interesting and innovative agents. Let us know what you build!