Skip to content

Support plugin-contributed Agent Harnesses through contributes.agentHarnesses #40889

Open

Description

@isayaGIT

Problem

Orca plugins can currently observe or rewrite an existing agent launch through agent.launch.before, but they cannot contribute a named agent to the Agent Picker or Settings → Agents. The hook also does not cover restored sessions, so a plugin-selected wrapper can be lost on resume. This prevents plugins from providing a first-class, lifecycle-safe agent integration.

The manifest already reserves contributes.agentHarnesses, and the plugin authoring docs describe it as declarative coding-agent harness definitions.

Proposed direction

Allow an enabled plugin to contribute one or more plugin-owned agent definitions through contributes.agentHarnesses. Prefer reusing the base-harness identity and launch-profile model being developed for Custom Agents (see #8337 and #9136), rather than introducing a second independent agent catalog.

A contributed entry should:

  • Have a stable, namespaced identity derived from the plugin ID and contribution ID.
  • Declare a base built-in harness separately from its launch command, so process recognition, prompt injection, permissions, status handling, and resume continue to use the correct base identity.
  • Be selectable anywhere an agent can be selected: new-agent picker, worktree creation, automation/CLI surfaces where supported, and session resume.
  • Be owned by the contributing plugin: users can enable/disable it, but should not accidentally edit or delete the plugin's source definition as if it were a user-created custom profile.
  • Refresh when the plugin updates. If the plugin is disabled or removed while existing worktrees/sessions still reference the entry, preserve the reference and fail clearly rather than silently launching a different agent.
  • Use declarative, validated manifest data; do not grant a plugin arbitrary access to the host launch process merely by contributing an entry.

A useful follow-on is project-scoped default selection for future worktrees, with an explicit per-worktree override. This should reuse Orca's existing workspace/project settings ownership rather than being stored as an opaque plugin-only preference.

Why this matters

This supports wrappers, named provider profiles, remote execution backends, managed runtimes, and other integrations without requiring each plugin to maintain an Orca fork or asking users to manually create and maintain a matching Custom Agent.

Questions for maintainers

  1. Should plugin contributions be projected into the Custom Agent catalog introduced by Custom agents #8337, or is a separate immutable provider registry preferred?
  2. Which launch metadata should be declarative in agentHarnesses, and which behavior should remain in plugin hooks/runtime?
  3. Should project defaults and worktree overrides be part of the same change or a follow-up?

I'm happy to implement this against the intended Custom Agent architecture once the preferred ownership and lifecycle contract is clear.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions