// Copyright 2026 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

// Copyright 2026 The Agent Substrate Authors.
//
// Protocol Buffers definition for the Agent Substrate Environment Control Plane API.
// Exposes environment lifecycle operations (create, get, suspend, delete).

syntax = "proto3";

package ateenv.v1alpha;

option go_package = "github.com/agent-substrate/env/proto/ateenv/v1alpha;ateenvv1alpha";


// TODO(jbd): Migrate data plane (shell/fs) to guest.proto (ProcessService/FileSystemService).
// TODO(jbd): Remove env legacy HTTP REST endpoints for environment lifecycle.
// TODO(jbd): Update remaining examples and documentation.
// TODO(jbd): Add ListEnvironments to EnvironmentService.

// ============================================================================
// --- SERVICES ---
// ============================================================================

// EnvironmentService manages the lifecycle of isolated execution environments.
service EnvironmentService {
  // CreateEnvironment registers and starts a new environment from an actor template.
  rpc CreateEnvironment(CreateEnvironmentRequest) returns (CreateEnvironmentResponse);

  // GetEnvironment retrieves the status and configuration of an existing environment.
  rpc GetEnvironment(GetEnvironmentRequest) returns (GetEnvironmentResponse);

  // SuspendEnvironment checkpoints and stops an active environment.
  rpc SuspendEnvironment(SuspendEnvironmentRequest) returns (SuspendEnvironmentResponse);

  // DeleteEnvironment permanently removes an environment and its associated resources.
  rpc DeleteEnvironment(DeleteEnvironmentRequest) returns (DeleteEnvironmentResponse);
}

// ============================================================================
// --- TYPES & ENUMS ---
// ============================================================================

// Lifecycle status of an environment, matching Substrate actor statuses.
enum EnvironmentStatus {
  ENVIRONMENT_STATUS_UNSPECIFIED = 0;
  // Environment is resuming / warming up from snapshot.
  ENVIRONMENT_STATUS_RESUMING = 1;
  // Environment is active and ready to accept operations.
  ENVIRONMENT_STATUS_RUNNING = 2;
  // Environment is in the process of suspending.
  ENVIRONMENT_STATUS_SUSPENDING = 3;
  // Environment is suspended and checkpointed.
  ENVIRONMENT_STATUS_SUSPENDED = 4;
  // Environment is in the process of pausing.
  ENVIRONMENT_STATUS_PAUSING = 5;
  // Environment is paused.
  ENVIRONMENT_STATUS_PAUSED = 6;
  // Environment process crashed.
  ENVIRONMENT_STATUS_CRASHED = 7;
  // Environment is being deleted.
  ENVIRONMENT_STATUS_DELETING = 8;
}

// Template represents an ActorTemplate used to instantiate environments.
message Template {
  // Name of the ActorTemplate (e.g. "default-template").
  string name = 1;
  // Substrate atespace where the ActorTemplate is located.
  string atespace = 2;
}

// Environment represents an isolated execution environment backed by a Substrate actor.
message Environment {
  // Unique environment identifier (DNS-1123 label).
  string id = 1;
  // Substrate atespace where the environment actor lives.
  string atespace = 2;
  // ActorTemplate configuration the environment is instantiated from.
  Template template = 3;
  // Current lifecycle status of the environment.
  EnvironmentStatus status = 4;
}

// ============================================================================
// --- ENVIRONMENT SERVICE MESSAGES ---
// ============================================================================

// Request to create and start a new environment.
message CreateEnvironmentRequest {
  // Unique environment identifier (DNS-1123 label). Required.
  string id = 1;
  // Substrate atespace for the environment (defaults to "ate-env").
  string atespace = 2;
  // ActorTemplate configuration to instantiate (defaults to name "default-template" in atespace "ate-env").
  Template template = 3;
}

// Response returned after creating an environment.
message CreateEnvironmentResponse {
  // The created environment.
  Environment environment = 1;
}

// Request to inspect an environment.
message GetEnvironmentRequest {
  // Unique identifier of the environment to retrieve. Required.
  string id = 1;
  // Substrate atespace of the environment (defaults to "ate-env").
  string atespace = 2;
}

// Response containing environment details.
message GetEnvironmentResponse {
  // The requested environment.
  Environment environment = 1;
}

// Request to suspend an environment.
message SuspendEnvironmentRequest {
  // Unique identifier of the environment to suspend. Required.
  string id = 1;
  // Substrate atespace of the environment (defaults to "ate-env").
  string atespace = 2;
}

// Response returned after suspending an environment.
message SuspendEnvironmentResponse {}

// Request to delete an environment.
message DeleteEnvironmentRequest {
  // Unique identifier of the environment to delete. Required.
  string id = 1;
  // Substrate atespace of the environment (defaults to "ate-env").
  string atespace = 2;
}

// Response returned after deleting an environment.
message DeleteEnvironmentResponse {}