agentera 0.0.0 → 3.0.0-dev.1

package/bundle/references/adapters/runtime-adapter-characterization.md

@@ -0,0 +1,79 @@
+# Runtime Adapter Characterization
+
+Task 2 of `Deepen RuntimeAdapter Registry` records current behavior before any
+registry extraction. This is a characterization artifact, not the new registry.
+
+## Doctor Output
+
+Current JSON envelope fields are `schemaVersion`, `ok`, `installRoot`,
+`runtimes`, `summary`, and `smoke`. Each runtime result exposes `runtime`,
+`status`, `available`, `binary`, and `checks`. Each check exposes `name`,
+`status`, `message`, `source`, `path`, `gap`, and `details`.
+
+Primary pass messages by runtime:
+
+| Runtime | Primary check | Status | Message | Diagnostic label |
+|---------|---------------|--------|---------|------------------|
+| Claude Code | `CLAUDE_PLUGIN_ROOT` | `pass` | `runtime can reach shared Agentera helper scripts` | none |
+| OpenCode | `plugin_file` | `pass` | `OpenCode plugin file is present` | none |
+| Copilot CLI | `AGENTERA_HOME` | `pass` | `runtime can reach shared Agentera helper scripts` | none |
+| Codex CLI | `config.AGENTERA_HOME` | `pass` | `runtime can reach shared Agentera helper scripts` | none |
+
+Current diagnostic labels that are intentionally public are `user_environment`,
+`runtime_config`, `bundle_packaging`, `command_drift`, `skill_path_drift`, and
+`validation_drift`.
+
+## Upgrade Planning
+
+Runtime-phase items currently expose `runtime`, `action`, `target`, `status`,
+and `message`; copy operations also expose `source`, and configure operations
+carry private `newText` until public JSON rendering strips it.
+
+Characterized runtime actions:
+
+| Runtime | Action | Target | Dry-run status | Apply behavior |
+|---------|--------|--------|----------------|----------------|
+| Claude Code | `configure` | none | `noop` | no local config write |
+| Codex CLI | `configure` | `~/.codex/config.toml` | `pending` | writes config, then reports `runtime update applied` |
+| Codex CLI | `copy-hooks` | `~/.codex/hooks.json` | `pending` | copies hooks, then reports `runtime update applied` |
+| Codex CLI | `copy-agent` | `~/.codex/agents/*.toml` | `pending` | copies managed capability descriptors, then reports `runtime update applied` |
+| Copilot CLI | `configure` | none | `noop` | no local config write; use per-invocation `AGENTERA_HOME` |
+| OpenCode | `copy-plugin` | `~/.config/opencode/plugins/agentera.js` | `pending` | copies plugin, then reports `runtime update applied` |
+| OpenCode | `copy-agent` | `~/.config/opencode/agents/*.md` | `pending` | copies managed capability descriptors, then reports `runtime update applied` |
+
+Package-phase items currently expose `runtime`, `action`, `command`, `status`,
+and `message`. Without `--update-packages`, package items are `skipped`; with it,
+Claude Code and OpenCode package commands become `pending` and apply through the
+external command runner. Copilot CLI and Codex CLI have no package command item in
+the current upgrade phase.
+
+## Lifecycle Validation
+
+Current pass output from `scripts/validate_lifecycle_adapters.py` is exactly:
+
+```text
+lifecycle adapter metadata ok
+```
+
+Current failure output begins with:
+
+```text
+lifecycle adapter validation failed:
+```
+
+Representative fail messages are characterized in `tests/test_runtime_adapters.py`:
+Copilot stale `lifecycleHooks`, unsupported hook event files, missing `preToolUse`
+artifact validation, Codex unsupported status values, malformed event containers,
+missing supported-event declarations, missing unsupported-event declarations, and
+missing `codex_hooks` limitation text.
+
+## Drift Inventory
+
+| Drift point | Decision | Before-migration handling |
+|-------------|----------|---------------------------|
+| duplicated runtime order appears in doctor, upgrade, and tests | `standardize` | Later registry extraction should define one runtime order and have consumers read it. |
+| upgrade package phase only manages Claude Code and OpenCode | `preserve` | This is current behavior, not a registry gap; Copilot CLI and Codex CLI package command support is separate future work. |
+| Codex supports hook events but shipped config wires only apply_patch validation | `preserve` | Keep the distinction between host support and shipped Agentera wiring. |
+| Claude lifecycle behavior is validated through native hook files, not lifecycle metadata | `defer` | Do not invent Claude lifecycle metadata in Task 2; decide during registry interface design. |
+| OpenCode session preload observes `session.created` but has no verified context injection path | `preserve` | Keep degraded preload semantics in docs and diagnostics. |
+| hard-gate docs only claim blocking for reconstructable OpenCode and Copilot candidates | `preserve` | Keep scoped claims; do not standardize to full hard-gate parity. |

package/bundle/references/adapters/runtime-adapter-interface-model.yaml

@@ -0,0 +1,200 @@
+interface: RuntimeAdapter
+status: design_contract
+purpose: >-
+  Define the runtime-owned facts that a later registry Module may expose without
+  absorbing package metadata, app-home classification, or caller behavior.
+record:
+  required_groups:
+    - identity
+    - host_detection
+    - lifecycle_events
+    - artifact_validation
+    - subagent_dispatch
+    - config_targets
+    - diagnostics
+    - documentation_claims
+  groups:
+    identity:
+      type: object
+      owns:
+        - runtime_id
+        - display_name
+        - adapter_family
+        - support_status
+      required_fields:
+        runtime_id: string
+        display_name: string
+        adapter_family: string
+        support_status: enum
+    host_detection:
+      type: object
+      owns:
+        - binary_names
+        - host_config_locations
+        - availability_probe_label
+      required_fields:
+        binary_names: list[string]
+        host_config_locations: list[string]
+        availability_probe_label: string
+    lifecycle_events:
+      type: object
+      owns:
+        - supported_events
+        - unsupported_events
+        - event_status
+        - limitations
+      required_fields:
+        supported_events: list[string]
+        unsupported_events: list[string]
+        event_status: map[string,string]
+        limitations: list[string]
+    artifact_validation:
+      type: object
+      owns:
+        - validation_events
+        - hard_gate_claims
+        - payload_reconstruction_limitations
+      required_fields:
+        validation_events: list[string]
+        hard_gate_claims: list[string]
+        payload_reconstruction_limitations: list[string]
+    subagent_dispatch:
+      type: object
+      owns:
+        - mechanism
+        - setup_targets
+        - descriptor_sources
+        - invocation_pattern
+        - limitations
+        - tool_configuration
+      required_fields:
+        mechanism: string
+        setup_targets: list[string]
+        descriptor_sources: list[string]
+        invocation_pattern: string
+        limitations: list[string]
+    config_targets:
+      type: object
+      owns:
+        - runtime_config_files
+        - hook_targets
+        - plugin_targets
+        - environment_exports
+        - write_safety_labels
+      required_fields:
+        runtime_config_files: list[string]
+        hook_targets: list[string]
+        plugin_targets: list[string]
+        environment_exports: list[string]
+        write_safety_labels: list[string]
+    diagnostics:
+      type: object
+      owns:
+        - check_names
+        - status_labels
+        - gap_labels
+        - primary_messages
+      required_fields:
+        check_names: list[string]
+        status_labels: list[string]
+        gap_labels: list[string]
+        primary_messages: list[string]
+    documentation_claims:
+      type: object
+      owns:
+        - reference_paths
+        - parity_claims
+        - install_claims
+        - known_drifts
+      required_fields:
+        reference_paths: list[string]
+        parity_claims: list[string]
+        install_claims: list[string]
+        known_drifts: list[string]
+ownership:
+  runtime_adapter_owns:
+    - runtime identity and display labels
+    - host detection facts used by runtime-facing consumers
+    - lifecycle event support and limitations
+    - artifact validation support claims
+    - runtime-native subagent dispatch descriptor and invocation facts
+    - runtime config, hook, plugin, and environment target paths
+    - diagnostic check names, statuses, gaps, and messages
+        - adapter documentation parity and known-mismatch claims
+  package_metadata_out_of_scope:
+    owner: package_manifest_registry
+    deferred_todo: arch-package-manifest-registry
+    facts:
+      - version_authority
+      - package_manifest_schemas
+      - shared_package_paths
+      - release_metadata
+  install_root_out_of_scope:
+    owner: scripts/install_root.py
+    facts:
+      - AGENTERA_HOME precedence
+      - default app home
+      - managed classification
+      - stale classification
+      - unmanaged classification
+      - app-home diagnostics
+consumer_permissions:
+  lifecycle_validation:
+    allowed_groups:
+      - identity
+      - lifecycle_events
+      - artifact_validation
+      - subagent_dispatch
+      - documentation_claims
+    forbidden_ownership:
+      - package_metadata_out_of_scope
+      - install_root_out_of_scope
+  doctor:
+    allowed_groups:
+      - identity
+      - host_detection
+      - config_targets
+      - diagnostics
+      - documentation_claims
+    forbidden_ownership:
+      - package_metadata_out_of_scope
+      - install_root_out_of_scope
+  upgrade:
+    allowed_groups:
+      - identity
+      - host_detection
+      - subagent_dispatch
+      - config_targets
+      - diagnostics
+    forbidden_ownership:
+      - package_metadata_out_of_scope
+      - install_root_out_of_scope
+  docs:
+    allowed_groups:
+      - identity
+      - lifecycle_events
+      - artifact_validation
+      - subagent_dispatch
+      - config_targets
+      - diagnostics
+      - documentation_claims
+    forbidden_ownership:
+      - package_metadata_out_of_scope
+      - install_root_out_of_scope
+  tests:
+    allowed_groups:
+      - identity
+      - host_detection
+      - lifecycle_events
+      - artifact_validation
+      - subagent_dispatch
+      - config_targets
+      - diagnostics
+      - documentation_claims
+    forbidden_ownership:
+      - package_metadata_out_of_scope
+      - install_root_out_of_scope
+non_goals:
+  - Do not introduce an executable RuntimeAdapter registry Module in this task.
+  - Do not migrate lifecycle validation, doctor, upgrade, docs, or runtime tests to consume a registry in this task.
+  - Do not change app-home classification, package metadata validation, artifact write validation, or live runtime behavior.