feat: initial implementation of Modus Agents

.trunk/configs/cspell.json

@@ -58,6 +58,7 @@
     "getsentry",
     "gitinfo",
     "gjson",
+    "goakt",
     "goarch",
     "GOBIN",
     "goccy",
@@ -139,6 +140,7 @@
     "openai",
     "openspeech",
     "operationreport",
+    "passivation",
     "PEMS",
     "pgconn",
     "pgxpool",
@@ -179,6 +181,7 @@
     "textgeneration",
     "tidwall",
     "tinygo",
+    "tochemey",
     "toolcalling",
     "tseslint",
     "tsrv",

.vscode/launch.json

@@ -139,6 +139,10 @@
       "type": "pickString",
       "description": "Choose a Modus app",
       "options": [
+        {
+          "label": "Agents Example",
+          "value": "agents"
+        },
         {
           "label": "Anthropic Model Example",
           "value": "anthropic-functions"

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 # Change Log
 
+## UNRELEASED
+
+- feat: initial implementation of Modus Agents [#840](https://github.com/hypermodeinc/modus/pull/840)
+
 ## 2025-05-06 - CLI 0.17.4
 
 - fix: fully install go sdk in dev mode [#837](https://github.com/hypermodeinc/modus/pull/837)

go.work

@@ -7,6 +7,7 @@ use (
 	./runtime
 	./runtime/languages/golang/testdata
 	./sdk/go
+	./sdk/go/examples/agents
 	./sdk/go/examples/anthropic-functions
 	./sdk/go/examples/auth
 	./sdk/go/examples/classification

runtime/actors/actorlogger.go

@@ -0,0 +1,116 @@
+/*
+ * Copyright 2025 Hypermode Inc.
+ * Licensed under the terms of the Apache License, Version 2.0
+ * See the LICENSE file that accompanied this code for further details.
+ *
+ * SPDX-FileCopyrightText: 2025 Hypermode Inc. <[email protected]>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package actors
+
+import (
+	"fmt"
+	"io"
+	"log"
+
+	"github.com/hypermodeinc/modus/runtime/logger"
+	"github.com/hypermodeinc/modus/runtime/utils"
+	"github.com/rs/zerolog"
+	actorLog "github.com/tochemey/goakt/v3/log"
+)
+
+func newActorLogger(logger *zerolog.Logger) *actorLogger {
+
+	var minLevel zerolog.Level
+	if utils.EnvVarFlagEnabled("MODUS_DEBUG_ACTORS") {
+		minLevel = zerolog.DebugLevel
+	} else {
+		// goakt info level is too noisy, so default to show only errors
+		minLevel = zerolog.ErrorLevel
+	}
+
+	l := logger.Level(minLevel).With().Str("component", "actors").Logger()
+	return &actorLogger{&l}
+}
+
+type actorLogger struct {
+	logger *zerolog.Logger
+}
+
+func (al *actorLogger) Debug(v ...any) {
+	al.logger.Debug().Msg(fmt.Sprint(v...))
+}
+
+func (al *actorLogger) Debugf(format string, v ...any) {
+	al.logger.Debug().Msgf(format, v...)
+}
+
+func (al *actorLogger) Info(v ...any) {
+	al.logger.Info().Msg(fmt.Sprint(v...))
+}
+
+func (al *actorLogger) Infof(format string, v ...any) {
+	al.logger.Info().Msgf(format, v...)
+}
+
+func (al *actorLogger) Warn(v ...any) {
+	al.logger.Warn().Msg(fmt.Sprint(v...))
+}
+
+func (al *actorLogger) Warnf(format string, v ...any) {
+	al.logger.Warn().Msgf(format, v...)
+}
+
+func (al *actorLogger) Error(v ...any) {
+	al.logger.Error().Msg(fmt.Sprint(v...))
+}
+
+func (al *actorLogger) Errorf(format string, v ...any) {
+	al.logger.Error().Msgf(format, v...)
+}
+
+func (al *actorLogger) Fatal(v ...any) {
+	al.logger.Fatal().Msg(fmt.Sprint(v...))
+}
+
+func (al *actorLogger) Fatalf(format string, v ...any) {
+	al.logger.Fatal().Msgf(format, v...)
+}
+
+func (al *actorLogger) Panic(v ...any) {
+	al.logger.Panic().Msg(fmt.Sprint(v...))
+}
+
+func (al *actorLogger) Panicf(format string, v ...any) {
+	al.logger.Panic().Msgf(format, v...)
+}
+
+func (al *actorLogger) LogLevel() actorLog.Level {
+	switch al.logger.GetLevel() {
+	case zerolog.DebugLevel:
+		return actorLog.DebugLevel
+	case zerolog.InfoLevel:
+		return actorLog.InfoLevel
+	case zerolog.WarnLevel:
+		return actorLog.WarningLevel
+	case zerolog.ErrorLevel:
+		return actorLog.ErrorLevel
+	case zerolog.FatalLevel:
+		return actorLog.FatalLevel
+	case zerolog.PanicLevel:
+		return actorLog.PanicLevel
+	default:
+		return actorLog.InvalidLevel
+	}
+}
+
+func (al *actorLogger) LogOutput() []io.Writer {
+	w := logger.NewLogWriter(al.logger, al.logger.GetLevel())
+	return []io.Writer{w}
+}
+
+func (al *actorLogger) StdLogger() *log.Logger {
+	w := logger.NewLogWriter(al.logger, al.logger.GetLevel())
+	return log.New(w, "", 0)
+}

runtime/actors/actorsystem.go

@@ -0,0 +1,78 @@
+/*
+ * Copyright 2025 Hypermode Inc.
+ * Licensed under the terms of the Apache License, Version 2.0
+ * See the LICENSE file that accompanied this code for further details.
+ *
+ * SPDX-FileCopyrightText: 2025 Hypermode Inc. <[email protected]>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package actors
+
+import (
+	"context"
+	"time"
+
+	"github.com/hypermodeinc/modus/runtime/logger"
+	"github.com/hypermodeinc/modus/runtime/pluginmanager"
+	"github.com/hypermodeinc/modus/runtime/plugins"
+
+	goakt "github.com/tochemey/goakt/v3/actor"
+)
+
+var _actorSystem goakt.ActorSystem
+
+func Initialize(ctx context.Context) {
+
+	actorLogger := newActorLogger(logger.Get(ctx))
+
+	actorSystem, err := goakt.NewActorSystem("modus",
+		goakt.WithLogger(actorLogger),
+		goakt.WithCoordinatedShutdown(beforeShutdown),
+		goakt.WithPassivationDisabled(),            // TODO: enable passivation. Requires a persistence store in production for agent state.
+		goakt.WithActorInitTimeout(10*time.Second), // TODO: adjust this value, or make it configurable
+		goakt.WithActorInitMaxRetries(1))           // TODO: adjust this value, or make it configurable
+
+	if err != nil {
+		logger.Fatal(ctx).Err(err).Msg("Failed to create actor system.")
+	}
+
+	if err := actorSystem.Start(ctx); err != nil {
+		logger.Fatal(ctx).Err(err).Msg("Failed to start actor system.")
+	}
+
+	_actorSystem = actorSystem
+
+	logger.Info(ctx).Msg("Actor system started.")
+
+	pluginmanager.RegisterPluginLoadedCallback(reloadAgentActors)
+}
+
+func reloadAgentActors(ctx context.Context, plugin *plugins.Plugin) error {
+	for _, pid := range _actorSystem.Actors() {
+		if actor, ok := pid.Actor().(*WasmAgentActor); ok {
+			if err := actor.reloadModule(ctx, plugin); err != nil {
+				return err
+			}
+		}
+	}
+
+	return nil
+}
+
+func beforeShutdown(ctx context.Context) error {
+	logger.Info(ctx).Msg("Actor system shutting down...")
+	return nil
+}
+
+func Shutdown(ctx context.Context) {
+	if _actorSystem == nil {
+		return
+	}
+
+	if err := _actorSystem.Stop(ctx); err != nil {
+		logger.Err(ctx, err).Msg("Failed to shutdown actor system.")
+	}
+
+	logger.Info(ctx).Msg("Actor system shutdown complete.")
+}