Proposal: lifecycle-managed Extension Runtime for safe agent self-extension

[xxhZs]

Problem

Maka currently has several extension mechanisms, including built-in tools, deferred load_tools groups, Skills, MCP, automations, and Agent Graph capabilities. However, these capabilities are assembled through fixed startup or backend wiring. An agent can reveal a tool that was already registered, but it cannot safely define, activate, inspect, update, stop, or remove a new runtime capability.

Adding dynamic scripts directly to the existing process would create a second problem: a script update could mutate the tool surface or leave listeners, timers, UI entries, and other effects behind while an Agent Run is active. This would conflict with Maka's durable Run, continuation, permission, and recovery guarantees.

The goal should not be a second plugin runtime beside the existing one. Maka's shipped capabilities should remain the protected core composition, while installed and agent-authored extensions enter through the same composition boundary.

Desired outcome

Introduce a lifecycle-managed Extension Runtime that lets capabilities behave like applications:

• Define or install an immutable extension revision without running it.
• Activate an exact revision and own every effect it contributes.
• Stop it cleanly while retaining the revision.
• Update through a prepared candidate without disturbing the current activation.
• Roll back when preparation or activation fails.
• Uninstall only after active work has drained.
• Inspect the live extension surface and its diagnostics.

Static packages and agent-authored scripts should use one model. Temporary versus persistent behavior should be expressed by binding scope and lifetime rather than separate plugin systems.

Each Agent Run should use an immutable Extension Composition snapshot. Changes produce a candidate composition for future work and must never mutate the composition of an active Run.

The protected core should initially remain non-replaceable. Extensions may contribute through explicit, typed surfaces, introduced progressively:

1. Tools
2. Runtime inspection and control
3. Agent-authored session extensions
4. UI slots
5. Read-only runtime observation
6. Restricted decision hooks, context, state, timers, and Agent Graph capabilities

Untrusted or agent-authored code must not execute directly inside the Electron main process. Lifecycle cleanup and execution isolation are separate requirements: lifecycle ownership prevents leaked effects, while an isolated extension host prevents faulty code from destabilizing the core process.

Proposed product and architecture direction

Core concepts

• Extension: stable identity.
• Revision: immutable package contents, manifest, permissions, and compatibility metadata.
• Contribution: one capability exposed through a typed extension surface, such as a Tool or UI slot.
• Binding: declares which revision is desired for a process, user, workspace, session, or run scope.
• Composition Snapshot: deterministic resolved set of core and extension contributions used by a Run.
• Activation: one live instance that owns its workers, registrations, listeners, timers, UI entries, and state handles.

Lifecycle semantics

Keep definition and execution separate:

define/install
  -> validate
  -> prepare exact revision
  -> activate
  -> drain
  -> stop
  -> uninstall

Updates should follow current/candidate semantics:

current activation remains live
  -> prepare candidate
  -> validate dependencies and policy
  -> health check
  -> commit at a safe Runtime boundary
  -> drain old activation

A failed candidate must not move the committed pointer.

Integration principle

The existing built-in tool set becomes the protected core provider of the same composition model. Existing model, collaboration-mode, permission, sandbox, and product-tool filters remain the final authority after extension contributions are resolved.

The existing Runtime generation and safe admission boundaries should remain authoritative. Extension changes may become visible to a later provider step or later Turn only when the corresponding immutable snapshot has been admitted safely.

Agent experience

After the runtime model is proven with trusted extensions, expose a small control surface:

inspect -> define -> validate/test -> run -> inspect -> stop/update -> remove

Defining a revision must have no runtime effect. Agent-authored revisions should initially be session-scoped, explicitly approved, resource-limited, and executed outside the core process.

Suggested roadmap

Phase 0 — Boundary and invariants

• Define protected core authority versus extensible capability surfaces.
• Specify Run composition immutability, cleanup, rollback, permission, and recovery invariants.

Phase 1 — Lifecycle and revision model

• Establish Extension, Revision, Contribution, Binding, Composition Snapshot, and Activation semantics.
• Prove complete cleanup, dependency waiting, failed-start rollback, and current/candidate behavior independently of product features.

Phase 2 — Trusted Tool vertical slice

• Use Tool as the first contribution type.
• Route trusted static Tool extensions through the same final filters as built-in tools.
• Preserve exact behavior when only the core composition is enabled.
• Pin each Run to an immutable composition.

Phase 3 — Runtime inspection and control

• Expose the actual live contribution catalog, composition, owners, dependencies, activation status, and diagnostics.
• Use one control plane for the UI and agent-facing operations.

Phase 4 — Agent-authored session extensions

• Support define, validate/test, run, call, stop, update, rollback, and remove.
• Keep definitions effect-free until activation.
• Use isolated execution and explicit capabilities.
• Allow immediate calls through a stable extension bridge; advertise a new native tool schema only at a safe request boundary.

Phase 5 — UI contributions

• Add explicit UI slots and coordinated host/client activation.
• Retract both sides as one owned activation.
• Start with declarative or otherwise isolated UI contributions.

Phase 6 — Additional contribution surfaces

• Add read-only observation first.
• Then introduce restricted decision hooks, context contributions, state, timers, and existing Agent Graph or child-agent capabilities.
• Keep core Runtime authority and durable event semantics non-overridable.

Phase 7 — Persistence and distribution

• Add persistent bindings, restart recovery, promotion from session draft to verified release, signatures, compatibility metadata, revocation, and catalog workflows.

Non-goals for the first milestone

• Replacing Maka's core Runtime, persistence, continuation, permission, or credential authorities.
• Making every Domain Module dynamically replaceable.
• Allowing arbitrary scripts inside Electron main or the main renderer.
• Shipping Tool, UI, and unrestricted hooks simultaneously.
• Building a marketplace before the lifecycle, Tool slice, composition, and inspection model are proven.

Acceptance principles

• An active Run never changes composition.
• Revisions are immutable.
• Every activation-owned effect is removed on stop, failure, update, and scope disposal.
• A failed candidate cannot affect the committed activation.
• Extension permissions cannot exceed final Runtime policy.
• Recovery never silently substitutes another revision.
• Disabling all extension bindings yields the same core-only behavior through the same composition path.

[ARE404]

I like this direction. A few additional product and ecosystem principles may be worth making explicit before the lifecycle model is turned into implementation work.

1. Protected kernel + profile/composition, not “everything is replaceable”

I think a complete Maka application can be understood as:

protected Maka kernel
+ platform capabilities
+ desired profile/bindings
= resolved immutable composition

The profile is only the desired application shape; the admitted Composition Snapshot is the exact execution shape for a Run.

Tools, UI slots, hooks, context providers, timers, and selected Agent Graph capabilities can all become typed Contributions. That does not mean every authority becomes a replaceable plugin. Runtime Event Log ownership, Run/Turn admission, permission and sandbox ceilings, credentials, continuation, recovery, and the Agent Graph durable control plane should remain protected.

For Agent Graph specifically, extensions may eventually contribute tools, operator/provider implementations, observers, policies within a bounded seam, or UI. They should not replace durable scheduling/admission/recovery authority.

So I would state the boundary as:

Everything extensible is a typed contribution, but not everything authoritative is replaceable.

2. Treat external ecosystem interoperability as a design goal

Maka should avoid creating an isolated plugin ecosystem. In particular, I would like the Extension Runtime to support interoperability with both Pi extensions and DeepSeek Harness plugins.

The preferred order could be:

1. The same package runs directly in both hosts where the semantics align.
2. The package shares its implementation and exposes thin host-specific entry points, for example maka.ts, pi.ts, and/or a DeepSeek Harness adapter.
3. A converter generates the target manifest/entry wrapper for a portable subset.
4. Unsupported behavior fails with an explicit compatibility report; conversion must never silently drop UI, lifecycle, permission, or isolation semantics.

This probably requires a small Portable Extension Contract, rather than copying every API from either host. A first portable subset could cover:

• stable extension identity and version metadata;
• Tool names, descriptions, input/result schemas, and implementations;
• configuration schema;
• explicit capability requirements;
• bounded activation/cleanup hooks;
• host-independent diagnostics.

Host-specific UI, shortcuts, arbitrary Node.js authority, event waterfalls, or behavior that changes core permission/runtime authority would need adapters or be reported as unsupported/blocked.

“Compatible” should mean semantic compatibility that can be validated, not an unrealistic promise that arbitrary TypeScript source can always be mechanically translated. Round trips do not need to preserve source bytes, but declared portable identity, schemas, configuration, and behavior should remain equivalent.

It may also be useful for one package to declare multiple host entries while keeping most code shared:

my-extension/
  package.json
  maka.extension.json
  src/
    shared.ts
    maka.ts
    pi.ts
    deepseek.ts
  tests/

The concrete manifest is a later decision. I would define the semantic contract before choosing JSON, YAML, TypeScript builders, or a profile DSL.

Compatibility must not weaken Maka's model: loading a Pi or DeepSeek plugin cannot implicitly allow arbitrary code in Electron main, bypass final Runtime policy, or mutate an active Run's composition.

3. Make one plugin a reviewable PR-sized contribution

A complete extension should be deliverable as one self-contained PR containing, as applicable:

• manifest, stable identity, and revision;
• implementation;
• permissions/capability declarations;
• automated and lifecycle cleanup tests;
• documentation and a minimal example;
• Pi/DeepSeek entry points or a generated compatibility report;
• migration, update, rollback, and uninstall notes for stateful extensions;
• dependency, license, and security information.

Ideally, an ordinary plugin PR adds an isolated extension directory and registration data. It should not scatter special cases across the Agent Loop, persistence, permission, or UI core. If a new core seam is required, it should be justified as a reusable extension point.

Also, PR merge, Revision installation, Binding commit, and Activation should remain four distinct operations. Merging reviewed source must not itself mean that the extension is immediately active.

4. Allow excellent plugins to graduate

Extensions should not be permanent second-class capabilities. A plugin that proves broadly useful, stable, safe, well-tested, performant, and maintainable should be able to graduate:

third-party extension
-> verified extension
-> first-party/default-profile extension
-> protected kernel only when it truly owns unavoidable authority

Most excellent plugins should probably graduate into a first-party package or a default Profile, not into the protected kernel.

Graduation should move the implementation rather than copy it. It should preserve/migrate the Extension ID, configuration, and state; retain interoperability adapters where useful; prevent the old plugin and built-in version from activating together; and continue through the same Contribution/Composition path. Becoming built-in should change distribution and maintenance ownership, not create a bypass around the extension model.

5. A few contracts worth adding to the RFC

Before implementation, I think the proposal would benefit from pinning down:

• the persisted identity/digest of a Composition Snapshot and where it is attached to RootTurn/AgentRun admission;
• deterministic conflict, dependency, ordering, and scope precedence rules;
• an explicit Revision/Binding/Activation state machine including crash recovery;
• idempotent, quiescent, reverse-order cleanup of activation-owned effects;
• residency/GC rules preventing uninstall while an admitted Run still references a Revision;
• compatibility reports and conformance tests for portable Pi/DeepSeek contributions.

This could remain an umbrella RFC, with separate implementation issues for the lifecycle kernel, trusted Tool slice, inspection, isolated host, profile representation, and ecosystem converters.