feat(appkit): add the omnigent plugin (1/4)

Embeds Omnigent, the open-source agent meta-harness, in an AppKit app:
Claude Agent SDK, Pi and OpenAI Agents SDK sessions, with model calls
going through Unity AI Gateway as the app's service principal.

- One Omnigent server on loopback in header-auth mode (random header
  name) and one host per active user, supervised with restart backoff
  and idle shutdown; a parent-death watchdog so no child outlives Node.
- A loopback model gateway: children hold a placeholder token, the
  gateway forwards only model-serving paths with the real token.
- Harnesses are offered the UC system.ai models whose API types they
  speak, plus the workspace's chat serving endpoints.
- Session routes under /api/omnigent, scoped to the signed-in user.
- docs/docs/plugins/omnigent.md, extended by the later PRs.

Co-authored-by: Isaac <no-reply@databricks.com>
Signed-off-by: Noah Solomon <noah@databricks.com>

Author: noah-databricks

.gitignore

@@ -22,3 +22,4 @@ internal
 .isaac/
 
 .codex-tmp/
+__pycache__/

docs/docs/plugins/omnigent.md

@@ -0,0 +1,69 @@
+# Omnigent
+
+<!-- AUTO-GENERATED: stability-banner-start -->
+:::warning Beta plugin
+This plugin is currently **beta**. APIs may change between minor releases. Import from `@databricks/appkit/beta`. See [Plugin Stability Tiers](./stability.md).
+:::
+<!-- AUTO-GENERATED: stability-banner-end -->
+
+The `omnigent` plugin embeds [Omnigent](https://github.com/omnigent-ai/omnigent), the open-source agent meta-harness, in a Databricks AppKit app. Your users get Claude Agent SDK, Pi and OpenAI Agents SDK sessions inside the app, with model calls going through Unity AI Gateway as the app's service principal.
+
+Omnigent owns the agent loop: sessions, history, approvals. The plugin runs it safely inside a Databricks App. Use the [`agents`](./agents.md) plugin when you want AppKit to own the loop against one serving endpoint. Use `omnigent` when you want the harnesses themselves.
+
+## Install
+
+```ts
+import { createApp, server } from "@databricks/appkit";
+import { omnigent } from "@databricks/appkit/beta";
+
+await createApp({
+  plugins: [
+    server(),
+    omnigent({ instructions: "You help the team explore order data." }),
+  ],
+});
+```
+
+The app also needs:
+
+- **Python.** Add a `pyproject.toml` with `requires-python = ">=3.12,<3.13"` and `omnigent[databricks]`, plus a `uv.lock`. Databricks Apps then builds a Python 3.12 venv next to `npm install`. A plain `requirements.txt` gets Python 3.11, which Omnigent does not support. The lockfile must reference public PyPI.
+- **Harness CLIs.** Add them to your `package.json`, so you pin their versions: `@anthropic-ai/claude-code` and `@earendil-works/pi-coding-agent`. The plugin only offers harnesses whose CLI is installed. The Claude Agent SDK's bundled CLI is too old for current Claude models, so add `@anthropic-ai/claude-code` even though the SDK ships one.
+- **Start with `node`.** In `app.yaml`, use `command: ["node", "server.js"]`, not `npm run start`. npm does not pass SIGTERM on, so the plugin never gets to stop its child processes. As a backstop, each child also exits when Node does, so a redeploy still succeeds.
+
+## Configuration
+
+| Option | Default | |
+|---|---|---|
+| `instructions` | a generic assistant prompt | System instructions for every session |
+| `harnesses` | `claude-sdk`, `pi`, `openai-agents` | Harnesses users may pick |
+| `defaultHarness`, `defaultModel` | first available | |
+| `runtime.python` | `./.venv/bin/python` | |
+| `runtime.home` | `$TMPDIR/appkit-omnigent` | The plugin's state directory |
+| `runtime.hostIdleMs` | 30 min | Stop a user's Omnigent host after this long idle |
+
+Each harness is offered the Unity AI Gateway `system.ai` models whose API it speaks: Claude Agent SDK the Anthropic Messages API, Pi the Codex Responses API, OpenAI Agents SDK the OpenAI Responses API.
+
+## Routes
+
+All routes are under `/api/omnigent` and scoped to the signed-in user.
+
+| Route | |
+|---|---|
+| `GET /harnesses` | Harnesses available to the user, each with the gateway models it can drive |
+| `GET /sessions`, `POST /sessions` | List, create (`harness`, `model`, `message`, `title`) |
+| `GET /sessions/:id`, `DELETE /sessions/:id` | Snapshot (items, status), delete |
+| `POST /sessions/:id/messages` | `{ "text": "..." }` |
+| `GET /sessions/:id/stream` | Server-sent events (Omnigent's session stream, which replays from `Last-Event-ID`) |
+| `POST /sessions/:id/interrupt` | Stop the current turn |
+| `GET /status` | Runtime health: hosts, gateway counters |
+
+## How it works
+
+- **One Omnigent server, one host per user.** The server listens on loopback in Omnigent's header-auth mode, under a random header name only the plugin knows. Each active user gets their own host process, registered as that user; Omnigent only runs a session on its owner's host. An idle host stops after `runtime.hostIdleMs`.
+- **No credential in any child process.** The harnesses' Databricks profile points at a model gateway inside the plugin, on loopback, with a placeholder token. The gateway forwards only model-serving paths to the workspace and adds the service principal's token. Every other path returns 403.
+
+## Limits
+
+- **Sessions live in the container.** Omnigent keeps them in SQLite under the plugin's state directory, so they survive a process restart but not a redeploy.
+- **Only gateway harnesses.** Harnesses that sign in with their vendor (Cursor, Copilot, Gemini and others) bypass Unity AI Gateway, so they are not offered. Native terminal harnesses (`claude-native`, `pi-native`) are not offered yet: they need tmux and a terminal client.
+- **Shared gateway limits.** All users' model traffic uses the service principal's gateway limits.

packages/appkit/src/plugins/beta-exports.generated.ts

@@ -0,0 +1,64 @@
+import { gzipSync } from "node:zlib";
+
+interface BundleSpec {
+  name: string;
+  description?: string;
+  harness: string;
+  model: string;
+  /** Databricks profile the harness uses for model calls. */
+  profile: string;
+  instructions: string;
+}
+
+/**
+ * An Omnigent agent bundle: `config.yaml` (the agent spec) and `AGENTS.md`
+ * (the instructions), as a tar.gz. The YAML is written as JSON, which is
+ * valid YAML.
+ */
+export function buildBundle(spec: BundleSpec): Buffer {
+  const config = {
+    spec_version: 1,
+    name: spec.name,
+    description: spec.description ?? spec.name,
+    executor: {
+      type: "omnigent",
+      model: spec.model,
+      profile: spec.profile,
+      config: { harness: spec.harness },
+      auth: { type: "databricks", profile: spec.profile },
+    },
+    instructions: "AGENTS.md",
+  };
+  const files: Record<string, string> = {
+    "config.yaml": `${JSON.stringify(config, null, 2)}\n`,
+    "AGENTS.md": spec.instructions,
+  };
+  return gzipSync(tar(files));
+}
+
+/** Minimal ustar writer: regular files only, names under 100 bytes. */
+function tar(files: Record<string, string | Buffer>): Buffer {
+  const blocks: Buffer[] = [];
+  const mtime = Math.floor(Date.now() / 1000);
+  for (const [name, content] of Object.entries(files)) {
+    if (Buffer.byteLength(name) >= 100)
+      throw new Error(`tar: name too long: ${name}`);
+    const data = Buffer.isBuffer(content) ? content : Buffer.from(content);
+    const header = Buffer.alloc(512);
+    header.write(name, 0, 100);
+    header.write("0000644\0", 100);
+    header.write("0000000\0", 108);
+    header.write("0000000\0", 116);
+    header.write(`${data.length.toString(8).padStart(11, "0")}\0`, 124);
+    header.write(`${mtime.toString(8).padStart(11, "0")}\0`, 136);
+    header.write("        ", 148); // checksum placeholder
+    header.write("0", 156);
+    header.write("ustar\u000000", 257);
+    let sum = 0;
+    for (const b of header) sum += b;
+    header.write(`${sum.toString(8).padStart(6, "0")}\0 `, 148);
+    blocks.push(header, data, Buffer.alloc((512 - (data.length % 512)) % 512));
+  }
+  blocks.push(Buffer.alloc(1024));
+  return Buffer.concat(blocks);
+}

packages/appkit/src/plugins/omnigent/bundle.ts

@@ -0,0 +1,83 @@
+import type { OmnigentHarness } from "./types";
+
+interface HarnessInfo {
+  label: string;
+  /**
+   * Unity AI Gateway API types it calls (a UC model service's
+   * `supported_api_types`); a model must support one of them.
+   */
+  apis: string[];
+  /** Default models, best first, when the workspace has them. */
+  preferred: string[];
+}
+
+/**
+ * Harnesses whose model calls Omnigent routes through a Databricks profile
+ * (`AuthModel.OMNIGENT_CREDENTIAL`), so they go through Unity AI Gateway.
+ * The other harnesses Omnigent supports sign in with their vendor, so they
+ * are not offered.
+ */
+const GATEWAY_HARNESSES: Readonly<Record<string, HarnessInfo>> = {
+  "claude-sdk": {
+    label: "Claude Agent SDK",
+    apis: ["anthropic/v1/messages"],
+    preferred: ["system.ai.claude-sonnet-5", "system.ai.claude-opus-5-5"],
+  },
+  pi: {
+    label: "Pi",
+    // Pi reaches Databricks models through the Codex responses API; on the
+    // chat-completions path Gemini fails with an empty 400 (tested).
+    apis: ["codex/v1/responses"],
+    preferred: ["system.ai.gpt-5-5"],
+  },
+  "openai-agents": {
+    label: "OpenAI Agents SDK",
+    apis: ["openai/v1/responses"],
+    preferred: ["system.ai.gpt-5-5"],
+  },
+};
+
+export const DEFAULT_HARNESSES = Object.keys(GATEWAY_HARNESSES);
+
+/** A Unity AI Gateway model, e.g. `system.ai.claude-sonnet-5`. */
+export interface GatewayModel {
+  name: string;
+  /** The model service's `supported_api_types`. */
+  apiTypes: string[];
+}
+
+export interface HarnessOffer extends OmnigentHarness {
+  models: string[];
+  defaultModel?: string;
+}
+
+/**
+ * What a user can pick: the allowed gateway harnesses their host reports as
+ * usable, each with the models whose API it speaks.
+ */
+export function offerHarnesses(opts: {
+  allowed: string[];
+  configured: Record<string, boolean | string>;
+  models: GatewayModel[];
+}): HarnessOffer[] {
+  const out: HarnessOffer[] = [];
+  for (const id of opts.allowed) {
+    const info = GATEWAY_HARNESSES[id];
+    const ready = opts.configured[id];
+    if (!info) continue;
+    // "needs-auth" is advisory for gateway harnesses: their auth comes from the profile.
+    if (ready === undefined || ready === false || ready === "binary-missing")
+      continue;
+    const models = opts.models
+      .filter((m) => m.apiTypes.some((t) => info.apis.includes(t)))
+      .map((m) => m.name);
+    out.push({
+      id,
+      label: info.label,
+      ready,
+      models,
+      defaultModel: info.preferred.find((m) => models.includes(m)) ?? models[0],
+    });
+  }
+  return out;
+}

packages/appkit/src/plugins/omnigent/harnesses.ts

@@ -0,0 +1,2 @@
+export * from "./omnigent";
+export * from "./types";

packages/appkit/src/plugins/omnigent/index.ts

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://databricks.github.io/appkit/schemas/plugin-manifest.schema.json",
+  "name": "omnigent",
+  "displayName": "Omnigent Plugin",
+  "description": "Embedded Omnigent agent runtime: Claude Agent SDK, Pi and OpenAI Agents SDK harnesses through Unity AI Gateway",
+  "stability": "beta",
+  "resources": {
+    "required": [],
+    "optional": []
+  },
+  "scaffolding": {
+    "rules": {
+      "must": [
+        "Add pyproject.toml (python >=3.12,<3.13) with omnigent[databricks] and a uv.lock that uses public PyPI",
+        "Add harness CLIs to package.json: @anthropic-ai/claude-code, @earendil-works/pi-coding-agent",
+        "Start the app with node, not npm run, so SIGTERM reaches the plugin and it can stop its child processes"
+      ]
+    }
+  },
+  "config": {
+    "schema": {
+      "type": "object",
+      "properties": {
+        "instructions": {
+          "type": "string",
+          "description": "System instructions for every session"
+        },
+        "harnesses": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Harnesses users may pick"
+        },
+        "defaultHarness": {
+          "type": "string"
+        },
+        "defaultModel": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}