github / github/copilot-sdk

Provide an opt-in managed-runtime launcher hook for host-controlled process ownership

Abierto
#2,582 0 comentarios 0 reacciones 0 asignados Ver en GitHub
enhancement
Lenguaje dominante
Java
Estrellas
10.5k
Forks
1.5k
Merge medio
1 d 11 h
PR fusionados (30 d)
127

Descripción

## Summary

The SDK's managed runtime connections are excellent for most applications: the SDK starts a compatible Copilot runtime, connects to it, and cleans it up automatically.

Some embedding hosts need to retain ownership of the runtime process from the instant it is created. Examples include desktop applications, long-lived services, worker hosts, managed execution environments, and applications with OS-level process containment or resource-governance requirements.

Could the SDK expose an opt-in launcher/lifecycle hook for managed runtime connections?

## Problem

Today an application can choose between two models:

1. Let the SDK launch and own the runtime process.
2. Launch a headless runtime independently and attach through a network connection.

The first model does not give the host a supported way to apply process containment, resource governance, or host-specific lifecycle handling at process creation.

The second model can add deployment and connection-management complexity. A host may also need a stronger way to establish that the runtime it connects to is the exact process it launched, rather than merely a process listening on a local endpoint.

There is no need to change the default SDK behavior. This is an advanced embedding requirement for hosts that already have mature process supervision.

## Proposed capability

Expose an optional factory or lifecycle interface used only when the SDK would otherwise launch a local runtime.

Illustrative Python shape:

```python
from copilot import CopilotClient, RuntimeConnection

def launch_runtime(command, options):
# Host launches the supplied command using its own process supervisor.
# Returns a process/lifecycle handle understood by the SDK.
...

client = CopilotClient(
connection=RuntimeConnection.for_stdio(
runtime_launcher=launch_runtime,
),
)
```

Or, if a lifecycle object is preferable:

```python
class RuntimeProcess:
def wait_ready(self, timeout: float) -> None: ...
def terminate(self, grace_period: float) -> None: ...
def wait(self, timeout: float | None = None) -> int | None: ...
@property
def stdin(self): ...
@property
def stdout(self): ...
@property
def stderr(self): ...

client = CopilotClient(
connection=RuntimeConnection.for_stdio(
runtime_factory=create_runtime_process,
),
)
```

The exact API shape is less important than these properties:

- The host receives the final runtime command and launch options **before** the runtime starts.
- The SDK retains ownership of protocol negotiation, session management, and normal client cleanup.
- The host can apply OS-native containment and observability at process birth.
- Process termination responsibilities are explicit and cannot result in double ownership.
- The default managed-runtime behavior remains unchanged.
- The abstraction works with local stdio first; it should not require an application to expose a TCP listener merely to control child-process ownership.

## Why stdio matters

A host-controlled stdio launcher avoids introducing a network endpoint solely for local embedding. It also keeps the runtime connection bound directly to the process the host created, which simplifies lifecycle, containment, and cleanup reasoning.

## Non-goals

- Changing default SDK startup behavior.
- Requiring applications to implement their own JSON-RPC transport.
- Replacing the SDK's runtime provisioning or compatibility management.
- Adding remote-runtime deployment features.
- Exposing private SDK process internals after startup.

## Questions for maintainers

1. Is there an existing supported extension point for host-owned runtime creation that I may have missed?
2. Would a launcher callback or a small lifecycle protocol be more consistent with the SDK's cross-language design?
3. Should this apply only to stdio transport, or also to SDK-managed TCP and in-process transports?
4. What lifecycle boundary would maintainers want the host to own versus the SDK to own?

I can provide a small implementation proposal once there is agreement on the intended API and cross-language scope.

Guía de contribución

Abrir la guía de contribución

Línea de trabajo

The proposed entry points are CopilotClient and RuntimeConnection.for_stdio; begin by tracing the existing managed-runtime launch and cleanup path, which the issue does not locate in files. Done means an agreed opt-in stdio launcher or lifecycle API with explicit ownership semantics, unchanged default behavior, and a defined cross-language scope.

Escrito por el modelo de indexación a partir del texto del issue.

Evaluación

Stack tecnológico
java, python
Área
api, backend
Tipo de issue
Nueva funcionalidad
Dificultad
5/5
Tiempo estimado
Más de una semana
Estado de actividad
Activo
Claridad
Necesita aclaración
Aptitud para principiantes
25/100

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.