mirror of
https://github.com/openclaw/openclaw.git
synced 2026-05-03 01:50:22 +00:00
Docs: clarify generic interactive contracts
This commit is contained in:
Gustavo Madeira Santana
@@ -633,8 +633,8 @@ Required descriptor metadata:
|
||||
|
||||
First-cut constraint:
|
||||
|
||||
- the first interactive runtime cut may stay limited to Telegram and Discord because those are the validated immediate needs
|
||||
- that limitation is a rollout choice, not a reason to encode Telegram- or Discord-specific handler APIs as the permanent kernel contract
|
||||
- the first interactive runtime cut may be validated on Telegram and Discord because those are the immediate proven needs
|
||||
- that is a rollout choice only; the contract itself must stay generic, host-owned, and kernel-agnostic rather than becoming Telegram- or Discord-specific handler APIs
|
||||
|
||||
Ownership rule:
|
||||
|
||||
|
||||
@@ -216,7 +216,7 @@ What is still missing for these phases:
|
||||
- keeping the cutover inventory current as more surfaces move
|
||||
- broader lifecycle ownership beyond the loader state machine, service-lifecycle boundary, CLI-lifecycle boundary, session-owned activation state, and explicit discovery-policy, activation-policy, and finalization-policy outcomes, remaining policy gate ownership, and broad host-owned registries described for Phase 2
|
||||
- minimal SDK compatibility work beyond preserving current behavior indirectly through existing loading
|
||||
- host-owned conversation binding, interaction routing, ingress claim, and bounded interactive channel-control surfaces identified by external-plugin validation
|
||||
- host-owned conversation binding, interaction routing, ingress claim, and generic interactive control surfaces identified by external-plugin validation
|
||||
- any pilot migration, event pipeline, canonical catalog, or arbitration implementation
|
||||
|
||||
Recent plan refinement from external-plugin validation:
|
||||
@@ -224,7 +224,7 @@ Recent plan refinement from external-plugin validation:
|
||||
- the plan now explicitly treats conversation binding ownership, approval persistence, restore-on-restart behavior, and detached-binding cleanup as first-class migration surfaces
|
||||
- it now explicitly treats interactive callback routing, namespace ownership, dedupe, and fallback behavior as first-class migration surfaces
|
||||
- it now explicitly treats inbound claim as a canonical ingress-stage concern rather than a permanent plugin-era hook shape
|
||||
- it now explicitly limits the first-cut interactive channel-control surface to a bounded set of Telegram and Discord capabilities, but models them as host-owned adapter-runtime contracts rather than permanent product-shaped kernel APIs
|
||||
- it now explicitly treats Telegram and Discord as the first validated rollout targets for interactive control surfaces while keeping the underlying contracts generic, host-owned, and kernel-agnostic
|
||||
|
||||
## Implementation Order
|
||||
|
||||
|
||||
@@ -470,7 +470,7 @@ Before implementation starts, write and maintain a cutover inventory for every c
|
||||
- conversation binding ownership, approval persistence, and restore-on-restart behavior
|
||||
- interactive callback routing, namespace ownership, and dedupe
|
||||
- ingress claim and bound-route short-circuit behavior
|
||||
- bounded interactive channel-control helpers needed by external interactive agents
|
||||
- generic interactive control contracts needed by external interactive agents
|
||||
- slot selection and existing arbitration paths
|
||||
- status, reload, install, update, and diagnostics surfaces
|
||||
|
||||
@@ -581,7 +581,7 @@ Additional migration rule from external-plugin validation:
|
||||
|
||||
- conversation binding, interactive callback routing, and inbound claim are real runtime needs, but they must not be solved by turning `src/plugins/*` into the permanent public architecture
|
||||
- bind approvals, callback namespace routing, and bound-ingress short-circuit behavior belong to host-owned surfaces and canonical pipeline stages
|
||||
- first-cut interactive channel controls may be parity-driven around Telegram and Discord, but the long-term contract must remain adapter-runtime and host-owned rather than product-shaped kernel APIs
|
||||
- first-cut interactive channel controls may be validated first on Telegram and Discord, but the long-term contract must remain generic, adapter-runtime, host-owned, and kernel-agnostic rather than product-shaped kernel APIs
|
||||
|
||||
## 1d. Lightweight descriptors and distribution metadata
|
||||
|
||||
|
||||
@@ -92,9 +92,9 @@ This is an implementation checklist, not a future-design spec.
|
||||
| CLI registration | plugin CLI registration in `src/plugins/registry.ts` and CLI loaders | `src/extension-host/cli-lifecycle.ts` plus static descriptors where possible | `partial` | CLI duplicate detection, registrar invocation, and async failure logging now delegate through a host-owned CLI-lifecycle helper while `src/plugins/cli.ts` remains the compatibility entry point. |
|
||||
| Gateway/server methods | `src/plugins/registry.ts` gateway handler registration plus gateway runtime consumers | `src/extension-host/gateway-methods.ts` plus host-owned runtime contribution registry | `partial` | Gateway method-id aggregation, plugin diagnostic shaping, and extra-handler composition now delegate through a host-owned gateway-methods helper while request dispatch semantics still live in the gateway server code. |
|
||||
| Conversation binding ownership, approvals, and restore semantics | `src/plugins/conversation-binding.ts` plus `src/infra/outbound/session-binding-service.ts` | host-owned binding registry and approval policy surface | `not started` | External-plugin evaluation showed this is a real missing migration surface. The host needs to own plugin-scoped conversation binding, approval persistence, restore-on-restart behavior, detached-binding cleanup, and legacy binding migration without making `src/plugins/conversation-binding.ts` the long-term public surface. |
|
||||
| Interactive callback routing and namespace ownership | `src/plugins/interactive.ts` plus Telegram and Discord monitor-specific callback wiring | host-owned interaction router and namespace registry | `not started` | External-plugin evaluation showed this needs to be explicit. The host should own namespace registration, dedupe, fallback rules, and callback dispatch, while first-cut channel support stays intentionally limited to Telegram and Discord. |
|
||||
| Interactive callback routing and namespace ownership | `src/plugins/interactive.ts` plus Telegram and Discord monitor-specific callback wiring | host-owned interaction router and namespace registry | `not started` | External-plugin evaluation showed this needs to be explicit. The host should own namespace registration, dedupe, fallback rules, and callback dispatch. The first validated rollout may target Telegram and Discord, but the contract itself should stay generic and kernel-agnostic. |
|
||||
| Ingress claim and bound-route short-circuit semantics | `src/plugins/hooks.ts` typed `inbound_claim` hook plus `src/auto-reply/reply/dispatch-from-config.ts` | canonical event-pipeline ingress claim stage | `not started` | The behavior is conceptually in-scope today, but it should land as a canonical ingress-stage contract with legacy hook bridging only as migration. The key parity rule is first-claim-wins for route ownership while passive observers still run through their own stages. |
|
||||
| Interactive channel control verbs for bound agents | product-shaped runtime helpers added under `src/plugins/runtime/*` and direct channel-specific helpers in extension code | host-owned adapter runtime contracts and interaction capabilities | `not started` | The host needs a bounded first-cut set of control verbs for interactive agents, such as typing leases plus message or conversation actions. These should be injected as generic host-owned capabilities or adapter-runtime contracts, not frozen as permanent Telegram- or Discord-shaped kernel APIs. |
|
||||
| Interactive channel control verbs for bound agents | product-shaped runtime helpers added under `src/plugins/runtime/*` and direct channel-specific helpers in extension code | host-owned adapter runtime contracts and interaction capabilities | `not started` | The host needs a bounded first-cut set of control verbs for interactive agents, such as typing leases plus message or conversation actions. Those verbs should be expressed as generic host-owned adapter capabilities, even if the first validated rollout only exercises them through Telegram and Discord. |
|
||||
| Slot arbitration | `src/plugins/slots.ts` | host-owned arbitration model | `not started` | Current slot selection remains plugin-era logic. |
|
||||
| ACP backend registry | `src/acp/runtime/registry.ts` | host-owned runtime-backend registry | `not started` | ACP backends still mutate a global ACP runtime registry directly. |
|
||||
| Onboarding/install/setup surfaces | `src/plugins/install.ts`, package manifests, channel catalog, onboarding commands | host-owned static descriptors | `partial` | Static metadata normalization has started; full setup/install descriptor migration is not done. |
|
||||
@@ -151,7 +151,7 @@ The following remain legacy-owned today:
|
||||
- conversation binding ownership, approval persistence, and restore-on-restart behavior
|
||||
- interaction namespace routing, dedupe, and callback fallback rules
|
||||
- canonical ingress claim semantics
|
||||
- bounded interactive channel control contracts
|
||||
- generic host-owned interactive channel control contracts
|
||||
- slot arbitration
|
||||
- ACP backend registration
|
||||
- channel runtime compatibility bridges
|
||||
|
||||
Reference in New Issue
Block a user