feat(example): add an Agent workbench with native self-hosted Sessions

CONTRIBUTING.md

@@ -42,6 +42,55 @@ business assets, the Parsar product Web, product API and product migrations rema
 in Parsar. Do not import `server/`, `apps/parsar/`, product CLI/plugin packages or
 their deployment stack.
 
+`example/parsar/` is an optional, independently started Agent workbench,
+authorized to reuse the product UI and maintain a small product-owned SQLite database.
+Named Provider groups and their models, anonymous HTTP MCP configurations, runtime profiles and reusable Agents
+belong to that database. An Agent contains model, harness, instructions, Skills
+and MCP bindings; it excludes the runtime. Starting a Session selects a runtime
+and passes an inline Agent/configuration snapshot to the public Core API. One
+Agent may have many independent Sessions. Existing Sessions keep their original
+configuration and history. Hosted Sessions have independent workspaces; native
+Sessions use the selected host directory, so selecting the same path shares files.
+There is no task layer or automatic workspace coordination.
+Providers are explicit catalog groups without default groups. Each model references
+one Provider. The example can fetch an OpenAI-shaped model list from a user-entered
+Provider Base URL using that Provider's key, then save checked/custom models and
+the Provider in one SQLite transaction. Editing reads the Provider revision and
+its models as one snapshot; individual model changes advance the owning Provider
+revision. Provider keys stay in the local restricted
+SQLite file and are omitted from every browser response. Discovery uses only the
+Provider credential, never the Core Project key, and never follows redirects.
+Catalog import does not reconfigure deployment routing. Self-hosted Session creation
+uses the selected Provider's URL/key in the explicit Session model-provider bundle;
+Core freezes and delivers it. Pending requests are never serialized to browsers.
+Core owns Skills and all execution/history state. SQLite stores Session references
+and freezes pending creation requests with stable idempotency keys for retry;
+confirmed requests are removed from local storage. Earlier example templates and
+instances migrate to Agent configurations, never to fabricated Sessions.
+Hosted HTTP MCP bindings become inline environment Plugins; none uses service-origin
+MCP. Unsupported harness/runtime combinations fail before execution. The example
+calls only public `/v1` APIs, using `OpenAIAgentsClient` for browser resource calls
+and a small server adapter for Session creation. Its Project key stays server-side.
+Session output uses the public SSE event stream through a non-buffering proxy;
+durable history reads reconcile completion and recover missed events. Browser
+disconnection aborts the upstream stream, never the running Session. Send latency
+measurements are browser-local observations (request return and first nonempty
+text delta), not inferred Core execution timings.
+Product resources use `/app/` and never become Core API or database conventions.
+The example supports native self-hosted runtime profiles with a platform and existing
+absolute workspace/capability paths. Create an empty Session first, issue its credential
+in Core Web, then run the displayed native install/start command. The example never
+holds a Core key or issues machine credentials; Core's public Environment status gates
+message sending. Core-only credential issuance remains in the operator console.
+Native Skills come from local capability directories: managed Skill references are
+rejected explicitly rather than ignored. Bound service-origin MCP is also rejected
+for self-hosted Sessions; use local Plugin capability directories. This example supports Codex and Claude Code on user machines; MiniMax Code's
+required token-limit configuration is not exposed here. No scheduler or user permissions
+are included. SQLite uses
+Node's built-in module (Node 22.13+), lives outside the checkout, and is isolated by
+Core origin and Project key fingerprint. The example is excluded from Core
+distributions and cannot become a service dependency.
+
 Preserve copied runtime and protocol behavior. Existing Go import paths remain unchanged and do not require fetching the original
 repository. Installed commands and environment settings use the OpenAgentCore names
 documented below. The source snapshot and per-file
@@ -300,6 +349,10 @@ and unrelated Web changes do not. Manual native validation remains available.
 Superseded native runs on the same ref are cancelled. Workflow syntax validation
 and release qualification remain separate checks.
 
+`make check-example` validates the optional application example with TypeScript,
+proxy/product-persistence tests, a build and fixture browser acceptance; it also runs in
+`make check`. Its synthetic responses are not live model qualification.
+
 Run `make check` before completion. The standalone gate includes all daemon/shared
 Go tests, Core contract/client/service tests, Core Web and TypeScript client
 checks (including fixture-only Playwright acceptance), a real dedicated PostgreSQL test

Makefile

@@ -8,7 +8,7 @@ SWAG_VERSION ?= v1.16.4
 help:
 	@printf '%s\n' 'make build-agents-api  Build standalone Core commands' 'make build-daemon      Build the execution daemon' 'make check             Run Core, persistence and runtime checks' 'See README.md for runtime prerequisites and deployment.'
 
-check: check-docs check-names check-distribution check-database check-sqlc check-go check-microsandbox-provider check-agents-api check-claude-sdk check-web check-mcode-harness
+check: check-docs check-names check-distribution check-database check-sqlc check-go check-microsandbox-provider check-agents-api check-claude-sdk check-web check-example check-mcode-harness
 	@printf 'OpenAgentCore checks passed.\n'
 
 .PHONY: check-names
@@ -90,6 +90,13 @@ check-web: node-deps
 build-claude-sdk-runtime:
 	./scripts/build-claude-sdk-runtime.sh
 
+.PHONY: check-example
+check-example: node-deps
+	pnpm --filter @oac/parsar-example typecheck
+	pnpm --filter @oac/parsar-example test
+	pnpm --filter @oac/parsar-example build
+	pnpm --filter @oac/parsar-example test:e2e
+
 check-mcode-harness:
 	node --test packages/mcode-harness/*.test.mjs
 	@for script in packages/mcode-harness/*.mjs; do node --check "$$script"; done

README.md

@@ -57,6 +57,10 @@ and native harness differences.
 
 ## Documentation
 
+For a complete application example using the Parsar product UI, see
+[`example/parsar`](example/parsar/README.md): model, Skill, MCP and runtime management, reusable Agents, and independent
+Sessions backed by the public API.
+
 | Start here | Purpose |
 | --- | --- |
 | [Documentation index](docs/getting-started/README.md) | Installation, usage and administration reading paths |

example/README.md

@@ -0,0 +1,4 @@
+# Application examples
+
+[Parsar](parsar/README.md) is a small Agent workbench using OpenAgentCore public
+resources. Reuse Agent configurations to start independent runtime-bound Sessions.

example/parsar/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MiniMax-AI-Dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

example/parsar/MOTION-PRIMITIVES-LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 ibelick
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+app/page.tsx

example/parsar/README.md

@@ -0,0 +1,164 @@
+# Parsar Agent workbench
+
+A small product application on OpenAgentCore, using Parsar UI. Manage models,
+Skills, HTTP MCP services and runtime configurations; compose reusable Agent
+configurations and start independent Sessions. Continue the same Session to keep
+its history and live workspace. There is no task layer or shared workspace.
+
+## Run
+
+Use Node 22.13+ (for built-in SQLite) and pnpm 10.30.3. Configure
+[Core](../../docs/getting-started/install.md), a deployment model/provider, and a
+Project API key. Store secrets in a private environment file outside the checkout:
+
+```sh
+export OAC_EXAMPLE_CORE_URL='http://127.0.0.1:8091'
+export OAC_EXAMPLE_PROJECT_KEY='<project-api-key>'
+pnpm install --frozen-lockfile
+pnpm --filter @oac/parsar-example dev
+```
+
+Open http://127.0.0.1:18180. The Core URL is an origin without `/v1`;
+remote origins require HTTPS. `OAC_EXAMPLE_PORT` changes the local port.
+For a built version, run `pnpm --filter @oac/parsar-example build` and then
+`pnpm --filter @oac/parsar-example start`.
+
+## Main flow
+
+1. **Models:** enter a Provider name, Base URL and API key, then fetch its
+   `GET /v1/models` list. Select models with checkboxes or add custom model IDs,
+   then save the Provider and selected models together. The dialog shows discovered
+   and selected counts. For manual entry, skip discovery. No default group is
+   created. Keys are stored in the local restricted SQLite file and never returned
+   to the browser; leaving the key blank while editing preserves it. Discovery
+   sends only that Provider's key and does not follow redirects. The list expects
+   the OpenAI-shaped `data: [{id: "..."}]` response. Discovery failures leave manual
+   entry available. This imports the catalog only: Core still owns execution
+   connections for hosted/text-only Sessions. Self-hosted Sessions instead pass
+   this Provider URL/key explicitly to Core, using the selected harness protocol.
+2. **Skills:** create a SKILL.md resource or upload a ZIP. Inspect versions,
+   upload a new version, and choose the default. Core validates and stores bundles.
+3. **MCP:** save anonymous HTTPS endpoints and bind them to Agents. Hosted
+   Sessions install an inline environment Plugin; text-only Sessions use Core's
+   service-origin MCP. Hosted HTTP MCP supports Claude Code and Codex, not MiniMax
+   Code. Authentication, Vault management and OAuth setup are not included.
+4. **Runtimes:** choose a Core-managed sandbox, text-only environment, or user
+   machine. User machines select Linux/macOS/Windows and an existing absolute
+   workspace path, plus an optional local capability directory. Each Session gets
+   its own daemon installation and credential; choosing the same workspace path
+   shares the host's files, so use distinct paths for isolated work.
+   These are placement configurations, not online machine identities. Machine
+   enrollment, fixed-node routing and self-hosted registration are omitted.
+5. **Agents:** combine a model, harness, instructions, Skills and MCP services.
+   Create, copy and edit configurations without allocating a runtime.
+6. **Sessions:** open an Agent, choose a runtime and send the first message.
+   Read streaming replies and tool activity, continue the conversation, cancel a running turn and reopen
+   history. Each hosted Session gets its own workspace; text-only has no workspace.
+
+Agent edits and catalog updates apply to future Sessions. Core freezes existing
+Session configuration, including resolved Skill versions. Continuing a Session
+retains history and its workspace while the sandbox exists; archiving/replacing a
+sandbox is not a persistence guarantee. Saving configuration alone does not verify
+model availability or MCP connectivity. Skills require a hosted runtime.
+
+## Ownership and storage
+
+The loopback Node server has two small responsibilities: a fixed allowlist proxy
+for public Core resources, and `/app/` CRUD for product-owned configuration. One
+SQLite table stores typed JSON records. There is no ORM, background scheduler,
+execution database or imported Parsar backend.
+
+SQLite files live in `~/.oac/data/parsar-example/`. Set the absolute
+`OAC_EXAMPLE_DATA_DIR` to relocate them. A hash of the Core origin and Project key
+selects the file; changing either selects a different local catalog. Back up the
+SQLite file with the server stopped. No key is stored in it. Builds and caches
+use `${OAC_DEV_HOME:-$HOME/.oac}`.
+
+Use one server process and a dedicated Project for this local single-user example.
+The server rejects cross-origin writes and keeps the Project key out of browser
+responses. Session creation freezes a pending request in SQLite before calling Core, and uses
+the local Session ID as its idempotency key. An uncertain response can be recovered
+from the Agent's Session list, including after a server restart. Successful creation
+leaves only the Core Session reference and local title/Agent/runtime relationship;
+Core owns messages, turns and execution status. The browser consumes public SSE
+text deltas through a non-buffering proxy, reconnects after interruption, and
+reconciles with durable history to avoid duplicate final replies. Each send records
+request-return latency and first nonempty text-delta latency from browser request
+start. These independent observations remain in sessionStorage across reloads;
+missing observations are shown as a dash rather than inferred from history. Definite validation rejection
+removes the pending request so it can be corrected. Use one server process.
+Deleting a local resource is blocked while another local record references it;
+Session deletion/archival is outside this example. Skill deletion is a separate
+explicit Core operation. Earlier templates and instances become Agent configs on
+startup; they are never presented as actual Sessions.
+
+## Validation
+
+```sh
+make check-example
+make check
+```
+
+The example gate runs TypeScript, proxy and SQLite persistence/binding tests,
+a production build and browser acceptance. Install Chrome with
+`pnpm exec playwright install chrome` if necessary. Browser fixtures use
+ports 18180/18181 and isolated SQLite data under `~/.oac/tests/parsar-example/`.
+They verify Provider groups and model selection, live text before durable completion,
+resource management, multiple Sessions, continuation, cancellation, lost-response recovery,
+Skill versions and mobile/help behavior. Synthetic fixtures are not model execution.
+
+The opt-in live browser probe requires an already started example backed by an
+isolated real Project:
+
+```sh
+OAC_EXAMPLE_LIVE_URL=http://127.0.0.1:18180 \
+OAC_EXAMPLE_LIVE_MODEL='<configured-model>' \
+pnpm --filter @oac/parsar-example test:live
+```
+
+It leaves sample resources for inspection and executes the configured model. It
+checks Skill/Plugin installation, same-Session file reuse, and workspace isolation
+between two Sessions. It asks the model to call DeepWiki; inspect the recorded
+tool activity to distinguish a successful call from an attempted call.
+
+## UI provenance
+
+The copied UI primitives, `src/lib/utils.ts`, `src/style.css`
+and `public/*` originate in [Parsar](https://github.com/MiniMax-AI-Dev/parsar)
+revision `90fafede`, under [MIT](LICENSE). The responsive body minimum width and
+application pages are local adaptations. Navigation animation adapts
+[Motion Primitives](https://github.com/ibelick/motion-primitives), with reduced-motion
+support and its [MIT notice](MOTION-PRIMITIVES-LICENSE). Multica's resource and
+Agent organization informs the product flow; no Multica code is copied.
+
+## Connect a user machine
+
+This branch builds on `codex/qualified-release-promotion-20260928` (native daemon
+support). Run a matching Core and daemon version; the older preview Core does not
+qualify this workflow. The optional unified Harness installer PR is not included.
+
+Create a user-machine runtime and start a Session with an Agent using Codex or
+Claude Code. No initial Turn is sent. Open **Connect user machine**, obtain the
+Session's executor credential in Core Web (Session log), save the credential on
+the host as instructed, and run the generated platform-specific install/start
+command. The daemon binary and native harness must already be installed. Windows
+Claude Code also requires Git Bash. The page reads Core's public Environment
+status and enables sending after it reports connected. The example backend does
+not need or accept the administrator Core key.
+
+The selected model Provider needs an HTTPS Base URL and API key. Its protocol is
+Responses for Codex and Anthropic for Claude Code. Core freezes and delivers the
+configuration to the enrolled executor. Local pending creation requests contain
+that configuration but browser Session responses omit the entire pending request.
+
+Self-hosted capability sources are local directories under the current Core API.
+Managed Skill bindings fail explicitly; configure local Skills/Plugins in the
+runtime's capability directory before connecting. Bound HTTP MCP services also
+fail explicitly for self-hosted Sessions; configure them in local Plugins instead. MiniMax Code self-hosted configuration is not
+included in this example because its required token limits are not exposed.
+
+The daemon runs with the starting user's permissions and adds no sandbox. Runtime
+home is separate per Session; stopping it preserves local files. Credential
+rotation and revocation remain Core console operations. Native install commands
+are for fresh installations; restart an existing one with the same Runtime home
+and `start`, without rerunning `install`.

example/parsar/index.html

@@ -0,0 +1,10 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <link rel="icon" href="/favicon.png" />
+    <title>Parsar · OpenAgentCore</title>
+  </head>
+  <body><div id="root"></div><script type="module" src="/src/main.tsx"></script></body>
+</html>