Wanaku MCP Server

# gRPC Bridge Architecture

This document describes the gRPC bridge component that mediates communication between the Wanaku router and remote capability services.

## Architecture Overview

The gRPC bridge implements a transport-agnostic architecture using composition:

```
┌─────────────────────────────────────────────────────────────────┐
│                      Bridge Interfaces                          │
│   ┌─────────────┐  ┌──────────────┐  ┌───────────────────┐     │
│   │ ToolsBridge │  │ResourceBridge│  │CodeExecutorBridge │     │
│   └──────┬──────┘  └──────┬───────┘  └─────────┬─────────┘     │
├──────────┼────────────────┼────────────────────┼────────────────┤
│          │                │                    │                │
│   ┌──────▼──────┐  ┌──────▼───────────┐  ┌─────▼──────────┐    │
│   │InvokerBridge│  │ResourceAcquirer- │  │CodeExecution-  │    │
│   │             │  │Bridge            │  │Bridge          │    │
│   └──────┬──────┘  └──────┬───────────┘  └─────┬──────────┘    │
├──────────┼────────────────┼────────────────────┼────────────────┤
│                    Transport Abstraction                        │
│                  WanakuBridgeTransport                          │
├─────────────────────────────────────────────────────────────────┤
│                    gRPC Implementation                          │
│   ┌─────────────────┐      ┌────────────────────┐              │
│   │  GrpcTransport  │──────│ GrpcChannelManager │              │
│   └────────┬────────┘      └────────────────────┘              │
│            │                                                    │
│   ┌────────▼────────┐                                          │
│   │ProvisioningService│                                         │
│   └─────────────────┘                                          │
└─────────────────────────────────────────────────────────────────┘
```

Key characteristics:
- Protocol independence via transport abstraction
- Service discovery integration for dynamic endpoint resolution
- Event emission for observability
- Streaming support for code execution
- Composition over inheritance

---

## Core Abstractions

### Bridge Interface

**Package:** `ai.wanaku.backend.bridge`

Base marker interface for all bridge implementations.

```java
public interface Bridge {
    default String name() {
        return this.getClass().getSimpleName();
    }
}
```

### WanakuBridgeTransport Interface

**Package:** `ai.wanaku.backend.bridge`

Core transport abstraction defining the contract for all transport implementations.

```java
public interface WanakuBridgeTransport {

    ProvisioningReference provision(
        String name,
        String configData,
        String secretsData,
        ServiceTarget service
    );

    ToolInvokeReply invokeTool(
        ToolInvokeRequest request,
        ServiceTarget service
    );

    ResourceReply acquireResource(
        ResourceRequest request,
        ServiceTarget service
    );

    Iterator<CodeExecutionReply> executeCode(
        CodeExecutionRequest request,
        ServiceTarget service
    );
}
```

This abstraction enables:
- Protocol independence (supports gRPC, HTTP, WebSocket)
- Testability (easy mocking)
- Separation of concerns

---

## Bridge Interfaces

### ToolsBridge

Contract for tool proxy implementations.

```java
public interface ToolsBridge extends Bridge {
    ProvisioningReference provision(ToolPayload payload);
    ToolExecutor getExecutor();
}
```

### ResourceBridge

Contract for resource proxy implementations.

```java
public interface ResourceBridge extends Bridge {
    ProvisioningReference provision(ResourcePayload payload);
    List<ResourceContents> eval(
        ResourceManager.ResourceArguments arguments,
        ResourceReference mcpResource
    );
}
```

### CodeExecutorBridge

Contract for code execution bridge implementations.

```java
public interface CodeExecutorBridge extends Bridge {
    Iterator<CodeExecutionReply> executeCode(
        String engineType,
        String language,
        CodeExecutionRequest request
    );
}
```

---

## gRPC Transport Layer

### GrpcChannelManager

**Package:** `ai.wanaku.backend.bridge.transports.grpc`

Manages gRPC channel lifecycle.

```java
class GrpcChannelManager {

    public ManagedChannel createChannel(ServiceTarget service) {
        return ManagedChannelBuilder
            .forTarget(service.toAddress())
            .usePlaintext()
            .build();
    }

    public void closeChannel(ManagedChannel channel) {
        if (channel != null && !channel.isShutdown()) {
            channel.shutdown();
        }
    }
}
```

**Characteristics:**
- Creates plaintext gRPC channels
- Robust error handling during shutdown
- Design allows for future SSL/TLS support

### GrpcTransport

**Package:** `ai.wanaku.backend.bridge.transports.grpc`

Central coordinator for all gRPC transport operations.

```java
public class GrpcTransport implements WanakuBridgeTransport {
    private final GrpcChannelManager channelManager;
    private final ProvisioningService provisioningService;

    public GrpcTransport() {
        this.channelManager = new GrpcChannelManager();
        this.provisioningService = new ProvisioningService();
    }

    @Override
    public ProvisioningReference provision(
            String name, String configData, String secretsData,
            ServiceTarget service) {
        // Build Configuration and Secret protobuf objects
        // Delegate to ProvisioningService
    }

    @Override
    public ToolInvokeReply invokeTool(
            ToolInvokeRequest request, ServiceTarget service) {
        ManagedChannel channel = channelManager.createChannel(service);
        try {
            ToolInvokerGrpc.ToolInvokerBlockingStub stub =
                ToolInvokerGrpc.newBlockingStub(channel);
            return stub.invokeTool(request);
        } catch (Exception e) {
            throw new ServiceUnavailableException(e);
        }
    }

    @Override
    public ResourceReply acquireResource(
            ResourceRequest request, ServiceTarget service) {
        ManagedChannel channel = channelManager.createChannel(service);
        try {
            ResourceAcquirerGrpc.ResourceAcquirerBlockingStub stub =
                ResourceAcquirerGrpc.newBlockingStub(channel);
            return stub.resourceAcquire(request);
        } catch (Exception e) {
            throw new ServiceUnavailableException(e);
        }
    }

    @Override
    public Iterator<CodeExecutionReply> executeCode(
            CodeExecutionRequest request, ServiceTarget service) {
        ManagedChannel channel = channelManager.createChannel(service);
        try {
            CodeExecutorGrpc.CodeExecutorBlockingStub stub =
                CodeExecutorGrpc.newBlockingStub(channel);
            return stub.executeCode(request);
        } catch (Exception e) {
            throw new ServiceUnavailableException(e);
        }
    }
}
```

### ProvisioningService

**Package:** `ai.wanaku.backend.bridge`

Encapsulates provisioning logic for all bridge types.

```java
public class ProvisioningService {

    public ProvisioningReference provision(
            Configuration cfg,
            Secret secret,
            ManagedChannel channel,
            ServiceTarget service) {

        ProvisionRequest request = ProvisionRequest.newBuilder()
            .setUri(service.toAddress())
            .setConfiguration(cfg)
            .setSecret(secret)
            .build();

        ProvisionerGrpc.ProvisionerBlockingStub stub =
            ProvisionerGrpc.newBlockingStub(channel);

        ProvisionReply reply = stub.provision(request);

        return new ProvisioningReference(
            reply.getConfigurationUri(),
            reply.getSecretUri(),
            reply.getPropertiesMap()
        );
    }
}
```

---

## Bridge Implementations

### InvokerBridge

**Package:** `ai.wanaku.backend.bridge`

Proxy for tool invocation services.

```java
public class InvokerBridge implements ToolsBridge {
    private static final String SERVICE_TYPE_TOOL_INVOKER = "tool-invoker";

    private final ServiceResolver serviceResolver;
    private final WanakuBridgeTransport transport;
    private final ToolExecutor executor;

    public InvokerBridge(
            ServiceResolver serviceResolver,
            WanakuBridgeTransport transport,
            MutinyEmitter<ToolCallEvent> toolCallEventEmitter) {
        this.serviceResolver = serviceResolver;
        this.transport = transport;
        this.executor = new InvokerToolExecutor(
            serviceResolver, transport, toolCallEventEmitter);
    }

    @Override
    public ToolExecutor getExecutor() {
        return executor;
    }

    @Override
    public ProvisioningReference provision(ToolPayload toolPayload) {
        ToolReference ref = toolPayload.getToolReference();
        ServiceTarget service = resolveService(
            ref.getType(), SERVICE_TYPE_TOOL_INVOKER);
        return transport.provision(
            ref.getName(),
            toolPayload.getConfigData(),
            toolPayload.getSecretsData(),
            service
        );
    }

    private ServiceTarget resolveService(String type, String serviceType) {
        ServiceTarget service = serviceResolver.resolve(type, serviceType);
        if (service == null) {
            throw new ServiceNotFoundException(type, serviceType);
        }
        return service;
    }
}
```

### InvokerToolExecutor

**Package:** `ai.wanaku.backend.bridge`

Handles actual tool execution by delegating to remote services.

```java
public class InvokerToolExecutor implements ToolExecutor {
    private final ServiceResolver serviceResolver;
    private final WanakuBridgeTransport transport;
    private final MutinyEmitter<ToolCallEvent> toolCallEventEmitter;

    @Override
    public ToolResponse execute(
            ToolManager.ToolArguments toolArguments,
            CallableReference toolReference) {

        if (!(toolReference instanceof ToolReference)) {
            throw new UnsupportedOperationException();
        }

        return executeToolReference(toolArguments, (ToolReference) toolReference);
    }

    private ToolResponse executeToolReference(
            ToolManager.ToolArguments toolArguments,
            ToolReference toolReference) {

        // 1. Resolve service (try TOOL_INVOKER, fallback to CODE_EXECUTION_ENGINE)
        ServiceTarget service = resolveServiceWithFallback(toolReference);

        // 2. Build request
        ToolInvokeRequest request = buildToolInvokeRequest(
            toolReference, toolArguments);

        // 3. Emit STARTED event
        ToolCallEvent startedEvent = emitStartedEvent(toolReference, toolArguments);
        long startTime = System.currentTimeMillis();

        try {
            // 4. Invoke tool
            ToolInvokeReply reply = transport.invokeTool(request, service);

            // 5. Emit completion event
            long duration = System.currentTimeMillis() - startTime;
            if (reply.getIsError()) {
                emitFailedEvent(startedEvent.getId(),
                    categorizeToolError(reply.getContent(0)),
                    reply.getContent(0), duration);
            } else {
                emitCompletedEvent(startedEvent.getId(),
                    String.join("\n", reply.getContentList()), duration);
            }

            // 6. Process reply
            return processToolInvokeReply(reply);

        } catch (Exception e) {
            long duration = System.currentTimeMillis() - startTime;
            emitFailedEvent(startedEvent.getId(),
                categorizeException(e), e.getMessage(), duration);
            throw e;
        }
    }

    private ToolInvokeRequest buildToolInvokeRequest(
            ToolReference toolReference,
            ToolManager.ToolArguments toolArguments) {

        return ToolInvokeRequest.newBuilder()
            .setUri(toolReference.getUri())
            .setBody(extractBody(toolReference, toolArguments))
            .putAllArguments(toolArguments.asMap())
            .putAllHeaders(extractHeaders(toolReference, toolArguments))
            .setConfigurationURI(
                Objects.requireNonNullElse(
                    toolReference.getConfigurationURI(), ""))
            .setSecretsURI(
                Objects.requireNonNullElse(
                    toolReference.getSecretsURI(), ""))
            .build();
    }

    static Map<String, String> extractHeaders(
            ToolReference toolReference,
            ToolManager.ToolArguments toolArguments) {
        // Filter properties where target == "header" and scope == "service"
        return toolReference.getProperties().stream()
            .filter(p -> "header".equals(p.getTarget())
                      && "service".equals(p.getScope()))
            .collect(Collectors.toMap(
                PropertySchema::getName,
                p -> toolArguments.get(p.getName())
            ));
    }
}
```

**Exception Categorization:**

| Exception Type | Category |
|----------------|----------|
| `StatusRuntimeException` | SERVICE_UNAVAILABLE |
| `ServiceUnavailableException` | SERVICE_UNAVAILABLE |
| `NullPointerException` | TOOL_DEFINITION_ERROR |
| `IllegalArgumentException` | INVALID_ARGUMENTS |
| Other | UNKNOWN |

### ResourceAcquirerBridge

**Package:** `ai.wanaku.backend.bridge`

Proxy for resource acquisition services.

```java
public class ResourceAcquirerBridge implements ResourceBridge {
    private static final String SERVICE_TYPE_RESOURCE_PROVIDER = "resource-provider";

    private final ServiceResolver serviceResolver;
    private final WanakuBridgeTransport transport;

    @Override
    public List<ResourceContents> eval(
            ResourceManager.ResourceArguments arguments,
            ResourceReference mcpResource) {

        ServiceTarget service = serviceResolver.resolve(
            mcpResource.getType(), SERVICE_TYPE_RESOURCE_PROVIDER);

        ResourceRequest request = buildResourceRequest(mcpResource);
        ResourceReply reply = transport.acquireResource(request, service);

        return processReply(reply, arguments, mcpResource);
    }

    @Override
    public ProvisioningReference provision(ResourcePayload payload) {
        ResourceReference ref = payload.getResourceReference();
        ServiceTarget service = serviceResolver.resolve(
            ref.getType(), SERVICE_TYPE_RESOURCE_PROVIDER);
        return transport.provision(
            ref.getName(),
            payload.getConfigData(),
            payload.getSecretsData(),
            service
        );
    }

    private ResourceRequest buildResourceRequest(ResourceReference mcpResource) {
        return ResourceRequest.newBuilder()
            .setLocation(mcpResource.getLocation())
            .setType(mcpResource.getType())
            .setName(mcpResource.getName())
            .setConfigurationURI(
                Objects.requireNonNullElse(
                    mcpResource.getConfigurationURI(), ""))
            .setSecretsURI(
                Objects.requireNonNullElse(
                    mcpResource.getSecretsURI(), ""))
            .build();
    }

    private List<ResourceContents> processReply(
            ResourceReply reply,
            ResourceManager.ResourceArguments arguments,
            ResourceReference mcpResource) {

        if (reply.getIsError()) {
            return List.of(new TextResourceContents(
                mcpResource.getUri(),
                mcpResource.getMimeType(),
                reply.getContent(0)
            ));
        }

        return reply.getContentList().stream()
            .map(content -> new TextResourceContents(
                mcpResource.getUri(),
                mcpResource.getMimeType(),
                content
            ))
            .toList();
    }
}
```

### CodeExecutionBridge

**Package:** `ai.wanaku.backend.bridge`

Proxy for code execution services with streaming support.

```java
public class CodeExecutionBridge implements CodeExecutorBridge {
    private static final String SERVICE_TYPE_CODE_EXECUTION = "code-execution-engine";

    private final ServiceResolver serviceResolver;
    private final WanakuBridgeTransport transport;
    private final MutinyEmitter<ToolCallEvent> toolCallEventEmitter;

    @Override
    public Iterator<CodeExecutionReply> executeCode(
            String engineType,
            String language,
            CodeExecutionRequest request) {

        ServiceTarget service = resolveService(engineType, language);

        ai.wanaku.core.exchange.CodeExecutionRequest grpcRequest =
            buildGrpcRequest(engineType, language, request);

        ToolCallEvent startedEvent = emitStartedEvent(engineType, language, request);
        Instant startTime = Instant.now();

        try {
            Iterator<CodeExecutionReply> iterator =
                transport.executeCode(grpcRequest, service);

            return new CloseableCodeExecutionIterator(
                iterator, startedEvent, startTime, this);

        } catch (Exception e) {
            emitCompletionEvent(startedEvent, startTime, true, e.getMessage());
            throw e;
        }
    }

    private ServiceTarget resolveService(String engineType, String language) {
        ServiceTarget service = serviceResolver.resolveCodeExecution(
            SERVICE_TYPE_CODE_EXECUTION, engineType, language);

        if (service == null) {
            throw new ServiceNotFoundException(
                SERVICE_TYPE_CODE_EXECUTION, engineType + "/" + language);
        }
        return service;
    }

    private ai.wanaku.core.exchange.CodeExecutionRequest buildGrpcRequest(
            String engineType,
            String language,
            CodeExecutionRequest request) {

        String uri = String.format("code-execution-engine://%s/%s",
            engineType, language);

        String decodedCode = decodeBase64Code(request.getCode());

        // Convert List<String> arguments to Map with indexed keys
        Map<String, String> argMap = new HashMap<>();
        List<String> args = request.getArguments();
        for (int i = 0; i < args.size(); i++) {
            argMap.put("arg" + i, args.get(i));
        }

        return ai.wanaku.core.exchange.CodeExecutionRequest.newBuilder()
            .setUri(uri)
            .setCode(decodedCode)
            .putAllArguments(argMap)
            .putAllEnvironment(request.getEnvironment())
            .setTimeout(request.getTimeout())
            .build();
    }

    private String decodeBase64Code(String base64Code) {
        if (base64Code == null || base64Code.isEmpty()) {
            return "";
        }
        try {
            return new String(Base64.getDecoder().decode(base64Code));
        } catch (IllegalArgumentException e) {
            return base64Code;  // Return raw if not valid base64
        }
    }
}
```

### CloseableCodeExecutionIterator

Wraps streaming iterator to ensure terminal events are emitted.

```java
public static class CloseableCodeExecutionIterator
        implements Iterator<CodeExecutionReply>, Closeable {

    private final Iterator<CodeExecutionReply> delegate;
    private final ToolCallEvent startedEvent;
    private final Instant startTime;
    private final CodeExecutionBridge bridge;
    private boolean completed = false;
    private boolean hasError = false;
    private String lastErrorMessage = null;

    @Override
    public boolean hasNext() {
        try {
            boolean hasMore = delegate.hasNext();
            if (!hasMore && !completed) {
                bridge.emitCompletionEvent(
                    startedEvent, startTime, hasError, lastErrorMessage);
                completed = true;
            }
            return hasMore;
        } catch (Exception e) {
            hasError = true;
            lastErrorMessage = e.getMessage();
            if (!completed) {
                bridge.emitCompletionEvent(
                    startedEvent, startTime, true, e.getMessage());
                completed = true;
            }
            throw e;
        }
    }

    @Override
    public CodeExecutionReply next() {
        try {
            CodeExecutionReply reply = delegate.next();
            if (reply.getIsError()) {
                hasError = true;
                lastErrorMessage = reply.getContent(0);
            }
            return reply;
        } catch (Exception e) {
            hasError = true;
            lastErrorMessage = e.getMessage();
            if (!completed) {
                bridge.emitCompletionEvent(
                    startedEvent, startTime, true, e.getMessage());
                completed = true;
            }
            throw e;
        }
    }

    @Override
    public void close() {
        if (!completed) {
            bridge.emitCompletionEvent(
                startedEvent, startTime, hasError, lastErrorMessage);
            completed = true;
        }
    }
}
```

---

## gRPC Protocol Definitions

### Provisioner Service

**File:** `provision.proto`

```protobuf
service Provisioner {
  rpc Provision (ProvisionRequest) returns (ProvisionReply) {}
}

message Configuration {
  PayloadType type = 1;   // REFERENCE or BUILTIN
  string name = 2;
  string payload = 3;
}

message Secret {
  PayloadType type = 1;
  string name = 2;
  string payload = 3;
}

message ProvisionRequest {
  string uri = 1;
  Configuration configuration = 2;
  Secret secret = 3;
}

message ProvisionReply {
  string configurationUri = 1;
  string secretUri = 2;
  map<string, PropertySchema> properties = 3;
}
```

### ToolInvoker Service

**File:** `toolrequest.proto`

```protobuf
service ToolInvoker {
  rpc InvokeTool (ToolInvokeRequest) returns (ToolInvokeReply) {}
}

message ToolInvokeRequest {
  string uri = 1;
  string body = 2;
  map<string, string> arguments = 3;
  string configurationURI = 4;
  string secretsURI = 5;
  map<string, string> headers = 6;
}

message ToolInvokeReply {
  bool isError = 1;
  repeated string content = 2;
}
```

### ResourceAcquirer Service

**File:** `resourcerequest.proto`

```protobuf
service ResourceAcquirer {
  rpc ResourceAcquire (ResourceRequest) returns (ResourceReply) {}
}

message ResourceRequest {
  string location = 1;
  string type = 2;
  string name = 3;
  map<string, string> params = 4;
  string configurationURI = 5;
  string secretsURI = 6;
}

message ResourceReply {
  bool isError = 1;
  repeated string content = 2;
}
```

### CodeExecutor Service

**File:** `codeexecution.proto`

```protobuf
service CodeExecutor {
  rpc ExecuteCode (CodeExecutionRequest) returns (stream CodeExecutionReply) {}
}

message CodeExecutionRequest {
  string uri = 1;
  string body = 2;
  string code = 3;
  map<string, string> arguments = 4;
  string configurationURI = 5;
  string secretsURI = 6;
  int64 timeout = 7;
  map<string, string> environment = 8;
}

message CodeExecutionReply {
  bool isError = 1;
  repeated string content = 2;
  OutputType outputType = 3;
  ExecutionStatus status = 4;
  int32 exitCode = 5;
  int64 timestamp = 6;
}

enum OutputType {
  STDOUT = 0;
  STDERR = 1;
  STATUS = 2;
  COMPLETION = 3;
}

enum ExecutionStatus {
  PENDING = 0;
  RUNNING = 1;
  COMPLETED = 2;
  FAILED = 3;
  CANCELLED = 4;
  TIMEOUT = 5;
}
```

---

## Request/Response Flows

### Tool Invocation Flow

```
┌─────────────────────────────────────────────────────────────────┐
│ 1. Client Request                                               │
└────────────────────────────┬────────────────────────────────────┘
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│ 2. InvokerBridge.getExecutor()                                  │
│    → Returns InvokerToolExecutor                                │
└────────────────────────────┬────────────────────────────────────┘
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│ 3. InvokerToolExecutor.execute(ToolArguments, ToolReference)    │
└────────────────────────────┬────────────────────────────────────┘
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│ 4. ServiceResolver.resolve(type, "tool-invoker")                │
│    └─ Fallback: resolve(type, "code-execution-engine")          │
└────────────────────────────┬────────────────────────────────────┘
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│ 5. buildToolInvokeRequest()                                     │
│    ├─ extractHeaders(): target="header", scope="service"        │
│    ├─ extractBody(): BODY argument if defined                   │
│    └─ Convert arguments to Map<String, String>                  │
└────────────────────────────┬────────────────────────────────────┘
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│ 6. Emit STARTED event (redacted sensitive data)                 │
└────────────────────────────┬────────────────────────────────────┘
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│ 7. GrpcTransport.invokeTool(request, service)                   │
│    ├─ GrpcChannelManager.createChannel(ServiceTarget)           │
│    ├─ ToolInvokerGrpc.newBlockingStub(channel)                  │
│    └─ stub.invokeTool(request)                                  │
└────────────────────────────┬────────────────────────────────────┘
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│ 8. Process ToolInvokeReply                                      │
│    ├─ isError=true  → Emit FAILED event                         │
│    └─ isError=false → Emit COMPLETED event                      │
└────────────────────────────┬────────────────────────────────────┘
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│ 9. Return ToolResponse                                          │
└─────────────────────────────────────────────────────────────────┘
```

### Resource Acquisition Flow

```
┌─────────────────────────────────────────────────────────────────┐
│ 1. ResourceAcquirerBridge.eval(ResourceArguments, ResourceRef)  │
└────────────────────────────┬────────────────────────────────────┘
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│ 2. ServiceResolver.resolve(type, "resource-provider")           │
└────────────────────────────┬────────────────────────────────────┘
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│ 3. buildResourceRequest()                                       │
│    ├─ location: from ResourceReference                          │
│    ├─ type: from ResourceReference                              │
│    ├─ configurationURI: from ResourceReference (default "")     │
│    └─ secretsURI: from ResourceReference (default "")           │
└────────────────────────────┬────────────────────────────────────┘
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│ 4. GrpcTransport.acquireResource(request, service)              │
│    ├─ GrpcChannelManager.createChannel(ServiceTarget)           │
│    ├─ ResourceAcquirerGrpc.newBlockingStub(channel)             │
│    └─ stub.resourceAcquire(request)                             │
└────────────────────────────┬────────────────────────────────────┘
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│ 5. processReply()                                               │
│    ├─ isError=true  → TextResourceContents with error message   │
│    └─ isError=false → TextResourceContents for each content     │
└────────────────────────────┬────────────────────────────────────┘
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│ 6. Return List<ResourceContents>                                │
└─────────────────────────────────────────────────────────────────┘
```

### Code Execution Flow (Streaming)

```
┌─────────────────────────────────────────────────────────────────┐
│ 1. CodeExecutionBridge.executeCode(engineType, language, req)   │
└────────────────────────────┬────────────────────────────────────┘
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│ 2. ServiceResolver.resolveCodeExecution(                        │
│       "code-execution-engine", engineType, language)            │
└────────────────────────────┬────────────────────────────────────┘
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│ 3. buildGrpcRequest()                                           │
│    ├─ uri: "code-execution-engine://{engineType}/{language}"    │
│    ├─ code: Base64 decode from request                          │
│    ├─ arguments: List → Map (arg0, arg1, ...)                   │
│    └─ environment: from request                                 │
└────────────────────────────┬────────────────────────────────────┘
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│ 4. Emit STARTED event                                           │
│    ├─ Redact code: "[CODE]"                                     │
│    └─ Redact arguments: emit count only                         │
└────────────────────────────┬────────────────────────────────────┘
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│ 5. GrpcTransport.executeCode(request, service)                  │
│    ├─ GrpcChannelManager.createChannel(ServiceTarget)           │
│    ├─ CodeExecutorGrpc.newBlockingStub(channel)                 │
│    └─ stub.executeCode(request) → Iterator                      │
└────────────────────────────┬────────────────────────────────────┘
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│ 6. Wrap in CloseableCodeExecutionIterator                       │
│    ├─ Tracks completion state                                   │
│    └─ Ensures terminal event on close/completion                │
└────────────────────────────┬────────────────────────────────────┘
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│ 7. Stream responses to client                                   │
│    └─ Emit COMPLETED/FAILED when iterator exhausted or closed   │
└────────────────────────────┬────────────────────────────────────┘
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│ 8. Return Iterator<CodeExecutionReply>                          │
└─────────────────────────────────────────────────────────────────┘
```

### Provisioning Flow

```
┌─────────────────────────────────────────────────────────────────┐
│ 1. InvokerBridge.provision(ToolPayload) or                      │
│    ResourceAcquirerBridge.provision(ResourcePayload)            │
└────────────────────────────┬────────────────────────────────────┘
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│ 2. ServiceResolver.resolve(type, serviceType)                   │
└────────────────────────────┬────────────────────────────────────┘
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│ 3. GrpcTransport.provision(name, configData, secretsData, svc)  │
│    ├─ Build Configuration protobuf                              │
│    └─ Build Secret protobuf                                     │
└────────────────────────────┬────────────────────────────────────┘
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│ 4. ProvisioningService.provision(cfg, secret, channel, service) │
│    ├─ Build ProvisionRequest                                    │
│    ├─ ProvisionerGrpc.ProvisionerBlockingStub                   │
│    └─ stub.provision(request) → ProvisionReply                  │
└────────────────────────────┬────────────────────────────────────┘
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│ 5. Return ProvisioningReference(configUri, secretUri, props)    │
└─────────────────────────────────────────────────────────────────┘
```

---

## Design Patterns

### Transport Abstraction Pattern

```java
// Interface defines protocol-independent contract
interface WanakuBridgeTransport {
    ToolInvokeReply invokeTool(ToolInvokeRequest request, ServiceTarget service);
}

// gRPC implementation
class GrpcTransport implements WanakuBridgeTransport {
    public ToolInvokeReply invokeTool(ToolInvokeRequest request, ServiceTarget service) {
        // gRPC-specific logic
    }
}

// HTTP implementation (future)
class HttpTransport implements WanakuBridgeTransport {
    public ToolInvokeReply invokeTool(ToolInvokeRequest request, ServiceTarget service) {
        // HTTP-specific logic
    }
}
```

### Composition Over Inheritance

```java
// InvokerBridge delegates to executor and transport
class InvokerBridge implements ToolsBridge {
    private final ServiceResolver serviceResolver;      // Service discovery
    private final WanakuBridgeTransport transport;     // Protocol handling
    private final ToolExecutor executor;               // Execution logic
}

// Each component has single responsibility
```

### Service Locator Pattern

```java
// ServiceResolver discovers services dynamically
ServiceTarget service = serviceResolver.resolve("my-tool", "tool-invoker");

// Bridges don't need hardcoded addresses
```

### Iterator Wrapper Pattern

```java
// Ensure cleanup even if iteration abandoned
try (CloseableCodeExecutionIterator iter = bridge.executeCode(...)) {
    while (iter.hasNext()) {
        CodeExecutionReply reply = iter.next();
        // Process reply
    }
}  // Terminal event emitted on close
```

---

## Security Features

| Feature | Implementation |
|---------|----------------|
| Argument Redaction | Events omit actual argument values |
| Code Redaction | Code replaced with "[CODE]" in events |
| Error Sanitization | Safe error messages in responses |
| Plaintext (dev) | Default configuration for development |
| TLS Ready | Channel manager designed for future SSL/TLS |

---

## File Locations

| Component | Path |
|-----------|------|
| Bridge.java | `wanaku-router/wanaku-router-backend/.../bridge/` |
| WanakuBridgeTransport.java | `wanaku-router/wanaku-router-backend/.../bridge/` |
| GrpcTransport.java | `wanaku-router/wanaku-router-backend/.../bridge/transports/grpc/` |
| GrpcChannelManager.java | `wanaku-router/wanaku-router-backend/.../bridge/transports/grpc/` |
| InvokerBridge.java | `wanaku-router/wanaku-router-backend/.../bridge/` |
| InvokerToolExecutor.java | `wanaku-router/wanaku-router-backend/.../bridge/` |
| ResourceAcquirerBridge.java | `wanaku-router/wanaku-router-backend/.../bridge/` |
| CodeExecutionBridge.java | `wanaku-router/wanaku-router-backend/.../bridge/` |
| ProvisioningService.java | `wanaku-router/wanaku-router-backend/.../bridge/` |
| ToolsBridge.java | `wanaku-router/wanaku-router-backend/.../bridge/` |
| ResourceBridge.java | `wanaku-router/wanaku-router-backend/.../bridge/` |
| CodeExecutorBridge.java | `wanaku-router/wanaku-router-backend/.../bridge/` |
| provision.proto | `core/core-exchange/src/main/proto/` |
| toolrequest.proto | `core/core-exchange/src/main/proto/` |
| resourcerequest.proto | `core/core-exchange/src/main/proto/` |
| codeexecution.proto | `core/core-exchange/src/main/proto/` |