# Devcontainer Resources

Devcontainer resources integrate the
[Development Containers Specification](https://containers.dev) into the
CleverAgents resource model. Two resource types and an auto-discovery
mechanism allow CleverAgents to detect, register, and use devcontainer
environments automatically.

## Resource Types

### `devcontainer-instance`

A container execution environment defined by a
`.devcontainer/devcontainer.json` configuration file. Inherits from
`container-instance` (see ADR-042 for resource type inheritance).

| Property          | Value                 |
|-------------------|-----------------------|
| Kind              | physical              |
| Sandbox strategy  | snapshot              |
| User-addable      | yes                   |
| Parent types      | git-checkout, fs-directory |
| Child types       | devcontainer-file     |
| Handler           | `DevcontainerHandler` |

**CLI arguments:**

- `--path` (path, required): Path to the directory containing
  `.devcontainer/devcontainer.json`.

### `devcontainer-file`

A single-file resource pointing to the `devcontainer.json`
configuration file itself. Created automatically as a child of
`devcontainer-instance` during auto-discovery.

| Property          | Value                 |
|-------------------|-----------------------|
| Kind              | physical              |
| Sandbox strategy  | copy\_on\_write       |
| User-addable      | no                    |
| Parent types      | devcontainer-instance |
| Child types       | (none)                |
| Handler           | `DevcontainerHandler` |

### `container-instance`

The base container resource type from which `devcontainer-instance`
inherits. Represents a generic container execution environment.

| Property          | Value                 |
|-------------------|-----------------------|
| Kind              | physical              |
| Sandbox strategy  | snapshot              |
| User-addable      | yes                   |
| Parent types      | git-checkout, fs-directory |
| Child types       | (none)                |
| Handler           | `DevcontainerHandler` |

## Auto-Discovery

When a `git-checkout` or `fs-directory` resource is linked to a
project, the auto-discovery hook scans for devcontainer configurations
in the following locations (relative to the resource root):

1. `.devcontainer/devcontainer.json`
2. `.devcontainer.json` (root-level)

### Discovery Process

1. **Trigger**: Linking a `git-checkout` or `fs-directory` resource.
2. **Scan**: The discovery module checks for configuration files at the
   well-known paths listed above.
3. **Validate**: Each discovered file is parsed as JSON. Invalid files
   are skipped with a warning.
4. **Register**: For each valid configuration:
   - A `devcontainer-instance` child resource is created under the
     parent resource.
   - A `devcontainer-file` child resource is created under the
     devcontainer instance, pointing to the JSON file.

### Lazy Activation

Devcontainers use lazy activation: the container is only built and
started when first needed by a plan execution. The discovery phase
only registers the resource metadata.

## CLI Usage

```bash
# Manually add a devcontainer instance
agents resource add devcontainer-instance local/my-dc --path /home/user/project

# Add a container instance
agents resource add container-instance local/my-ctr --image ubuntu:latest

# List all devcontainer resources
agents resource list --type devcontainer-instance

# Show devcontainer details
agents resource show local/my-dc

# View resource tree (shows devcontainer children)
agents resource tree local/my-repo

# Inspect resource with tree view
agents resource inspect local/my-repo --tree
```

## Architecture

The devcontainer integration follows ADR-043 and builds on the
resource type inheritance model defined in ADR-042.

### Handler

`DevcontainerHandler` extends `BaseResourceHandler` and uses the
`snapshot` sandbox strategy. It handles both `devcontainer-instance`
and `devcontainer-file` resource types through the common base class
resolve logic.

### Discovery Module

The `cleveragents.resource.handlers.discovery` module provides:

- `discover_devcontainers(location, type)`: Scans a path for
  devcontainer configs.
- `is_trigger_type(type)`: Checks if a resource type triggers
  auto-discovery.
- `DevcontainerDiscoveryResult`: Data class holding discovery results.

## See Also

- [ADR-042: Resource Type Inheritance](../adr/ADR-042-resource-type-inheritance.md)
- [ADR-043: Devcontainer Integration](../adr/ADR-043-devcontainer-integration.md)
- [Resource Types (Built-in)](resource_types_builtin.md)
- [Resource Handlers](resource_handlers.md)