feat(local-notifications): add explicit local sudo notifications

Author: michaelw

docs/configuration/local-sudo.md

@@ -53,6 +53,9 @@ providers:
   local-presence:
     provider: local-presence
     enabled: true
+  local-notification:
+    provider: local-notification
+    enabled: true
 ```
 
 For full local macOS integration testing, install the Apple Development-signed privilege-services bundle with:
@@ -81,6 +84,8 @@ On macOS v1, timed sudo is brokered through the native privilege-services app bu
 
 If a workflow uses an approval notifier with `provider: local-presence`, the same signed helper can trigger a macOS device-owner authentication prompt on the routed device before `authorize` runs. The result is recorded through the normal approvals path, alongside Slack and email approval callbacks. This requires the target agent to be online in an interactive login session; CI and unit tests mock the LocalAuthentication result rather than invoking biometrics.
 
+Workflows can also opt into Thand-managed macOS notifications with `provider: local-notification` in `thand: notify`, approval notifiers, `authorize.with.notifiers`, or `revoke.with.notifiers`. These notifications are routed to the target `device_id` and posted by the signed helper through `UNUserNotificationCenter`. Broker-triggered lease notifications remain enabled separately for now.
+
 ## Account Mapping
 
 Per-device account mappings decide which local account receives sudo.

docs/configuration/workflows/tasks.md

@@ -191,6 +191,7 @@ notifiers:
 | `slack` | Slack notifications | Channel ID: `C0123456789` or User ID |
 | `email` | Email notifications | Email address |
 | `local-presence` | macOS device-owner approval prompt | `device_id` |
+| `local-notification` | macOS local user notification | `device_id` |
 
 ### Flow Control
 
@@ -491,21 +492,21 @@ The `notify` task sends notifications to users, administrators, or external syst
 - notify:
     thand: notify
     with:
-      approvals: number          # Number of approvals needed
-      notifiers:                  # Notification configuration
-        key:
-          provider: string
-          to: string
-          message: string
+      provider: string
+      to: string
+      message: string
+      device: string             # Optional; used by local-notification
     then: next-step
 ```
 
 ### Parameters
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `approvals` | number | Yes | Number of approvals required (for approval notifications) |
-| `notifier` | object | Yes | Notification configuration |
+| `provider` | string | Yes | Notification provider |
+| `to` | string or array | Yes | Recipient identity, channel, or email address |
+| `message` | string | No | Notification body |
+| `device` | string | No | Target device for `local-notification` |
 
 ### Notification Process
 
@@ -519,6 +520,9 @@ The notify task:
 
 - **Slack**: Sends rich notifications with approval buttons
 - **Email**: Sends email notifications
+- **Local Notification**: Sends a macOS user notification on a routed agent device with `provider: local-notification`
+
+`local-notification` requires a live macOS agent and a target device. Device resolution follows the explicit notifier `device` field first, then the request `device`, then request metadata `device_id`. The same routing applies when `local-notification` is used in `thand: notify`, `authorize.with.notifiers`, `revoke.with.notifiers`, or `approvals.with.notifiers` approval prompts. It uses the signed helper and `UNUserNotificationCenter`; it does not replace broker-triggered sudo lease notifications, which remain in place for now.
 
 ### Examples
 
@@ -527,12 +531,20 @@ The notify task:
 - slack-notify:
     thand: notify
     with:
-      approvals: 1
-      notifiers:
-        slack:
-          provider: slack
-          to: "C0123456789"
-          message: "Access granted to user"
+      provider: slack
+      to: "C0123456789"
+      message: "Access granted to user"
+```
+
+**macOS Local Notification**
+```yaml
+- local-notify:
+    thand: notify
+    with:
+      provider: local-notification
+      to: ${ $context.user.email }
+      device: "${ .device }"
+      message: "Your local sudo request was approved"
 ```
 
 **Note**: The notify task is primarily used internally by the approvals task. For standalone notifications, consider using standard Serverless Workflow `call` tasks to external APIs.

internal/config/environment/local/providers.yaml

@@ -18,3 +18,9 @@ providers:
     description: Local macOS device-owner approval prompts
     provider: local-presence
     enabled: true
+
+  local-notification:
+    name: Local Notification
+    description: Local macOS user notifications
+    provider: local-notification
+    enabled: true

internal/config/providers_local.go

@@ -2,5 +2,6 @@ package config
 
 import (
 	_ "github.com/thand-io/agent/internal/providers/local"
+	_ "github.com/thand-io/agent/internal/providers/localnotification"
 	_ "github.com/thand-io/agent/internal/providers/localpresence"
 )

internal/localbroker/client.go

@@ -25,6 +25,7 @@ const (
 	OperationExecCommand        Operation = "exec_command"
 	OperationPTYSession         Operation = "pty_session"
 	OperationCheckLocalPresence Operation = "check_local_presence"
+	OperationPostNotification   Operation = "post_local_notification"
 
 	DefaultControlExecutable = "/Library/Application Support/Thand/PrivilegeBroker/bin/thand-macos-privilege-brokerctl"
 	DefaultMachServiceLabel  = "io.thand.agent.privilege-broker"
@@ -38,6 +39,7 @@ type Client interface {
 	GrantTimedSudoers(ctx context.Context, req TimedSudoersGrantRequest) (*TimedSudoersGrantResponse, error)
 	RevokeTimedGrant(ctx context.Context, handle string) (*RevokeTimedGrantResponse, error)
 	CheckLocalPresence(ctx context.Context, req CheckLocalPresenceRequest) (*CheckLocalPresenceResponse, error)
+	PostLocalNotification(ctx context.Context, req PostLocalNotificationRequest) (*PostLocalNotificationResponse, error)
 }
 
 type TimedSudoersGrantRequest struct {
@@ -153,6 +155,18 @@ type CheckLocalPresenceResponse struct {
 	FailureReason   string    `json:"failure_reason,omitempty"`
 }
 
+type PostLocalNotificationRequest struct {
+	NotificationID string `json:"notification_id,omitempty"`
+	Title          string `json:"title"`
+	Subtitle       string `json:"subtitle,omitempty"`
+	Body           string `json:"body"`
+	ThreadID       string `json:"thread_id,omitempty"`
+}
+
+type PostLocalNotificationResponse struct {
+	Posted bool `json:"posted"`
+}
+
 type helperSession struct {
 	dial        func(context.Context, string) (net.Conn, error)
 	wait        func() error
@@ -260,6 +274,19 @@ func (c *CommandClient) CheckLocalPresence(ctx context.Context, req CheckLocalPr
 	})
 }
 
+func (c *CommandClient) PostLocalNotification(ctx context.Context, req PostLocalNotificationRequest) (*PostLocalNotificationResponse, error) {
+	return invokeHelperRPC(ctx, c, OperationPostNotification, func(ctx context.Context, client localbrokerv1.LocalBrokerControlClient) (*PostLocalNotificationResponse, error) {
+		response, err := client.PostLocalNotification(ctx, localNotificationProtoRequest(req))
+		if err != nil {
+			return nil, err
+		}
+
+		return &PostLocalNotificationResponse{
+			Posted: response.GetPosted(),
+		}, nil
+	})
+}
+
 func IsRetryableError(err error) bool {
 	switch status.Code(err) {
 	case codes.Unavailable, codes.DeadlineExceeded, codes.Canceled:
@@ -374,6 +401,16 @@ func localPresenceProtoRequest(req CheckLocalPresenceRequest) *localbrokerv1.Che
 	}
 }
 
+func localNotificationProtoRequest(req PostLocalNotificationRequest) *localbrokerv1.PostLocalNotificationRequest {
+	return &localbrokerv1.PostLocalNotificationRequest{
+		NotificationId: req.NotificationID,
+		Title:          req.Title,
+		Subtitle:       req.Subtitle,
+		Body:           req.Body,
+		ThreadId:       req.ThreadID,
+	}
+}
+
 func (c *CommandClient) helperArguments() []string {
 	args := []string{
 		defaultHelperCommand,

internal/localbroker/client_test.go

@@ -31,6 +31,10 @@ type fakeLocalBrokerControlServer struct {
 	presenceResponse *localbrokerv1.CheckLocalPresenceResponse
 	presenceError    error
 	presenceRequest  *localbrokerv1.CheckLocalPresenceRequest
+
+	notificationResponse *localbrokerv1.PostLocalNotificationResponse
+	notificationError    error
+	notificationRequest  *localbrokerv1.PostLocalNotificationRequest
 }
 
 func (f *fakeLocalBrokerControlServer) GrantTimedSudoers(
@@ -84,6 +88,22 @@ func (f *fakeLocalBrokerControlServer) CheckLocalPresence(
 	}, nil
 }
 
+func (f *fakeLocalBrokerControlServer) PostLocalNotification(
+	_ context.Context,
+	req *localbrokerv1.PostLocalNotificationRequest,
+) (*localbrokerv1.PostLocalNotificationResponse, error) {
+	f.notificationRequest = req
+	if f.notificationError != nil {
+		return nil, f.notificationError
+	}
+	if f.notificationResponse != nil {
+		return f.notificationResponse, nil
+	}
+	return &localbrokerv1.PostLocalNotificationResponse{
+		Posted: true,
+	}, nil
+}
+
 func grpcTestStarter(
 	t *testing.T,
 	server *fakeLocalBrokerControlServer,
@@ -427,6 +447,39 @@ func TestCheckLocalPresencePassesPromptContext(t *testing.T) {
 	}
 }
 
+func TestPostLocalNotificationPassesNotificationPayload(t *testing.T) {
+	server := &fakeLocalBrokerControlServer{}
+	client := &CommandClient{
+		executable:   "/test/brokerctl",
+		serviceLabel: "io.thand.agent.privilege-broker",
+		start:        grpcTestStarter(t, server, "", nil),
+	}
+
+	response, err := client.PostLocalNotification(context.Background(), PostLocalNotificationRequest{
+		NotificationID: "notification-1",
+		Title:          "Access approved",
+		Subtitle:       "Local Sudo",
+		Body:           "Your sudo access is ready",
+		ThreadID:       "workflow-1",
+	})
+	if err != nil {
+		t.Fatalf("PostLocalNotification returned error: %v", err)
+	}
+
+	if got, want := server.notificationRequest.GetNotificationId(), "notification-1"; got != want {
+		t.Fatalf("notification_id = %q, want %q", got, want)
+	}
+	if got, want := server.notificationRequest.GetTitle(), "Access approved"; got != want {
+		t.Fatalf("title = %q, want %q", got, want)
+	}
+	if got, want := server.notificationRequest.GetBody(), "Your sudo access is ready"; got != want {
+		t.Fatalf("body = %q, want %q", got, want)
+	}
+	if !response.Posted {
+		t.Fatal("expected posted response")
+	}
+}
+
 func TestIsRetryableError(t *testing.T) {
 	if !IsRetryableError(status.Error(codes.Unavailable, "transport interrupted")) {
 		t.Fatal("expected unavailable to be retryable")

internal/models/local_notification.go

@@ -0,0 +1,10 @@
+package models
+
+type LocalNotificationRequest struct {
+	NotificationID string `json:"notification_id,omitempty"`
+	DeviceID       string `json:"device_id,omitempty"`
+	Title          string `json:"title"`
+	Subtitle       string `json:"subtitle,omitempty"`
+	Body           string `json:"body"`
+	ThreadID       string `json:"thread_id,omitempty"`
+}

internal/providers/local/main_test.go

@@ -1022,6 +1022,10 @@ func (f *fakeBrokerClient) CheckLocalPresence(ctx context.Context, req localbrok
 	return f.presenceResponse, nil
 }
 
+func (f *fakeBrokerClient) PostLocalNotification(context.Context, localbroker.PostLocalNotificationRequest) (*localbroker.PostLocalNotificationResponse, error) {
+	return &localbroker.PostLocalNotificationResponse{Posted: true}, nil
+}
+
 type fakeEnforcer struct {
 	revokeFn func(meta models.LocalSudoAuthorizationMetadata) error
 }

internal/providers/localnotification/activities.go

@@ -0,0 +1,18 @@
+package localnotification
+
+import (
+	"context"
+
+	"github.com/thand-io/agent/internal/models"
+)
+
+type localNotificationProviderActivities struct {
+	provider *localNotificationProvider
+}
+
+func (a *localNotificationProviderActivities) SendNotificationActivity(
+	ctx context.Context,
+	notification models.NotificationRequest,
+) error {
+	return a.provider.SendNotification(ctx, notification)
+}

internal/providers/localnotification/capabilities.go

@@ -0,0 +1,6 @@
+package localnotification
+
+import "github.com/thand-io/agent/internal/models"
+
+var LocalNotificationCapabilities = models.NewProviderCapabilities().
+	WithDefaultNotifierConfiguration()