### Install CLI Proxy SDK

Source: https://github.com/router-for-me/cliproxyapi/blob/main/docs/sdk-usage.md

Use `go get` to install the SDK. Note the `/v6` module path.

```bash
go get github.com/router-for-me/CLIProxyAPI/v6/sdk/cliproxy
```

--------------------------------

### Build All Plugin Examples

Source: https://github.com/router-for-me/cliproxyapi/blob/main/examples/plugin/simple/README.md

Command to build all plugin examples, including Go, C, and Rust variants.

```bash
make -C examples/plugin build
```

--------------------------------

### Build All Plugin Examples

Source: https://github.com/router-for-me/cliproxyapi/blob/main/examples/plugin/README.md

Builds all standard dynamic library plugin examples. Artifacts are generated in the 'examples/plugin/bin' directory.

```bash
make -C examples/plugin list
make -C examples/plugin build
```

--------------------------------

### Writing Custom Providers

Source: https://github.com/router-for-me/cliproxyapi/blob/main/docs/sdk-access.md

Guide on implementing and registering your own access providers.

```APIDOC
## Writing Custom Providers

### Description
Implement the `sdkaccess.Provider` interface to create custom authentication providers.

### Provider Interface
```go
type customProvider struct{}

func (p *customProvider) Identifier() string { return "my-provider" }

func (p *customProvider) Authenticate(ctx context.Context, r *http.Request) (*sdkaccess.Result, *sdkaccess.AuthError) {
    // Implementation details here...
    return nil, sdkaccess.NewNotHandledError()
}
```

### Registration
Call `sdkaccess.RegisterProvider` within an `init` function to make your custom provider available.

```go
func init() {
    sdkaccess.RegisterProvider("custom", &customProvider{})
}
```

### Provider Implementation Details
- **`Identifier()`**: Returns a unique string identifier for the provider.
- **`Authenticate(ctx, r)`**: Handles the authentication logic. It should return:
    - `(*sdkaccess.Result, nil)` on success.
    - `(nil, sdkaccess.NewNotHandledError())` if the provider cannot handle the request.
    - `(nil, sdkaccess.NewInvalidCredentialError())` if credentials are provided but invalid.
    - `(nil, otherAuthError)` for other errors.

### Metadata and Auditing
Populate `Result.Metadata` with provider-specific context (e.g., `map[string]string{"source": "x-custom"}`) to enrich logs and downstream auditing.
```

--------------------------------

### Example Request Header

Source: https://github.com/router-for-me/cliproxyapi/blob/main/examples/plugin/frontend-auth-exclusive/README.md

Requests must include the 'X-Example-Frontend-Auth: exclusive' header to be authenticated by this provider.

```http
X-Example-Frontend-Auth: exclusive
```

--------------------------------

### Clean Plugin Build Artifacts

Source: https://github.com/router-for-me/cliproxyapi/blob/main/examples/plugin/simple/README.md

Shell command to clean up build artifacts for plugins in the examples directory.

```bash
make -C examples/plugin clean
```

--------------------------------

### Build JS Handler Plugin with Custom Output Directory

Source: https://github.com/router-for-me/cliproxyapi/blob/main/examples/plugin/jshandler/README.md

Override the default target operating system and architecture, and specify a custom build directory for the JS Handler plugin. This example targets macOS ARM64.

```bash
make build GOOS=darwin GOARCH=arm64 BUILD_DIR=/path/to/plugins/darwin/arm64
```

--------------------------------

### Register Executor with Core Manager

Source: https://github.com/router-for-me/cliproxyapi/blob/main/docs/sdk-advanced.md

Register your custom executor with the core manager before starting the service. This ensures that requests intended for your provider are routed to your custom executor.

```go
core := coreauth.NewManager(coreauth.NewFileStore(cfg.AuthDir), nil, nil)
core.RegisterExecutor(myprov.Executor{})
svc, _ := cliproxy.NewBuilder().WithConfig(cfg).WithConfigPath(cfgPath).WithCoreAuthManager(core).Build()
```

--------------------------------

### Initializing the Access Manager

Source: https://github.com/router-for-me/cliproxyapi/blob/main/docs/sdk-access.md

Construct a manager and populate it with globally registered providers.

```go
manager := sdkaccess.NewManager()
manager.SetProviders(sdkaccess.RegisteredProviders())
```

--------------------------------

### Import CLI Proxy SDK Packages

Source: https://github.com/router-for-me/cliproxyapi/blob/main/docs/sdk-usage.md

Import necessary packages for using the SDK. Ensure you use the `/v6` module path.

```go
import (
    "context"
    "errors"
    "time"

    "github.com/router-for-me/CLIProxyAPI/v6/internal/config"
    "github.com/router-for-me/CLIProxyAPI/v6/sdk/cliproxy"
)
```

--------------------------------

### Build Server with Test Output

Source: https://github.com/router-for-me/cliproxyapi/blob/main/examples/plugin/simple/README.md

Go command to build the server executable and remove a previous test output file.

```bash
go build -o test-output ./cmd/server && rm test-output
```

--------------------------------

### Initialize CLIProxy Service with Access Manager

Source: https://github.com/router-for-me/cliproxyapi/blob/main/docs/sdk-access.md

Configures a new service instance using a builder pattern and a shared access manager.

```go
coreCfg, _ := config.LoadConfig("config.yaml")
accessManager := sdkaccess.NewManager()

svc, _ := cliproxy.NewBuilder().
  WithConfig(coreCfg).
  WithConfigPath("config.yaml").
  WithRequestAccessManager(accessManager).
  Build()
```

--------------------------------

### Development and Build Commands

Source: https://github.com/router-for-me/cliproxyapi/blob/main/AGENTS.md

Standard commands for formatting, building, running, and testing the CLIProxyAPI server.

```bash
gofmt -w . # Format (required after Go changes)
go build -o cli-proxy-api ./cmd/server # Build
go run ./cmd/server # Run dev server
go test ./... # Run all tests
go test -v -run TestName ./path/to/pkg # Run single test
go build -o test-output ./cmd/server && rm test-output # Verify compile (REQUIRED after changes)
```

--------------------------------

### Minimal CLI Proxy Service Embedding

Source: https://github.com/router-for-me/cliproxyapi/blob/main/docs/sdk-usage.md

Load configuration and build a minimal service instance. Cancel the context to stop the service gracefully.

```go
cfg, err := config.LoadConfig("config.yaml")
if err != nil { panic(err) }

svc, err := cliproxy.NewBuilder().
    WithConfig(cfg).
    WithConfigPath("config.yaml"). // absolute or working-dir relative
    Build()
if err != nil { panic(err) }

ctx, cancel := context.WithCancel(context.Background())
deferr cancel()

if err := svc.Run(ctx); err != nil && !errors.Is(err, context.Canceled) {
    panic(err)
}
```

--------------------------------

### Plugin Initialization Entry Point (C)

Source: https://github.com/router-for-me/cliproxyapi/blob/main/examples/plugin/simple/README.md

The required C function that the host calls to initialize the plugin. It receives host API pointers and returns plugin API pointers.

```c
int cliproxy_plugin_init(const cliproxy_host_api* host, cliproxy_plugin_api* plugin);
```

--------------------------------

### Implementing a Custom Provider

Source: https://github.com/router-for-me/cliproxyapi/blob/main/docs/sdk-access.md

Create a custom authentication provider by implementing the Identifier and Authenticate methods, then registering it in an init block.

```go
type customProvider struct{}

func (p *customProvider) Identifier() string { return "my-provider" }

func (p *customProvider) Authenticate(ctx context.Context, r *http.Request) (*sdkaccess.Result, *sdkaccess.AuthError) {
    token := r.Header.Get("X-Custom")
    if token == "" {
        return nil, sdkaccess.NewNotHandledError()
    }
    if token != "expected" {
        return nil, sdkaccess.NewInvalidCredentialError()
    }
    return &sdkaccess.Result{
        Provider:  p.Identifier(),
        Principal: "service-user",
        Metadata:  map[string]string{"source": "x-custom"},
    }, nil
}

func init() {
    sdkaccess.RegisterProvider("custom", &customProvider{})
}
```

--------------------------------

### Importing the Access SDK

Source: https://github.com/router-for-me/cliproxyapi/blob/main/docs/sdk-access.md

Include the access package in your Go project.

```go
import (
    sdkaccess "github.com/router-for-me/CLIProxyAPI/v6/sdk/access"
)
```

--------------------------------

### Configure CLI Proxy Server Options

Source: https://github.com/router-for-me/cliproxyapi/blob/main/docs/sdk-usage.md

Customize the embedded server with middleware, engine configurations, custom routes, and request loggers using `WithServerOptions`.

```go
svc, _ := cliproxy.NewBuilder().
  WithConfig(cfg).
  WithConfigPath("config.yaml").
  WithServerOptions(
    // Add global middleware
    cliproxy.WithMiddleware(func(c *gin.Context) { c.Header("X-Embed", "1"); c.Next() }),
    // Tweak gin engine early (CORS, trusted proxies, etc.)
    cliproxy.WithEngineConfigurator(func(e *gin.Engine) { e.ForwardedByClientIP = true }),
    // Add your own routes after defaults
    cliproxy.WithRouterConfigurator(func(e *gin.Engine, _ *handlers.BaseAPIHandler, _ *config.Config) {
      e.GET("/healthz", func(c *gin.Context) { c.String(200, "ok") })
    }),
    // Override request log writer/dir
    cliproxy.WithRequestLoggerFactory(func(cfg *config.Config, cfgPath string) logging.RequestLogger {
      return logging.NewFileRequestLogger(true, "logs", filepath.Dir(cfgPath))
    }),
  ).
  Build()
```

--------------------------------

### Configure Service Hooks

Source: https://github.com/router-for-me/cliproxyapi/blob/main/docs/sdk-usage.md

Observe the service lifecycle by providing custom functions for `OnBeforeStart` and `OnAfterStart` events.

```go
hooks := cliproxy.Hooks{
  OnBeforeStart: func(cfg *config.Config) { log.Infof("starting on :%d", cfg.Port) },
  OnAfterStart:  func(s *cliproxy.Service) { log.Info("ready") },
}
svc, _ := cliproxy.NewBuilder().WithConfig(cfg).WithConfigPath("config.yaml").WithHooks(hooks).Build()
```

--------------------------------

### Manual Go Build on macOS

Source: https://github.com/router-for-me/cliproxyapi/blob/main/examples/plugin/simple/README.md

Builds a shared dynamic library for the Go plugin on macOS. It creates necessary directories and compiles the Go code.

```bash
mkdir -p plugins/darwin/$(go env GOARCH)
go build -buildmode=c-shared -o plugins/darwin/$(go env GOARCH)/simple-go.dylib ./examples/plugin/simple/go
rm -f plugins/darwin/$(go env GOARCH)/simple-go.h
```

--------------------------------

### Importing the SDK Access Package

Source: https://github.com/router-for-me/cliproxyapi/blob/main/docs/sdk-access.md

How to import the SDK Access package into your Go project.

```APIDOC
## Importing the SDK Access Package

### Description
Import the `sdk/access` package to utilize its functionalities for request authentication.

### Code Example
```go
import (
    sdkaccess "github.com/router-for-me/CLIProxyAPI/v6/sdk/access"
)
```

### Installation
Add the module with `go get github.com/router-for-me/CLIProxyAPI/v6/sdk/access`.
```

--------------------------------

### Implement Custom Token Client Provider

Source: https://github.com/router-for-me/cliproxyapi/blob/main/docs/sdk-usage.md

Replace default token loaders by implementing the `cliproxy.TokenClientProvider` interface for custom credential storage.

```go
type memoryTokenProvider struct{}
func (p *memoryTokenProvider) Load(ctx context.Context, cfg *config.Config) (*cliproxy.TokenClientResult, error) {
    // Populate from memory/remote store and return counts
    return &cliproxy.TokenClientResult{}, nil
}

svc, _ := cliproxy.NewBuilder().
  WithConfig(cfg).
  WithConfigPath("config.yaml").
  WithTokenClientProvider(&memoryTokenProvider{}).
  WithAPIKeyClientProvider(cliproxy.NewAPIKeyClientProvider()).
  Build()
```

--------------------------------

### Build Shared Library

Source: https://github.com/router-for-me/cliproxyapi/blob/main/examples/plugin/frontend-auth-exclusive/README.md

Builds the Go code as a C-shared dynamic library for use as a plugin. Ensure the output path is accessible.

```bash
cd examples/plugin/frontend-auth-exclusive/go
go build -buildmode=c-shared -o /tmp/cliproxy-frontend-auth-exclusive.dylib .
```

--------------------------------

### Count Plugin Binaries

Source: https://github.com/router-for-me/cliproxyapi/blob/main/examples/plugin/simple/README.md

Shell command to count the number of plugin binary files in the examples/plugin/bin directory.

```bash
find examples/plugin/bin -maxdepth 1 -type f | wc -l
```

--------------------------------

### Registering External Providers

Source: https://github.com/router-for-me/cliproxyapi/blob/main/docs/sdk-access.md

Import external modules using the blank identifier to trigger provider registration via init functions.

```go
import (
    _ "github.com/acme/xplatform/sdk/access/providers/partner" // registers partner-token
    sdkaccess "github.com/router-for-me/CLIProxyAPI/v6/sdk/access"
)
```

--------------------------------

### Loading Providers from External Go Modules

Source: https://github.com/router-for-me/cliproxyapi/blob/main/docs/sdk-access.md

How to integrate providers from other Go modules.

```APIDOC
## Loading Providers from External Go Modules

### Description
To use a provider from another Go module, import it for its registration side effect.

### Example
```go
import (
    _ "github.com/acme/xplatform/sdk/access/providers/partner" // registers partner-token
    sdkaccess "github.com/router-for-me/CLIProxyAPI/v6/sdk/access"
)
```

### Explanation
The blank identifier import (`_`) ensures that the `init` function of the imported package runs, which in turn calls `sdkaccess.RegisterProvider` before `RegisteredProviders()` or `cliproxy.NewBuilder().Build()` are invoked.
```

--------------------------------

### Build Scheduler Plugin

Source: https://github.com/router-for-me/cliproxyapi/blob/main/examples/plugin/scheduler/README.md

Build the scheduler plugin as a C-shared library. This command compiles the Go code and outputs a shared object file and header file.

```bash
cd go
go build -buildmode=c-shared -o /tmp/cliproxy-scheduler-plugin.so .
rm -f /tmp/cliproxy-scheduler-plugin.so /tmp/cliproxy-scheduler-plugin.h
```

--------------------------------

### Manual C Build on macOS

Source: https://github.com/router-for-me/cliproxyapi/blob/main/examples/plugin/simple/README.md

Builds the C plugin using CMake on macOS. It configures the build and then compiles the library.

```bash
mkdir -p plugins/darwin/$(go env GOARCH)
cmake -S examples/plugin/simple/c -B /tmp/cliproxy-simple-c-build -DCMAKE_LIBRARY_OUTPUT_DIRECTORY=$PWD/plugins/darwin/$(go env GOARCH)
cmake --build /tmp/cliproxy-simple-c-build
```

--------------------------------

### Enable Dynamic Plugins Configuration

Source: https://github.com/router-for-me/cliproxyapi/blob/main/examples/plugin/simple/README.md

YAML configuration to enable and configure dynamic plugins, including directory and specific plugin settings.

```yaml
plugins:
  enabled: true
  dir: "plugins"
  configs:
    simple-go:
      enabled: true
      priority: 1
      config1: true
      config2: "string"
      config3: 3
      mode: "safe"
```

--------------------------------

### Register Models with Global Registry

Source: https://github.com/router-for-me/cliproxyapi/blob/main/docs/sdk-advanced.md

Expose your provider's models under `/v1/models` by registering them in the global model registry. This is typically done during startup or upon auth registration hooks for custom providers.

```go
models := []*cliproxy.ModelInfo{
  { ID: "myprov-pro-1", Object: "model", Type: "myprov", DisplayName: "MyProv Pro 1" },
}
cliproxy.GlobalModelRegistry().RegisterClient(authID, "myprov", models)
```

--------------------------------

### Plugin Discovery Paths

Source: https://github.com/router-for-me/cliproxyapi/blob/main/examples/plugin/simple/README.md

Specifies the directory structure the host searches for dynamic plugins.

```text
plugins/<GOOS>/<GOARCH>-<variant>
plugins/<GOOS>/<GOARCH>
plugins
```

--------------------------------

### CMakeLists.txt for C Protocol Format Plugin

Source: https://github.com/router-for-me/cliproxyapi/blob/main/examples/plugin/protocol-format/c/CMakeLists.txt

Configures the build for the C protocol format plugin using CMake. It sets the minimum CMake version, defines the project, adds a shared library from the source file, and sets specific target properties for the output name and prefix.

```cmake
cmake_minimum_required(VERSION 3.16)
project(cliproxy_protocol_format_c C)

add_library(cliproxy_protocol_format_c SHARED src/plugin.c)
set_target_properties(cliproxy_protocol_format_c PROPERTIES
    OUTPUT_NAME "protocol-format-c"
    PREFIX ""
)
```

--------------------------------

### Build C Frontend Authentication Plugin

Source: https://github.com/router-for-me/cliproxyapi/blob/main/examples/plugin/frontend-auth/c/CMakeLists.txt

Configures the build for the C frontend authentication plugin using CMake. It defines the minimum required CMake version, names the project, adds a shared library from the source file, and sets output properties.

```cmake
cmake_minimum_required(VERSION 3.16)
project(cliproxy_frontend_auth_c C)

add_library(cliproxy_frontend_auth_c SHARED src/plugin.c)
set_target_properties(cliproxy_frontend_auth_c PROPERTIES
    OUTPUT_NAME "frontend-auth-c"
    PREFIX ""
)
```

--------------------------------

### CMakeLists.txt for Simple C Plugin

Source: https://github.com/router-for-me/cliproxyapi/blob/main/examples/plugin/simple/c/CMakeLists.txt

Defines the build configuration for a shared C library plugin named 'simple-c'.

```cmake
cmake_minimum_required(VERSION 3.16)
project(cliproxy_simple_c C)

add_library(cliproxy_simple_c SHARED src/plugin.c)
set_target_properties(cliproxy_simple_c PROPERTIES
    OUTPUT_NAME "simple-c"
    PREFIX ""
)
```

--------------------------------

### Build JS Handler Plugin for Windows

Source: https://github.com/router-for-me/cliproxyapi/blob/main/examples/plugin/jshandler/README.md

Build the JS Handler plugin for Windows. The output will be a dynamic-link library (`.dll`).

```bash
make build GOOS=windows
```

--------------------------------

### Integration with cliproxy Service

Source: https://github.com/router-for-me/cliproxyapi/blob/main/docs/sdk-access.md

Instructions for wiring the access manager into the cliproxy service builder.

```APIDOC
## Integration with cliproxy Service

### Description
Use `cliproxy.NewBuilder` to integrate the access manager. Register custom providers before calling `Build()`.

### Request Example
```go
coreCfg, _ := config.LoadConfig("config.yaml")
accessManager := sdkaccess.NewManager()

svc, _ := cliproxy.NewBuilder().
  WithConfig(coreCfg).
  WithConfigPath("config.yaml").
  WithRequestAccessManager(accessManager).
  Build()
```
```

--------------------------------

### Configuring Built-in API Keys

Source: https://github.com/router-for-me/cliproxyapi/blob/main/docs/sdk-access.md

Define valid API keys in your configuration file for the built-in provider.

```yaml
api-keys:
  - sk-test-123
  - sk-prod-456
```

--------------------------------

### Build JS Handler Plugin for Linux/FreeBSD

Source: https://github.com/router-for-me/cliproxyapi/blob/main/examples/plugin/jshandler/README.md

Build the JS Handler plugin for Linux or FreeBSD operating systems. The output will be a shared object file (`.so`).

```bash
make build
```

--------------------------------

### Manager Lifecycle

Source: https://github.com/router-for-me/cliproxyapi/blob/main/docs/sdk-access.md

Details on creating and configuring the access manager.

```APIDOC
## Manager Lifecycle

### Description
This section covers the creation and configuration of the access manager.

### Creating a New Manager
- **Method**: `NewManager()`
- **Description**: Constructs an empty manager.

### Setting Providers
- **Method**: `SetProviders(providers)`
- **Description**: Replaces the provider slice using a defensive copy.

### Retrieving Providers Snapshot
- **Method**: `Providers()`
- **Description**: Retrieves a snapshot of providers that can be iterated safely from other goroutines.

### Handling Nil or Unconfigured Managers
If the manager is `nil` or has no providers configured, `Authenticate` returns `nil, nil`, effectively disabling access control.
```

--------------------------------

### Build JS Handler Plugin for macOS

Source: https://github.com/router-for-me/cliproxyapi/blob/main/examples/plugin/jshandler/README.md

Build the JS Handler plugin for macOS. The output will be a dynamic library (`.dylib`).

```bash
make build GOOS=darwin
```

--------------------------------

### CMakeLists.txt for C Host Callback Plugin

Source: https://github.com/router-for-me/cliproxyapi/blob/main/examples/plugin/host-callback/c/CMakeLists.txt

Configures the build for a C shared library plugin that utilizes host callbacks. Sets the output name to 'host-callback-c'.

```cmake
cmake_minimum_required(VERSION 3.16)
project(cliproxy_host_callback_c C)

add_library(cliproxy_host_callback_c SHARED src/plugin.c)
set_target_properties(cliproxy_host_callback_c PROPERTIES
    OUTPUT_NAME "host-callback-c"
    PREFIX ""
)
```

--------------------------------

### CMakeLists.txt for C Management API Plugin

Source: https://github.com/router-for-me/cliproxyapi/blob/main/examples/plugin/management-api/c/CMakeLists.txt

Configures the build process for the C Management API plugin as a shared library.

```cmake
cmake_minimum_required(VERSION 3.16)
project(cliproxy_management_api_c C)

add_library(cliproxy_management_api_c SHARED src/plugin.c)
set_target_properties(cliproxy_management_api_c PROPERTIES
    OUTPUT_NAME "management-api-c"
    PREFIX ""
)
```

--------------------------------

### Manual Rust Build on macOS

Source: https://github.com/router-for-me/cliproxyapi/blob/main/examples/plugin/simple/README.md

Builds the Rust plugin using Cargo on macOS. It compiles the release version and copies the dynamic library to the plugins directory.

```bash
mkdir -p plugins/darwin/$(go env GOARCH)
cd examples/plugin/simple/rust
CARGO_TARGET_DIR=/tmp/cliproxy-simple-rust-target cargo build --release --locked
cp /tmp/cliproxy-simple-rust-target/release/libcliproxy_simple_rust.dylib ../../../../plugins/darwin/$(go env GOARCH)/simple-rust.dylib
```

--------------------------------

### Build C Shared Library Plugin

Source: https://github.com/router-for-me/cliproxyapi/blob/main/examples/plugin/cli/c/CMakeLists.txt

Configures CMake to build a C shared library named 'cli-c' from the 'src/plugin.c' file. Sets the output name and removes the default prefix.

```cmake
cmake_minimum_required(VERSION 3.16)
project(cliproxy_cli_c C)

add_library(cliproxy_cli_c SHARED src/plugin.c)
set_target_properties(cliproxy_cli_c PROPERTIES
    OUTPUT_NAME "cli-c"
    PREFIX ""
)
```

--------------------------------

### Graceful Service Shutdown

Source: https://github.com/router-for-me/cliproxyapi/blob/main/docs/sdk-usage.md

Initiate a graceful shutdown of the service by calling `Shutdown` with a context that has a timeout.

```go
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
deferr cancel()
_ = svc.Shutdown(ctx)
```

--------------------------------

### Host API Functions (C)

Source: https://github.com/router-for-me/cliproxyapi/blob/main/examples/plugin/simple/README.md

Defines the functions provided by the host to the plugin for making calls and managing memory.

```c
int call(void* host_ctx, char* method, uint8_t* request, size_t request_len, cliproxy_buffer* response);
void free_buffer(void* ptr, size_t len);
```

--------------------------------

### Provider Registry Management

Source: https://github.com/router-for-me/cliproxyapi/blob/main/docs/sdk-access.md

Explains how to register and retrieve access providers.

```APIDOC
## Provider Registry

### Description
Providers are registered globally and can be attached to a `Manager`. The registration order is preserved for the first time each provider type is seen.

### Registering a Provider
- **Method**: `RegisterProvider(type, provider)`
- **Description**: Installs a pre-initialized provider instance.

### Retrieving Providers
- **Method**: `RegisteredProviders()`
- **Description**: Returns the registered providers in their registration order.
```

--------------------------------

### CMakeLists.txt for C Response Translator Plugin

Source: https://github.com/router-for-me/cliproxyapi/blob/main/examples/plugin/response-translator/c/CMakeLists.txt

This snippet shows the CMake configuration to build a shared C library for the response translator plugin. It specifies the minimum CMake version, project name, source files, and output properties.

```cmake
cmake_minimum_required(VERSION 3.16)
project(cliproxy_response_translator_c C)

add_library(cliproxy_response_translator_c SHARED src/plugin.c)
set_target_properties(cliproxy_response_translator_c PROPERTIES
    OUTPUT_NAME "response-translator-c"
    PREFIX ""
)
```

--------------------------------

### Execute Auth Manager Requests

Source: https://github.com/router-for-me/cliproxyapi/blob/main/docs/sdk-usage.md

Programmatically execute requests using the core auth manager for both non-streaming and streaming responses.

```go
// Non‑streaming
resp, err := core.Execute(ctx, []string{"gemini"}, req, opts)

// Streaming
chunks, err := core.ExecuteStream(ctx, []string{"gemini"}, req, opts)
for ch := range chunks { /* ... */ }
```

--------------------------------

### Build C Auth Plugin Shared Library

Source: https://github.com/router-for-me/cliproxyapi/blob/main/examples/plugin/auth/c/CMakeLists.txt

Configures CMake to build a C shared library named 'auth-c' from the plugin source file.

```cmake
cmake_minimum_required(VERSION 3.16)
project(cliproxy_auth_c C)

add_library(cliproxy_auth_c SHARED src/plugin.c)
set_target_properties(cliproxy_auth_c PROPERTIES
    OUTPUT_NAME "auth-c"
    PREFIX ""
)
```

--------------------------------

### Implement a Provider Executor

Source: https://github.com/router-for-me/cliproxyapi/blob/main/docs/sdk-advanced.md

Implement the `auth.ProviderExecutor` interface to create a custom executor for your provider. This involves defining methods for identifier, request preparation, execution, streaming, and token refreshing. Use this when you need to integrate a new upstream API with the proxy.

```go
package myprov

import (
  "context"
  "net/http"

  coreauth "github.com/router-for-me/CLIProxyAPI/v6/sdk/cliproxy/auth"
  clipexec "github.com/router-for-me/CLIProxyAPI/v6/sdk/cliproxy/executor"
)

type Executor struct{}

func (Executor) Identifier() string { return "myprov" }

// Optional: mutate outbound HTTP requests with credentials
func (Executor) PrepareRequest(req *http.Request, a *coreauth.Auth) error {
  // Example: req.Header.Set("Authorization", "Bearer "+a.APIKey)
  return nil
}

func (Executor) Execute(ctx context.Context, a *coreauth.Auth, req clipexec.Request, opts clipexec.Options) (clipexec.Response, error) {
  // Build HTTP request based on req.Payload (already translated into provider format)
  // Use per‑auth transport if provided: transport := a.RoundTripper // via RoundTripperProvider
  // Perform call and return provider JSON payload
  return clipexec.Response{Payload: []byte(`{"ok":true}`)}, nil
}

func (Executor) ExecuteStream(ctx context.Context, a *coreauth.Auth, req clipexec.Request, opts clipexec.Options) (<-chan clipexec.StreamChunk, error) {
  ch := make(chan clipexec.StreamChunk, 1)
  go func() { defer close(ch); ch <- clipexec.StreamChunk{Payload: []byte("data: {\"done\":true}\n\n")} }()
  return ch, nil
}

func (Executor) Refresh(ctx context.Context, a *coreauth.Auth) (*coreauth.Auth, error) {
  // Optionally refresh tokens and return updated auth
  return a, nil
}
```

--------------------------------

### Build C Response Normalizer Plugin with CMake

Source: https://github.com/router-for-me/cliproxyapi/blob/main/examples/plugin/response-normalizer/c/CMakeLists.txt

Configures CMake to build a shared C library for the response normalizer plugin. Sets the output name and removes the default prefix.

```cmake
cmake_minimum_required(VERSION 3.16)
project(cliproxy_response_normalizer_c C)

add_library(cliproxy_response_normalizer_c SHARED src/plugin.c)
set_target_properties(cliproxy_response_normalizer_c PROPERTIES
    OUTPUT_NAME "response-normalizer-c"
    PREFIX ""
)
```

--------------------------------

### Management API Endpoints

Source: https://github.com/router-for-me/cliproxyapi/blob/main/examples/plugin/simple/README.md

Lists the native API endpoints for managing plugins, such as enabling/disabling and updating configurations.

```text
GET /v0/management/plugins
PATCH /v0/management/plugins/{pluginID}/enabled
PUT /v0/management/plugins/{pluginID}/config
PATCH /v0/management/plugins/{pluginID}/config
```

--------------------------------

### Build C Shared Library for Plugin

Source: https://github.com/router-for-me/cliproxyapi/blob/main/examples/plugin/usage/c/CMakeLists.txt

Configures CMake to build a C shared library named 'usage-c' for plugin integration. Ensure your C source files are in the 'src/' directory.

```cmake
cmake_minimum_required(VERSION 3.16)
project(cliproxy_usage_c C)

add_library(cliproxy_usage_c SHARED src/plugin.c)
set_target_properties(cliproxy_usage_c PROPERTIES
    OUTPUT_NAME "usage-c"
    PREFIX ""
)
```

--------------------------------

### Register Translators for Schema Conversion

Source: https://github.com/router-for-me/cliproxyapi/blob/main/docs/sdk-advanced.md

Register translation functions in `sdk/translator` to convert between different schema formats (e.g., OpenAI Chat to MyProv Chat). This is necessary when your provider uses a different schema than the standard formats supported by the proxy.

```go
package myprov

import (
  "context"
  sdktr "github.com/router-for-me/CLIProxyAPI/v6/sdk/translator"
)

const (
  FOpenAI = sdktr.Format("openai.chat")
  FMyProv = sdktr.Format("myprov.chat")
)

func init() {
  sdktr.Register(FOpenAI, FMyProv,
    // Request transform (model, rawJSON, stream)
    func(model string, raw []byte, stream bool) []byte { return convertOpenAIToMyProv(model, raw, stream) },
    // Response transform (stream & non‑stream)
    sdktr.ResponseTransform{
      Stream: func(ctx context.Context, model string, originalReq, translatedReq, raw []byte, param *any) []string {
        return convertStreamMyProvToOpenAI(model, originalReq, translatedReq, raw)
      },
      NonStream: func(ctx context.Context, model string, originalReq, translatedReq, raw []byte, param *any) string {
        return convertMyProvToOpenAI(model, originalReq, translatedReq, raw)
      },
    },
  )
}
```

--------------------------------

### Provide Custom Core Auth Manager

Source: https://github.com/router-for-me/cliproxyapi/blob/main/docs/sdk-usage.md

Embed a custom `auth.Manager` to customize transports or hooks. Implement `http.RoundTripper` for custom per-auth transports.

```go
core := coreauth.NewManager(coreauth.NewFileStore(cfg.AuthDir), nil, nil)
core.SetRoundTripperProvider(myRTProvider) // per‑auth *http.Transport

svc, _ := cliproxy.NewBuilder().
    WithConfig(cfg).
    WithConfigPath("config.yaml").
    WithCoreAuthManager(core).
    Build()
```

```go
type myRTProvider struct{}
func (myRTProvider) RoundTripperFor(a *coreauth.Auth) http.RoundTripper {
    if a == nil || a.ProxyURL == "" { return nil }
    u, _ := url.Parse(a.ProxyURL)
    return &http.Transport{ Proxy: http.ProxyURL(u) }
}
```

--------------------------------

### Build C Shared Library for Model Plugin

Source: https://github.com/router-for-me/cliproxyapi/blob/main/examples/plugin/model/c/CMakeLists.txt

Configures CMake to build a C shared library. This is used for the cliproxy model plugin, specifying the output name and prefix.

```cmake
cmake_minimum_required(VERSION 3.16)
project(cliproxy_model_c C)

add_library(cliproxy_model_c SHARED src/plugin.c)
set_target_properties(cliproxy_model_c PROPERTIES
    OUTPUT_NAME "model-c"
    PREFIX ""
)
```

--------------------------------

### Build C Executor Plugin Library

Source: https://github.com/router-for-me/cliproxyapi/blob/main/examples/plugin/executor/c/CMakeLists.txt

Configures CMake to build a shared C library named 'executor-c' from the 'src/plugin.c' file. This is used for the cliproxyapi executor plugin.

```cmake
cmake_minimum_required(VERSION 3.16)
project(cliproxy_executor_c C)

add_library(cliproxy_executor_c SHARED src/plugin.c)
set_target_properties(cliproxy_executor_c PROPERTIES
    OUTPUT_NAME "executor-c"
    PREFIX ""
)
```

--------------------------------

### Plugin API Functions (C)

Source: https://github.com/router-for-me/cliproxyapi/blob/main/examples/plugin/simple/README.md

Defines the functions that the plugin must export to the host for communication and management.

```c
int call(char* method, uint8_t* request, size_t request_len, cliproxy_buffer* response);
void free_buffer(void* ptr, size_t len);
void shutdown(void);
```

--------------------------------

### Authenticating Requests

Source: https://github.com/router-for-me/cliproxyapi/blob/main/docs/sdk-access.md

How to use the manager to authenticate incoming requests.

```APIDOC
## Authenticating Requests

### Description
The `Manager.Authenticate` method walks through configured providers to authenticate a request.

### Method
`manager.Authenticate(ctx, req)`

### Parameters
- **ctx** (`context.Context`): The context for the request.
- **req** (`*http.Request`): The incoming HTTP request.

### Return Values
- **result** (`*sdkaccess.Result`): Describes the provider and principal upon successful authentication.
- **authErr** (`*sdkaccess.AuthError`): An error indicating the authentication outcome.

### Error Handling
- `authErr == nil`: Authentication succeeded.
- `sdkaccess.IsAuthErrorCode(authErr, sdkaccess.AuthErrorCodeNoCredentials)`: No recognizable credentials were supplied.
- `sdkaccess.IsAuthErrorCode(authErr, sdkaccess.AuthErrorCodeInvalidCredential)`: Supplied credentials were present but rejected.
- `default`: An internal or transport failure occurred.

### Result Details
Each `Result` includes the provider identifier, the resolved principal, and optional metadata (e.g., the header that carried the credential).
```

--------------------------------

### Configure Scheduler Plugin

Source: https://github.com/router-for-me/cliproxyapi/blob/main/examples/plugin/README.md

Enables the scheduler plugin with a priority. It can optionally specify an auth_id to select a candidate, delegate to a built-in scheduler, or deny picks.

```yaml
plugins:
  configs:
    scheduler:
      enabled: true
      priority: 1
      auth_id: ""
      delegate: ""
      deny: false
```

--------------------------------

### JS Handler Plugin Configuration

Source: https://github.com/router-for-me/cliproxyapi/blob/main/examples/plugin/jshandler/README.md

Configure the JS Handler plugin to enable it, specify the directory for scripts, and list the paths to the JavaScript files to be executed. A timeout can also be set for script execution.

```yaml
plugins:
  enabled: true
  dir: "plugins-dir"
  configs:
    jshandler:
      enabled: true
      script_paths:
        - /path/to/custom_handler.js
        - ./relative_handler.js
      timeout: 1s
```

--------------------------------

### Built-in `config-api-key` Provider

Source: https://github.com/router-for-me/cliproxyapi/blob/main/docs/sdk-access.md

Details on the pre-configured API key validation provider.

```APIDOC
## Built-in `config-api-key` Provider

### Description
This provider validates API keys declared under top-level `api-keys` in the configuration.

### Credential Sources
- `Authorization: Bearer`
- `X-Goog-Api-Key`
- `X-Api-Key`
- `?key=`
- `?auth_token=`

### Metadata
- `Result.Metadata["source"]` is set to the matched source label (e.g., `authorization`, `x-goog-api-key`, `query-key`).

### Configuration Example
```yaml
api-keys:
  - sk-test-123
  - sk-prod-456
```

### Automatic Registration
In the CLI server and `sdk/cliproxy`, this provider is registered automatically based on the loaded configuration.
```

--------------------------------

### Build C Shared Library Plugin

Source: https://github.com/router-for-me/cliproxyapi/blob/main/examples/plugin/thinking/c/CMakeLists.txt

Configures CMake to build a C shared library named 'thinking-c' from 'src/plugin.c'. This is used for creating plugins that can be loaded dynamically.

```cmake
cmake_minimum_required(VERSION 3.16)
project(cliproxy_thinking_c C)

add_library(cliproxy_thinking_c SHARED src/plugin.c)
set_target_properties(cliproxy_thinking_c PROPERTIES
    OUTPUT_NAME "thinking-c"
    PREFIX ""
)
```

--------------------------------

### Authenticating Requests

Source: https://github.com/router-for-me/cliproxyapi/blob/main/docs/sdk-access.md

Process incoming requests through the configured provider chain and handle authentication results or errors.

```go
result, authErr := manager.Authenticate(ctx, req)
switch {
case authErr == nil:
    // Authentication succeeded; result describes the provider and principal.
case sdkaccess.IsAuthErrorCode(authErr, sdkaccess.AuthErrorCodeNoCredentials):
    // No recognizable credentials were supplied.
case sdkaccess.IsAuthErrorCode(authErr, sdkaccess.AuthErrorCodeInvalidCredential):
    // Supplied credentials were present but rejected.
default:
    // Internal/transport failure was returned by a provider.
}
```

--------------------------------

### Build C Request Translator Plugin

Source: https://github.com/router-for-me/cliproxyapi/blob/main/examples/plugin/request-translator/c/CMakeLists.txt

Configures CMake to build a shared C library for the request translator plugin. Sets the output name and removes the default prefix.

```cmake
cmake_minimum_required(VERSION 3.16)
project(cliproxy_request_translator_c C)

add_library(cliproxy_request_translator_c SHARED src/plugin.c)
set_target_properties(cliproxy_request_translator_c PROPERTIES
    OUTPUT_NAME "request-translator-c"
    PREFIX ""
)
```

--------------------------------

### Enable Codex Service Tier Plugin

Source: https://github.com/router-for-me/cliproxyapi/blob/main/examples/plugin/codex-service-tier/README.md

Configure the Codex Service Tier plugin by adding it to the plugin configurations. Set 'enabled' to true and 'priority' to 1. The 'fast' option, when set to true, enables priority service tier shaping for matching Codex requests.

```yaml
plugins:
  configs:
    codex-service-tier:
      enabled: true
      priority: 1
      fast: false
```

--------------------------------

### Plugin ID Pattern

Source: https://github.com/router-for-me/cliproxyapi/blob/main/examples/plugin/simple/README.md

Defines the regular expression for valid plugin identifiers.

```regex
[A-Za-z0-9][A-Za-z0-9._-]{0,127}
```

--------------------------------

### Hot Reloading Providers

Source: https://github.com/router-for-me/cliproxyapi/blob/main/docs/sdk-access.md

Procedure for updating access providers at runtime when configuration changes.

```APIDOC
## Hot Reloading Providers

### Description
Refresh config-backed providers and reset the manager's provider chain to enable runtime updates without restarting the process.

### Request Example
```go
configaccess.Register(&newCfg.SDKConfig)
accessManager.SetProviders(sdkaccess.RegisteredProviders())
```
```

--------------------------------

### Successful JSON Response Envelope

Source: https://github.com/router-for-me/cliproxyapi/blob/main/examples/plugin/simple/README.md

The structure for a successful response from the plugin to the host.

```json
{
  "ok": true,
  "result": {}
}
```

--------------------------------

### Host HTTP Bridge Method

Source: https://github.com/router-for-me/cliproxyapi/blob/main/examples/plugin/simple/README.md

The specific method used by plugins to call host functionality for HTTP requests.

```text
host.http.do
```

--------------------------------

### Set Custom Round Tripper Provider

Source: https://github.com/router-for-me/cliproxyapi/blob/main/docs/sdk-advanced.md

Inject a per-authentication custom http.Transport, such as a proxy, by providing a custom provider to SetRoundTripperProvider. This is useful for advanced transport configurations.

```go
core.SetRoundTripperProvider(myProvider) // returns transport per auth
```

--------------------------------

### Hot Reload Access Providers

Source: https://github.com/router-for-me/cliproxyapi/blob/main/docs/sdk-access.md

Updates the provider registry and resets the manager's provider chain to reflect configuration changes at runtime.

```go
// configaccess is github.com/router-for-me/CLIProxyAPI/v6/internal/access/config_access
configaccess.Register(&newCfg.SDKConfig)
accessManager.SetProviders(sdkaccess.RegisteredProviders())
```

--------------------------------

### Authentication Error Semantics

Source: https://github.com/router-for-me/cliproxyapi/blob/main/docs/sdk-access.md

Defines the standard error codes and their corresponding HTTP status codes for authentication failures.

```APIDOC
## Authentication Error Semantics

### Error Codes
- **AuthErrorCodeNoCredentials** (401) - No credentials were present or recognized.
- **AuthErrorCodeInvalidCredential** (401) - Credentials were present but rejected.
- **AuthErrorCodeNotHandled** (N/A) - Fall through to the next provider.
- **AuthErrorCodeInternal** (500) - Transport or system failure.
```

--------------------------------

### JS Script API: on_before_request Context

Source: https://github.com/router-for-me/cliproxyapi/blob/main/examples/plugin/jshandler/README.md

The context object for the `on_before_request` hook provides details about the outgoing request, including its ID, body, headers, URL, model, and protocol. This allows modification of these properties before the request is sent upstream.

```javascript
{
    "id": "request-id",
    "body": "...",        // Request body string
    "headers": {},
    "url": "",
    "model": "gpt-4",
    "protocol": "openai"
}
```

--------------------------------

### JS Script API: on_after_nonstream_response Context

Source: https://github.com/router-for-me/cliproxyapi/blob/main/examples/plugin/jshandler/README.md

The context for the `on_after_nonstream_response` hook contains the full response body, request details, protocol, headers, and null values for chunk and history_chunks. This context is used to modify non-streaming responses.

```javascript
{
    "id": "request-id",
    "body": "...",        // Full response body
    "req": { "body": "...", "headers": {}, "url": "" },
    "protocol": "openai",
    "headers": {},
    "chunk": null,
    "history_chunks": null
}
```

--------------------------------

### Error JSON Response Envelope

Source: https://github.com/router-for-me/cliproxyapi/blob/main/examples/plugin/simple/README.md

The structure for an error response from the plugin to the host.

```json
{
  "ok": false,
  "error": {
    "code": "invalid_request",
    "message": "request is invalid"
  }
}
```

--------------------------------

### JS Script API: on_after_stream_response Context

Source: https://github.com/router-for-me/cliproxyapi/blob/main/examples/plugin/jshandler/README.md

The context for the `on_after_stream_response` hook includes the current streaming chunk and a read-only array of historical chunks, along with request and response details. This enables modification of individual streaming chunks.

```javascript
{
    "id": "request-id",
    "body": null,
    "req": { "body": "...", "headers": {}, "url": "" },
    "protocol": "openai",
    "headers": {},
    "chunk": "...",              // Current writable chunk
    "history_chunks": ["..."]    // Read-only frozen array
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.