fixes

.gitignore

@@ -21,5 +21,5 @@ logs/
 .cache
 .gocache
 .conductor
-
+.tmp-go/
 .claude/worktrees/

.goreleaser.yml

@@ -0,0 +1,49 @@
+version: 2
+
+builds:
+  - id: agentremote
+    main: ./cmd/agentremote
+    binary: agentremote
+    env:
+      - CGO_ENABLED=1
+    goos:
+      - darwin
+      - linux
+    goarch:
+      - amd64
+      - arm64
+    ldflags:
+      - -s -w
+      - -X main.Tag={{.Tag}}
+      - -X main.Commit={{.Commit}}
+      - -X main.BuildTime={{.Date}}
+
+archives:
+  - id: agentremote
+    builds:
+      - agentremote
+    format: tar.gz
+    name_template: "agentremote_{{ .Os }}_{{ .Arch }}"
+
+brews:
+  - name: agentremote
+    ids:
+      - agentremote
+    repository:
+      owner: beeper
+      name: homebrew-tap
+    homepage: https://github.com/beeper/agentremote
+    description: Unified AI bridge manager for Beeper
+    license: Apache-2.0
+    install: |
+      bin.install "agentremote"
+
+checksum:
+  name_template: "checksums.txt"
+
+changelog:
+  sort: asc
+  filters:
+    exclude:
+      - "^docs:"
+      - "^test:"

README.md

@@ -29,13 +29,135 @@ That means:
 
 There is a broader product direction around richer AI chats and more opinionated agent experiences. Open source here is focused on making the bridge layer for private deployments easy to run and hard to break.
 
+## AgentRemote SDK
+
+If you want to build your own bridge, start with the SDK in [`sdk/`](./sdk).
+
+The SDK handles the Matrix and Beeper side of the bridge for you:
+
+- bridge bootstrapping and registration
+- room and conversation wrappers
+- streaming turn lifecycle
+- tool approval UI
+- agent identity and capability metadata
+
+The main entrypoint is `sdk.New(sdk.Config{...})`.
+
+In practice, most custom bridges only need three things:
+
+- an `sdk.Agent` that represents the remote assistant in Beeper
+- an `OnConnect` hook that builds whatever runtime client you need
+- an `OnMessage` hook that turns an incoming Beeper message into model output
+
+### Minimal SDK Shape
+
+This is the smallest useful shape of a bridge:
+
+```go
+bridge := sdk.New(sdk.Config{
+	Name: "my-bridge",
+	Agent: &sdk.Agent{
+		ID:           "my-agent",
+		Name:         "My Agent",
+		Description:  "A custom agent exposed through Beeper",
+		ModelKey:     "openai/gpt-5-mini",
+		Capabilities: sdk.BaseAgentCapabilities(),
+	},
+	OnConnect: func(ctx context.Context, login *sdk.LoginInfo) (any, error) {
+		return newRuntimeClient(), nil
+	},
+	OnMessage: func(session any, conv *sdk.Conversation, msg *sdk.Message, turn *sdk.Turn) error {
+		turn.WriteText("hello from my bridge")
+		turn.End("stop")
+		return nil
+	},
+})
+
+bridge.Run()
+```
+
+`turn` is the important piece here. You can write text and reasoning deltas into it, request approvals, attach sources/files, and then finalize the message with `turn.End(...)` or `turn.EndWithError(...)`.
+
+### Simple OpenAI SDK Bridge
+
+The example below is intentionally minimal. It uses the Go OpenAI SDK directly and lets AgentRemote handle the chat room, sender identity, and message lifecycle.
+
+```go
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"os"
+
+	"github.com/beeper/agentremote/sdk"
+	"github.com/openai/openai-go/v3"
+	"github.com/openai/openai-go/v3/option"
+)
+
+func main() {
+	if os.Getenv("OPENAI_API_KEY") == "" {
+		log.Fatal("OPENAI_API_KEY is required")
+	}
+
+	bridge := sdk.New(sdk.Config{
+		Name:        "openai-simple",
+		Description: "A minimal OpenAI-backed AgentRemote bridge",
+		Agent: &sdk.Agent{
+			ID:           "openai-simple-agent",
+			Name:         "OpenAI Simple",
+			Description:  "Minimal bridge example using openai-go",
+			ModelKey:     "openai/gpt-4o-mini",
+			Capabilities: sdk.BaseAgentCapabilities(),
+		},
+		OnConnect: func(ctx context.Context, login *sdk.LoginInfo) (any, error) {
+			return openai.NewClient(option.WithAPIKey(os.Getenv("OPENAI_API_KEY"))), nil
+		},
+		OnMessage: func(session any, conv *sdk.Conversation, msg *sdk.Message, turn *sdk.Turn) error {
+			client := session.(*openai.Client)
+
+			resp, err := client.Chat.Completions.New(turn.Context(), openai.ChatCompletionNewParams{
+				Model: "gpt-4o-mini",
+				Messages: []openai.ChatCompletionMessageParamUnion{
+					openai.SystemMessage("You are a helpful assistant replying through Beeper."),
+					openai.UserMessage(msg.Text),
+				},
+			})
+			if err != nil {
+				turn.EndWithError(err.Error())
+				return err
+			}
+			if len(resp.Choices) == 0 {
+				err := fmt.Errorf("openai returned no choices")
+				turn.EndWithError(err.Error())
+				return err
+			}
+
+			turn.WriteText(resp.Choices[0].Message.Content)
+			turn.End(resp.Choices[0].FinishReason)
+			return nil
+		},
+	})
+
+	bridge.Run()
+}
+```
+
+Useful details from that example:
+
+- `OnConnect` returns the session object that will be passed back into every `OnMessage` call.
+- `sdk.Message` already gives you the normalized incoming Beeper message text.
+- `sdk.Turn` is where you stream or finalize the assistant reply.
+- If you want live token streaming later, switch the OpenAI call to `client.Chat.Completions.NewStreaming(...)` or `client.Responses.NewStreaming(...)` and forward deltas with `turn.WriteText(...)`.
+
 ## Included Bridges
 
 Each bridge has its own README with setup details and scope:
 
 | Bridge | Purpose |
 | --- | --- |
-| `ai` | General Matrix-to-AI bridge surface used by the project |
+| `ai` | AI Chats bridge surface used by the project |
 | [`codex`](./bridges/codex/README.md) | Connect the Codex CLI app-server to Beeper |
 | [`openclaw`](./bridges/openclaw/README.md) | Connect a self-hosted OpenClaw gateway to Beeper |
 | [`opencode`](./bridges/opencode/README.md) | Connect a self-hosted OpenCode server to Beeper |
@@ -59,7 +181,7 @@ For a local Beeper environment:
 ./tools/bridges run codex
 ```
 
-Configured instances in `bridges.manifest.yml`:
+Configured instances live under `~/.config/agentremote/profiles/<profile>/instances/`:
 
 - `ai`
 - `codex`

bridgectl.sh → agentremote.sh

@@ -1,4 +1,4 @@
 #!/usr/bin/env bash
 set -euo pipefail
 cd "$(dirname "$0")"
-go run ./cmd/bridgectl "$@"
+go run ./cmd/agentremote "$@"

pkg/bridgeadapter/approval_decision.go → approval_decision.go

@@ -1,10 +1,22 @@
-package bridgeadapter
+package agentremote
 
 import (
 	"errors"
 	"strings"
 )
 
+// Approval decision reason constants.
+const (
+	ApprovalReasonAllowOnce     = "allow_once"
+	ApprovalReasonAllowAlways   = "allow_always"
+	ApprovalReasonAutoApproved  = "auto_approved"
+	ApprovalReasonDeny          = "deny"
+	ApprovalReasonTimeout       = "timeout"
+	ApprovalReasonExpired       = "expired"
+	ApprovalReasonCancelled     = "cancelled"
+	ApprovalReasonDeliveryError = "delivery_error"
+)
+
 // ApprovalDecisionPayload is the standardized decision type for all approval flows.
 type ApprovalDecisionPayload struct {
 	ApprovalID string