Ocor

Name: Ocor
Rating: 3.5 (1 reviews)
Author: anyech

By anyech 👁 37 views ▲ 0 votes

Native OpenClaw plugin for attempt-aware Kubernetes Jobs, with a disposable k3s OCOR lifecycle demo.

GitHub

Install

openclaw plugins install git:github.com/anyech/[email protected]

Configuration Example

{
  "namespace": "ocor",
  "profiles": {
    "daily-report": {
      "image": "ghcr.io/example/report@sha256:REPLACE_WITH_REAL_DIGEST",
      "command": ["/app/report", "--once"],
      "timeoutSeconds": 120
    }
  }
}

README

# OpenClaw OCOR

**The missing seam between an AI agent's tool call and an asynchronous executor's final truth.**

OpenClaw can ask Kubernetes to start work. Kubernetes can run and report a Job. The hard part in between is deciding which *attempt* owns a late completion after cancellation, retry, timeout, or controller restart. Without that binding, stale evidence can silently overwrite the current result.

`openclaw-ocor` is a native TypeScript OpenClaw plugin that makes that seam usable: the agent selects a named profile; the plugin assigns an `attempt_id`, persists it on Kubernetes resources, and accepts or quarantines evidence by attempt. No database, broker, Python, or `kubectl` is required at runtime.

![Where OCOR sits](docs/diagrams/01-the-seam.svg)

## Five-minute proof

Prerequisites: Docker, Node.js 22+, and OpenClaw 2026.5.17+.

```bash
openclaw plugins install git:github.com/anyech/[email protected]
openclaw ocor demo --ephemeral
```

The demo starts a disposable k3s container, proves a successful Job, creates a real cancellation race, recreates the controller, quarantines attempt A's late completion, verifies attempt B remains successful, deletes every managed Job/Pod, and removes the container.

Expected final lines:

```text
cancelled-… => late_succeeded_quarantined
replacement-… => succeeded
cleanup: 0 managed resources remain
```

![Five-minute sequence](docs/diagrams/02-five-minute-path.svg)

Already have Kubernetes? Use your current context:

```bash
openclaw ocor demo
# or:
openclaw ocor demo --kubeconfig /path/to/kubeconfig --context my-context
```

## Use it from an agent

The plugin registers one tool:

```text
ocor_job(action=submit|inspect|cancel, profile=..., attempt_id=...)
```

The model may choose a configured `profile`; it cannot provide an arbitrary container image or command. Built-ins are `hello` and `cancel-race`.

Add your own profile under `plugins.entries.openclaw-ocor.config`:

```json
{
  "namespace": "ocor",
  "profiles": {
    "daily-report": {
      "image": "ghcr.io/example/report@sha256:REPLACE_WITH_REAL_DIGEST",
      "command": ["/app/report", "--once"],
      "timeoutSeconds": 120
    }
  }
}
```

Use immutable image digests for real workloads. Config changes follow the normal OpenClaw plugin lifecycle; the demo itself does not edit config or restart the Gateway.

## What it is—and is not

| Project / framework | Relationship to OpenClaw OCOR |
|---|---|
| **OpenClaw** | Hosts the agent, tool, config, and CLI. This repository is the native plugin. |
| **Kubernetes / k3s** | Executes Jobs and persists resource state. OCOR adds agent-attempt meaning to those primitives. k3s is the disposable flagship demo; any conforming cluster should work. |
| **OCOR conformance** | The neutral executable contract. This plugin ships a hidden JSONL adapter and passes `ocor-conformance` v0.1. |
| **MCP / ordinary tool wrappers** | Move tool requests and responses. They do not, by themselves, bind late executor evidence to an attempt lineage. OCOR can sit behind an MCP tool as well. |
| **LangGraph / agent workflow frameworks** | Can express retries and graphs. OCOR focuses narrowly on the agent-to-executor lifecycle boundary and can be used inside such a node. |
| **Temporal / Argo Workflows** | Rich durable workflow systems. Use them when you need histories, DAGs, timers, or broad orchestration. An OCOR adapter can target them; this plugin avoids requiring one for a single Kubernetes Job seam. |

OCOR does **not** replace a scheduler, workflow engine, policy engine, authorization layer, or Kubernetes. It is the small executable contract at their boundary.

![Attempt lineage](docs/diagrams/03-attempt-lineage.svg)

## Why the state survives a controller restart

Correctness does not depend on process memory. Each Job and Pod carries:

- a full `ocor.dev/attempt-id` annotation;
- a bounded hash label used for selection;
- the named profile and profile digest;
- cancellation acknowledgement when applicable.

Reconciliation rebuilds the result from Kubernetes. A successful Pod with a cancelled attempt id becomes `late_succeeded_quarantined`; it cannot become the replacement attempt's result.

## Develop and verify

```bash
npm ci
npm run check

# Neutral black-box contract (from a sibling ocor-conformance checkout)
../ocor-conformance/.venv/bin/ocor-conformance \
  --adapter "node $(pwd)/dist/conformance-adapter.js"

# Real Kubernetes race in disposable k3s
node dist/standalone-cli.js demo --ephemeral
```

CI runs unit/build, neutral conformance, isolated OpenClaw plugin loading, and disposable k3s integration.

## Alpha boundaries

- One Kubernetes Job per attempt; no DAGs.
- Named profiles are configuration, not model-supplied commands.
- Bounded terminal logs only; no streaming UI yet.
- The `cancel-race` orphan behavior exists to make late evidence observable in the demo. Normal profiles use Kubernetes deletion.
- Public API and config may change before `v0.1.0`.

## License

Apache-2.0. See [LICENSE](LICENSE).

tools