feat(sdk): align capabilities and complete documentation

Author: ZhiXiao-Lin

Cargo.lock

@@ -138,19 +138,32 @@ report, err := session.VerifyCommands(ctx, "release", []code.VerificationCommand
 _, _, _, _ = content, result, matches, report
 ```
 
-The stable surface includes:
-
-- Agent creation, session creation/resume/list/close, and MCP refresh.
-- `Send`, `Run`, `Stream`, history, save, cancellation, and close.
+The stable surface is aligned with the Node.js and Python SDKs for
+serializable Agent and Session capabilities, including:
+
+- Agent creation, session creation/resume/replace/list/close, worker sessions,
+  MCP refresh/idle disconnect, and agent-directory serving.
+- `Send`, `Run`, `Stream`, attachments, checkpoint resume, history, save,
+  cancellation, and close.
+- Parallel, resumable parallel, workflow-step, and pipeline orchestration.
 - Generic `Tool` plus file, shell, search, Git, web, QuickJS program, and
   delegated-task conveniences.
 - Run snapshots and replay events, active tools, traces, artifacts, pending
-  confirmations, and verification reports.
-- Live agent directories, skills, and MCP server add/remove/status.
-
-Rust trait-object injections such as custom `LlmClient`, workspace backends,
-hook executors, and memory implementations are intentionally Rust-only. The Go
-bridge accepts their serializable configuration counterparts where one exists.
+  confirmations, subagent tasks, and verification reports.
+- Memory recall/recording, lane queues, external tasks, dead letters, and
+  queue metrics.
+- Go-backed lifecycle hooks, budget guards, and slash commands through the
+  callback transport.
+- Live agent directories, workers, skills, dynamic workflows, and MCP server
+  add/remove/status.
+- File memory/session persistence, default security, local or S3 workspaces,
+  remote Git, permission/confirmation policies, retention, trajectory,
+  deterministic ID/clock replay, delegation, and prompt-slot configuration.
+
+Rust trait-object injections such as a custom `LlmClient`, arbitrary workspace
+implementation, or custom memory store implementation remain Rust-native
+extension points. The Go SDK exposes every corresponding serializable
+configuration and callback-backed extension point.
 
 ## Errors
 

sdk/go/README.md

@@ -175,16 +175,96 @@ func (agent *Agent) ResumeSession(
 	return agent.newSession(ctx, op, params)
 }
 
+func (agent *Agent) ReplaceSession(
+	ctx context.Context,
+	current *Session,
+	options *SessionOptions,
+) (*Session, error) {
+	const op = "agent_replace_session"
+	if err := validateAgent(agent, ctx, op); err != nil {
+		return nil, err
+	}
+	if current == nil || current.handle == "" {
+		return nil, invalid(op, "current session is not initialized")
+	}
+	params := current.params()
+	params["agent_id"] = agent.id
+	if options != nil {
+		params["options"] = options
+	}
+	return agent.newSession(ctx, op, params)
+}
+
+func (agent *Agent) SessionForAgent(
+	ctx context.Context,
+	workspace string,
+	agentName string,
+	agentDirs []string,
+	options *SessionOptions,
+) (*Session, error) {
+	const op = "agent_session_for_agent"
+	if err := validateAgent(agent, ctx, op); err != nil {
+		return nil, err
+	}
+	if strings.TrimSpace(workspace) == "" {
+		return nil, invalid(op, "workspace cannot be empty")
+	}
+	if strings.TrimSpace(agentName) == "" {
+		return nil, invalid(op, "agent name cannot be empty")
+	}
+	params := map[string]any{
+		"agent_id":   agent.id,
+		"workspace":  workspace,
+		"agent_name": agentName,
+		"agent_dirs": agentDirs,
+	}
+	if options != nil {
+		params["options"] = options
+	}
+	return agent.newSession(ctx, op, params)
+}
+
+func (agent *Agent) SessionForWorker(
+	ctx context.Context,
+	workspace string,
+	worker WorkerAgentSpec,
+	options *SessionOptions,
+) (*Session, error) {
+	const op = "agent_session_for_worker"
+	if err := validateAgent(agent, ctx, op); err != nil {
+		return nil, err
+	}
+	if strings.TrimSpace(workspace) == "" {
+		return nil, invalid(op, "workspace cannot be empty")
+	}
+	if strings.TrimSpace(worker.Name) == "" || strings.TrimSpace(worker.Description) == "" {
+		return nil, invalid(op, "worker name and description cannot be empty")
+	}
+	params := map[string]any{
+		"agent_id":  agent.id,
+		"workspace": workspace,
+		"worker":    worker,
+	}
+	if options != nil {
+		params["options"] = options
+	}
+	return agent.newSession(ctx, op, params)
+}
+
 func (agent *Agent) newSession(
 	ctx context.Context,
 	operation string,
 	params map[string]any,
 ) (*Session, error) {
 	var created struct {
-		SessionHandle string  `json:"session_handle"`
-		SessionID     string  `json:"session_id"`
-		Workspace     string  `json:"workspace"`
-		InitWarning   *string `json:"init_warning"`
+		SessionHandle   string  `json:"session_handle"`
+		SessionID       string  `json:"session_id"`
+		Workspace       string  `json:"workspace"`
+		InitWarning     *string `json:"init_warning"`
+		TenantID        *string `json:"tenant_id"`
+		Principal       *string `json:"principal"`
+		AgentTemplateID *string `json:"agent_template_id"`
+		CorrelationID   *string `json:"correlation_id"`
 	}
 	if err := agent.runtime.Request(ctx, operation, params, &created); err != nil {
 		return nil, err
@@ -198,11 +278,15 @@ func (agent *Agent) newSession(
 		)
 	}
 	return &Session{
-		runtime:     agent.runtime,
-		handle:      created.SessionHandle,
-		id:          created.SessionID,
-		workspace:   created.Workspace,
-		initWarning: created.InitWarning,
+		runtime:         agent.runtime,
+		handle:          created.SessionHandle,
+		id:              created.SessionID,
+		workspace:       created.Workspace,
+		initWarning:     created.InitWarning,
+		tenantID:        created.TenantID,
+		principal:       created.Principal,
+		agentTemplateID: created.AgentTemplateID,
+		correlationID:   created.CorrelationID,
 	}, nil
 }
 
@@ -251,6 +335,80 @@ func (agent *Agent) CloseSession(ctx context.Context, sessionID string) (bool, e
 	return result.Closed, err
 }
 
+func (agent *Agent) DisconnectIdleMCP(
+	ctx context.Context,
+	idleThresholdMS uint64,
+) ([]string, error) {
+	const op = "agent_disconnect_idle_mcp"
+	if err := validateAgent(agent, ctx, op); err != nil {
+		return nil, err
+	}
+	var result struct {
+		Names []string `json:"names"`
+	}
+	err := agent.runtime.Request(ctx, op, map[string]any{
+		"agent_id":          agent.id,
+		"idle_threshold_ms": idleThresholdMS,
+	}, &result)
+	return result.Names, err
+}
+
+type ServeHandle struct {
+	runtime  Runtime
+	handle   string
+	stopOnce sync.Once
+	stopErr  error
+}
+
+func (agent *Agent) ServeAgentDir(
+	ctx context.Context,
+	dir string,
+	workspace string,
+	options *SessionOptions,
+) (*ServeHandle, error) {
+	const op = "agent_serve_agent_dir"
+	if err := validateAgent(agent, ctx, op); err != nil {
+		return nil, err
+	}
+	if strings.TrimSpace(dir) == "" || strings.TrimSpace(workspace) == "" {
+		return nil, invalid(op, "agent directory and workspace cannot be empty")
+	}
+	params := map[string]any{
+		"agent_id":  agent.id,
+		"dir":       dir,
+		"workspace": workspace,
+	}
+	if options != nil {
+		params["options"] = options
+	}
+	var result struct {
+		Handle string `json:"serve_handle"`
+	}
+	if err := agent.runtime.Request(ctx, op, params, &result); err != nil {
+		return nil, err
+	}
+	if result.Handle == "" {
+		return nil, sdkError(op, CodeProtocol, "bridge returned an empty serve handle", nil)
+	}
+	return &ServeHandle{runtime: agent.runtime, handle: result.Handle}, nil
+}
+
+func (handle *ServeHandle) Stop(ctx context.Context) error {
+	const op = "agent_stop_serve"
+	if handle == nil {
+		return nil
+	}
+	if ctx == nil {
+		return invalid(op, "context cannot be nil")
+	}
+	handle.stopOnce.Do(func() {
+		handle.stopErr = handle.runtime.Request(ctx, op, map[string]any{
+			"serve_handle": handle.handle,
+		}, nil)
+	})
+	return handle.stopErr
+}
+
 func (agent *Agent) IsClosed(ctx context.Context) (bool, error) {
 	const op = "agent_is_closed"
 	if err := validateAgent(agent, ctx, op); err != nil {

sdk/go/agent.go

@@ -21,6 +21,12 @@ func TestCreateSessionAndCloseWithInjectedRuntime(t *testing.T) {
 				}
 				return map[string]any{"agent_id": "agent-1"}, nil
 			case "session_create":
+				options, ok := params["options"].(*SessionOptions)
+				if !ok || options.HostEnv == nil ||
+					options.HostEnv.SequentialIDPrefix == nil ||
+					*options.HostEnv.SequentialIDPrefix != "replay" {
+					t.Fatalf("deterministic host env was not forwarded: %#v", params)
+				}
 				return map[string]any{
 					"session_handle": "handle-1",
 					"session_id":     "session-1",
@@ -45,8 +51,14 @@ func TestCreateSessionAndCloseWithInjectedRuntime(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
+	prefix := "replay"
+	fixedTime := uint64(1_700_000_000_000)
 	session, err := agent.Session(ctx, "C:/repo", &SessionOptions{
 		SessionID: "session-1",
+		HostEnv: &HostEnvConfig{
+			SequentialIDPrefix: &prefix,
+			FixedTimeMS:        &fixedTime,
+		},
 	})
 	if err != nil {
 		t.Fatal(err)

sdk/go/agent_test.go

@@ -17,7 +17,10 @@ name = "a3s-code-go-bridge"
 path = "src/main.rs"
 
 [dependencies]
-a3s-code-core = { version = "6.5.2", path = "../../../core" }
+a3s-code-core = { version = "6.5.2", path = "../../../core", features = ["s3", "serve"] }
+async-trait = "0.1"
+anyhow = "1.0"
+base64 = "0.22"
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
 tokio = { version = "1.35", features = [
@@ -28,6 +31,7 @@ tokio = { version = "1.35", features = [
     "sync",
     "time",
 ] }
+tokio-util = { version = "0.7" }
 
 [dev-dependencies]
 tempfile = "3.10"