idkmesh

Agent and Model Connector Control Plane

Status: implementation target / architecture proposal
Date: 2026-09-22
Scope: productize the existing WorkUnit/WorkerAdapter/verification foundation into an easy-to-connect GitHub + agent + model platform.

1. Product objective

IDKMesh should become easy to use in two successive loops:

  1. Build IDKMesh with external agents and models.
  2. Use IDKMesh itself to build and maintain other applications.

The first loop is bootstrap. The second loop is the product proof.

The intended user experience is not “install ten bots and hand them repository tokens.” It is:

connect repository
 -> connect one or more agent/model providers
 -> test connections
 -> declare policy
 -> convert issue/spec into bounded WorkUnit
 -> dispatch to eligible worker
 -> collect canonical candidate evidence
 -> verify independently
 -> open/review PR
 -> explicit human integration decision

The current repository already has most of the semantic foundation:

The missing product layer is a Connector Control Plane.

2. Design rule: model != agent != execution backend != GitHub

Do not collapse these concepts.

Model provider

A model provider generates model responses. Examples:

A raw model should not receive repository authority by itself.

Agent runner

An agent runner supplies the tool loop around one or more models. Examples:

An agent receives a bounded task and returns a candidate result.

Execution backend

The execution backend determines where and how a worker runs:

SCM/project connector

The SCM connector maps project events and candidate changes:

This separation lets IDKMesh replace any one part without rewriting the coordinator.

3. Target architecture

                         GitHub
          issues / PRs / webhooks / checks
                            |
                            v
                  +--------------------+
                  |  SCM Connector     |
                  |  GitHub adapter    |
                  +---------+----------+
                            |
                            v
                  +--------------------+
                  | Connector Control  |
                  | Plane              |
                  |                    |
                  | registry           |
                  | policy             |
                  | routing            |
                  | run state          |
                  | secret refs        |
                  +----+----------+----+
                       |          |
              +--------+          +-------------------+
              |                                       |
              v                                       v
    +-------------------+                  +---------------------+
    | Agent Connectors  |                  | Model Providers     |
    |                   |                  |                     |
    | Jules REST        |                  | OpenAI-compatible   |
    | OpenHands         |                  | Gemini-compatible   |
    | goose             |                  | Ollama              |
    | Gemini CLI        |                  | vLLM                |
    | mini-SWE-agent    |                  | OpenRouter          |
    | A2A/MCP workers   |                  | LiteLLM gateway     |
    +---------+---------+                  +----------+----------+
              |                                       |
              +------------------+--------------------+
                                 |
                                 v
                    +-------------------------+
                    | Execution Backends      |
                    | hosted / Docker / node  |
                    +------------+------------+
                                 |
                                 v
                      untrusted candidate
                                 |
                                 v
                  ResultManifest + artifacts
                                 |
                                 v
                independent verifier/evidence
                                 |
                                 v
                      explicit human merge

The control plane is a broker and normalizer. It does not become merge authority.

4. Connector kinds

Every configured integration should declare one of four connector kinds.

scm

Project/repository integration.

Initial driver:

Later:

agent

A complete task-execution agent.

Initial drivers:

Concrete presets can map to OpenHands, goose, Gemini CLI, mini-SWE-agent, and similar systems without adding coordinator branches.

model

Model inference provider for local/self-hosted agent loops.

Initial driver:

This one interface can cover several useful providers and local servers by changing base URL, model and secret reference. Native provider drivers should be added only when required features cannot be represented faithfully.

execution

Worker runtime/sandbox.

Initial drivers:

Hosted agents such as Jules own their execution substrate internally; the IDKMesh connector records that fact rather than pretending the local control plane owns the sandbox.

5. Why Jules should be the first remote API connector

As of 2026-09-22, Jules provides an alpha REST API with:

Primary documentation:

This is a strong first connector because IDKMesh already uses Jules in the repository, but current integration is mostly GitHub-label based.

The first implementation should default to:

{
  "requirePlanApproval": true
}

until bounded real-task evidence supports wider automation.

The Jules source itself must still be connected through the Jules web/GitHub installation flow; the API can list/use sources but does not currently create them.

6. OpenHands and GitHub-native agents

OpenHands currently documents a GitHub Action flow triggered by:

Reference:

That should initially be represented as a GitHub-native agent connector, not forced into a fake synchronous HTTP API.

Generic connector mode:

submit WorkUnit
 -> add configured label/comment through constrained SCM connector
 -> observe issue/PR events
 -> bind resulting PR/head SHA to the run
 -> collect candidate patch + metadata
 -> normalize to ResultManifest

The same mode can later cover other GitHub-native coding agents.

7. Local agent connectors

goose currently exposes desktop, CLI and API surfaces and supports multiple model providers plus MCP extensions.

Reference:

The local agent path should use a generic allowlisted executable adapter behind the canonical sandbox/node boundary:

WorkUnit
 -> disposable workspace at exact source SHA
 -> allowlisted agent driver
 -> configured model connection
 -> patch / logs / test evidence
 -> ResultManifest
 -> cleanup

Initial local presets:

Do not let issue text choose the executable, shell template, secret reference, network policy, or filesystem mounts.

8. Model-provider strategy

8.1 OpenAI-compatible driver first

The minimum useful model interface should be an OpenAI-compatible HTTP client.

That immediately supports or can support:

Relevant current references:

8.2 Native adapters only when needed

Compatibility APIs do not expose every provider-specific feature. Add a native provider driver only when a concrete product requirement cannot be expressed with the common interface.

Examples of possible later native drivers:

The common model API is therefore a portability baseline, not a claim that every provider is semantically identical.

8.3 LiteLLM is optional infrastructure

LiteLLM can expose many providers through one OpenAI-style gateway and provides routing, rate limiting and budget controls.

It should be supported as an optional deployment component, not imported into the dependency-free IDKMesh core.

This keeps the policy boundary clear:

IDKMesh owns:
  task authority
  connector eligibility
  WorkUnit semantics
  verification
  provenance
  human integration

Optional gateway owns:
  provider request translation
  provider retry/fallback
  provider-level rate/cost plumbing

9. Dependency boundary

The current installable idkmesh package intentionally keeps gate-audit dependency-free.

Preserve that.

Recommended packaging:

idkmesh core
  stdlib-only connector contracts/config validation where practical
  gate-audit remains dependency-free

idkmesh[connectors]
  HTTP client/runtime dependencies required by live connectors

idkmesh[control]
  optional HTTP service dependencies

idkmesh[verify]
  existing verification dependency

Do not make a user install a web server, SDKs, Docker client, or provider SDK merely to run idkmesh gate-audit.

10. Core interfaces

The control-plane implementation should converge on small interfaces.

10.1 Agent connector

Conceptual Python contract:

class AgentConnector(Protocol):
    connector_id: str
    connector_version: str

    def capabilities(self) -> AgentCapabilities: ...
    def probe(self) -> ConnectionProbe: ...
    def submit(self, work_unit: dict, context: DispatchContext) -> RunHandle: ...
    def inspect(self, run_id: str) -> AgentRunSnapshot: ...
    def cancel(self, run_id: str) -> AgentRunSnapshot: ...
    def collect(self, run_id: str) -> AdapterExecution: ...

The returned AdapterExecution should feed the existing run_with_adapter() normalization path or a direct successor of that contract.

10.2 Model provider

class ModelProvider(Protocol):
    provider_id: str

    def probe(self) -> ConnectionProbe: ...
    def list_models(self) -> tuple[ModelDescriptor, ...]: ...
    def generate(self, request: ModelRequest) -> ModelResponse: ...

The model interface is used by local agent runners; GitHub issue dispatch should normally target an AgentConnector, not ModelProvider.generate() directly.

10.3 SCM connector

class SCMConnector(Protocol):
    def repository_snapshot(self, project_id: str) -> RepositorySnapshot: ...
    def issue_to_work_unit(self, issue_ref: str) -> dict: ...
    def publish_candidate(self, candidate: CandidateChange) -> CandidateRef: ...
    def observe_candidate(self, candidate_ref: CandidateRef) -> CandidateState: ...

10.4 Secret resolver

class SecretResolver(Protocol):
    def resolve(self, ref: str) -> SecretValue: ...

Initial accepted references:

Future optional resolvers can support Vault/1Password/cloud secret managers without changing connection records.

11. Configuration contract

Configuration must contain references to secrets, never secret values.

Proposed project-local configuration:

api_version: idkmesh.io/v1alpha1
kind: ConnectorProfile

project:
  repository: MSKazemi/idkmesh

connections:
  - id: github-main
    kind: scm
    driver: github
    settings:
      repository: MSKazemi/idkmesh

  - id: jules-main
    kind: agent
    driver: jules
    auth:
      secret_ref: env:JULES_API_KEY
    settings:
      source: sources/github/MSKazemi/idkmesh
      starting_branch: main
      require_plan_approval: true
    policy:
      task_classes: [coder]
      max_concurrency: 1
      allowed_risk: [low]

  - id: gemini-openai
    kind: model
    driver: openai-compatible
    auth:
      secret_ref: env:GEMINI_API_KEY
    settings:
      base_url: https://generativelanguage.googleapis.com/v1beta/openai/
      model: <configured-model>
    policy:
      external_processing: true
      project_spend_usd_max: 0

  - id: ollama-local
    kind: model
    driver: openai-compatible
    settings:
      base_url: http://127.0.0.1:11434/v1
      model: <allowlisted-local-model>
    policy:
      external_processing: false
      project_spend_usd_max: 0

This is a proposed control-plane profile, not a replacement for WorkUnit, compute-offer, or Free Resource Mesh schemas.

12. Connection lifecycle

Every connection has explicit state:

configured
 -> probe_pending
 -> healthy | degraded | unavailable
 -> disabled

A connection probe records:

The dispatcher uses only healthy/eligible connections.

13. Proposed backend API

The first HTTP API should be thin over the same Python control-plane services used by the CLI.

Service

Projects

Connections

Routing

Work

Results

GitHub ingress

The webhook endpoint must verify GitHub signatures and event replay/idempotency before touching project state.

14. Run state machine

Use an explicit state model:

created
 -> admitted
 -> dispatched
 -> waiting_for_agent
 -> candidate_ready
 -> verification_pending
 -> verified | verification_failed
 -> awaiting_human_decision
 -> integrated | rejected | cancelled | failed

Important:

15. GitHub-native control surface

GitHub remains the first public project UI.

Recommended labels:

idkmesh:ready
idkmesh:auto
agent:jules
agent:openhands
agent:local
agent:research
risk:low
risk:medium
risk:high
needs-human-review

Rules:

16. Routing policy

Routing should begin deterministic and explainable.

Eligibility example:

eligible(connection, work_unit) =
    connection.healthy
AND connection.supports(task_class)
AND work_unit.risk in connection.allowed_risk
AND data_egress_policy_allows(connection)
AND cost_policy_allows(connection)
AND concurrency_available(connection)
AND required_capabilities_subset(connection.capabilities)
AND secret_requirements_satisfied
AND no_authority_conflict

Ranking can later use measured evidence such as:

Do not optimize on raw model confidence or number of commits.

17. GitHub App model

Long term, the easiest hosted setup is an IDKMesh GitHub App.

Minimum principle:

During bootstrap, a local/Actions token can be used through environment injection, but the product target should be GitHub App installation tokens with least privilege and short lifetime.

18. Credentials and secrets

Hard rules:

  1. Never store raw API keys in tracked config, WorkUnit, ResultManifest, logs, issue bodies, PR bodies, or run artifacts.
  2. Connection records store only secret_ref.
  3. Resolve the secret only in the control plane or agent runtime that needs it.
  4. Do not pass a provider key into an unrelated worker sandbox.
  5. Redact headers/env values from logs.
  6. Treat external provider responses as untrusted data.
  7. Add secret-provider plugins later instead of creating a home-grown vault.

Bootstrap:

local development -> environment variables
GitHub Actions     -> repository/environment secrets
hosted control     -> dedicated secret manager via SecretResolver

19. Persistence

Start small.

Bootstrap persistence

Use:

SQLite is available in the Python standard library and avoids requiring a database service during the first product loop.

Scale-out persistence

Only after the local/hosted control plane proves useful:

20. Observability contract

Every run should retain:

Never log secret values.

21. Failure taxonomy

Connector errors should be classified, not flattened into “agent failed.”

Minimum classes:

This supports routing/retry decisions without letting a retry mutate authority.

22. User-facing CLI target

The CLI should eventually make connection setup understandable without requiring architecture knowledge.

Example target:

idkmesh project add MSKazemi/idkmesh

idkmesh connect agent jules \
  --secret-ref env:JULES_API_KEY \
  --source sources/github/MSKazemi/idkmesh

idkmesh connect model gemini \
  --driver openai-compatible \
  --base-url https://generativelanguage.googleapis.com/v1beta/openai/ \
  --secret-ref env:GEMINI_API_KEY \
  --model <model>

idkmesh connect model ollama \
  --driver openai-compatible \
  --base-url http://127.0.0.1:11434/v1 \
  --model <model>

idkmesh connections probe
idkmesh doctor

idkmesh work preview --issue 123
idkmesh run --issue 123 --agent jules
idkmesh run status <run-id>

CLI and HTTP API must call the same service layer.

23. Web UI target

A dashboard is useful only after the connector kernel works.

Minimum screens:

  1. Projects — repository and policy.
  2. Connections — add/test/enable/disable agent/model connections.
  3. Runs — status, source SHA, agent, result, verification.
  4. Queue — ready/blocked work and routing explanation.
  5. Evidence — candidate vs verification vs human decision.
  6. Usage — quotas/cost where available, without making spend telemetry authority.

Do not block the first self-hosting milestone on a large frontend.

24. Self-hosting boundary

IDKMesh should become its own first user only after the connector kernel is independently usable.

Self-hosting means:

IDKMesh issue
 -> IDKMesh Connector Control Plane
 -> external/local agent
 -> candidate PR
 -> existing IDKMesh CI/verifier
 -> human merge decision

It does not mean:

IDKMesh generates task
 -> IDKMesh selects its own output
 -> IDKMesh approves itself
 -> IDKMesh merges itself

Self-hosting tests orchestration and evidence. It must preserve the external integration boundary.

25. New-application bootstrap

After self-hosting evidence exists, IDKMesh should support a second repository.

Target:

product brief / requirements
 -> project manifest
 -> GitHub backlog
 -> bounded WorkUnits
 -> heterogeneous agent attempts
 -> tests / verification
 -> PRs
 -> human product decisions
 -> releases

A new application should use the same connector profile mechanism. No code path should be special-cased for the idkmesh repository.

Proposed future command:

idkmesh project init --repo OWNER/NEW_APP --profile profiles/default-safe.yaml

This should create/configure project metadata and suggested GitHub control surfaces. It should not silently grant workers merge authority.

26. Compatibility with current repository architecture

This control plane extends, rather than replaces:

Layer ownership:

Free Resource Mesh         -> what external capacity might exist
Connector Control Plane    -> how a configured provider/agent is contacted
Compute Offer/Router       -> what concrete runtime resource may execute
WorkerAdapter              -> coordinator-facing execution semantics
Verification               -> whether candidate evidence satisfies checks
GitHub/human governance    -> whether canonical state changes

Do not create a second WorkUnit, a second verification contract, or a second scheduler.

27. Initial connector matrix

Connection Mode First milestone Notes
Jules REST API P0 First production remote-agent connector; plan approval on by default.
OpenHands GitHub-native P1 Observe label/comment-triggered work and normalize resulting PR.
goose local CLI/API P1 Run inside bounded sandbox/node; can use local or remote models.
Gemini CLI local CLI P1 Headless auth must use supported non-interactive credentials.
mini-SWE-agent local CLI P2 Useful heterogeneous software-engineering worker.
A2A protocol existing/extend Keep canonical semantic mapping.
MCP worker protocol/tool existing/extend Use only where task semantics survive.
Gemini model OpenAI-compatible P0 One common model-driver path.
Ollama model OpenAI-compatible/local P0 Zero-project-spend local inference.
vLLM model OpenAI-compatible/local P1 Useful for self-hosted GPU nodes.
OpenRouter OpenAI-compatible P1 Broad provider access; cost/data policy still applies.
LiteLLM OpenAI-compatible gateway P1 optional External gateway, not core dependency.
OpenAI/Anthropic native native later P2 Add only for required native features.

28. Security invariants

No connector is considered complete unless it preserves:

29. Product success criteria

The Connector Control Plane is ready for the next stage when a newcomer can:

  1. install the relevant IDKMesh product extra;
  2. connect one GitHub repository;
  3. connect Jules or one local agent;
  4. connect/test one model provider where required;
  5. preview an issue as a WorkUnit;
  6. dispatch one low-risk task;
  7. see the candidate and its provenance;
  8. see independent verification separately;
  9. make the integration decision manually;
  10. replay/inspect the run without provider-specific knowledge.

That is the bridge from research infrastructure to a usable development platform.

This site is open source. Improve this page.