Add isolated SIP call tool, optional debug capture and split interface schemas

internal/config/agent_debug_test.go

@@ -0,0 +1,30 @@
+package config
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestAgentDebugEvidenceIsOptIn(t *testing.T) {
+	setAgentEnvironment(t)
+	t.Setenv("AGENT_MOCK_SCENARIO_FILE", "")
+	t.Setenv("AGENT_MOCK_APPLIED_SIP_FILE", "")
+	for k, v := range map[string]string{"ASTERISK_CONFIG_DIR": "/tmp/asterisk-config", "ASTERISK_BIN": "/tmp/asterisk", "ASTERISK_LIBRARY_DIR": "/tmp/lib", "AGENT_OSS_ALLOWED_HOST": "test.oss-cn-beijing.aliyuncs.com", "AGENT_HEP_LISTEN_ADDR": "127.0.0.1:19060", "AGENT_EVIDENCE_ROOT": ""} {
+		t.Setenv(k, v)
+	}
+	s, err := LoadAgentEnvironment("nonprod-real")
+	if err != nil {
+		t.Fatalf("normal operation must not require external capture: %v", err)
+	}
+	if err = s.ValidateDebug(); err != nil {
+		t.Fatal(err)
+	}
+	s.Debug = true
+	if err = s.ValidateDebug(); err == nil || !strings.Contains(err.Error(), "AGENT_EVIDENCE_ROOT") {
+		t.Fatalf("debug requires an absolute evidence root: %v", err)
+	}
+	s.EvidenceRoot = "/tmp/evidence"
+	if err = s.ValidateDebug(); err != nil {
+		t.Fatal(err)
+	}
+}

internal/config/agent_runtime.go

@@ -15,6 +15,7 @@ import (
 // AgentEnvironment is deployment-owned and is inspected without opening any
 // durable file, media adapter, credential or network connection.
 type AgentEnvironment struct {
+	Debug                bool
 	Mode                 string
 	AgentID              string
 	CellID               string
@@ -99,9 +100,7 @@ func LoadAgentEnvironment(mode string) (AgentEnvironment, error) {
 		*field.value = value
 	}
 	if mode == "nonprod-real" {
-		if settings.EvidenceRoot, err = get("AGENT_EVIDENCE_ROOT"); err != nil {
-			return AgentEnvironment{}, err
-		}
+		settings.EvidenceRoot = os.Getenv("AGENT_EVIDENCE_ROOT")
 		if settings.OSSAllowedHost, err = get("AGENT_OSS_ALLOWED_HOST"); err != nil {
 			return AgentEnvironment{}, err
 		}
@@ -122,9 +121,6 @@ func LoadAgentEnvironment(mode string) (AgentEnvironment, error) {
 		if !strings.HasPrefix(settings.HEPListen, "127.0.0.1:") || !localGRPCAddress(settings.HEPListen, false) {
 			return AgentEnvironment{}, errors.New("AGENT_HEP_LISTEN_ADDR must be an explicit IPv4 loopback address with a nonzero port")
 		}
-		if !filepath.IsAbs(settings.EvidenceRoot) {
-			return AgentEnvironment{}, errors.New("AGENT_EVIDENCE_ROOT must be absolute")
-		}
 		if os.Getenv("AGENT_MOCK_SCENARIO_FILE") != "" || os.Getenv("AGENT_MOCK_APPLIED_SIP_FILE") != "" {
 			return AgentEnvironment{}, errors.New("nonprod-real Agent cannot load isolated Mock fixtures")
 		}
@@ -140,6 +136,14 @@ func LoadAgentEnvironment(mode string) (AgentEnvironment, error) {
 	return settings, nil
 }
 
+// ValidateDebug only requires external capture configuration when explicitly enabled.
+func (s AgentEnvironment) ValidateDebug() error {
+	if s.Debug && s.Mode == "nonprod-real" && !filepath.IsAbs(s.EvidenceRoot) {
+		return errors.New("AGENT_EVIDENCE_ROOT must be absolute when --debug/-D is enabled")
+	}
+	return nil
+}
+
 func localGRPCAddress(raw string, allowZeroPort bool) bool {
 	host, port, err := net.SplitHostPort(raw)
 	if err != nil {

internal/config/agent_runtime_test.go

@@ -86,7 +86,7 @@ func TestLoadNonprodRealAgentRequiresNativeCallAndEvidenceSettings(t *testing.T)
 		}
 	}
 	t.Setenv("AGENT_HEP_LISTEN_ADDR", "127.0.0.1:19060")
-	for _, name := range []string{"ASTERISK_CONFIG_DIR", "ASTERISK_BIN", "ASTERISK_LIBRARY_DIR", "AGENT_EVIDENCE_ROOT", "AGENT_OSS_ALLOWED_HOST", "AGENT_HEP_LISTEN_ADDR", "DISPATCHER_GRPC_ENDPOINT", "DISPATCHER_GRPC_SERVER_NAME"} {
+	for _, name := range []string{"ASTERISK_CONFIG_DIR", "ASTERISK_BIN", "ASTERISK_LIBRARY_DIR", "AGENT_OSS_ALLOWED_HOST", "AGENT_HEP_LISTEN_ADDR", "DISPATCHER_GRPC_ENDPOINT", "DISPATCHER_GRPC_SERVER_NAME"} {
 		t.Run(name, func(t *testing.T) {
 			t.Setenv(name, "")
 			if _, err := LoadAgentEnvironment("nonprod-real"); err == nil || !strings.Contains(err.Error(), name) {