# Erstan Agent Tools Beta

Temporary Erstan Beta integration for AI coding agents. This repository
packages one broad plugin that connects beta users to Erstan's isolated QA
environment and supplies focused instructions for building, reviewing, and
optimizing Agents and Skills, operating runs, and working with authorized
workspace content.

> **Beta environment:** Data and OAuth grants in this plugin are separate from
> production. Install the production `erstan` plugin when your workspace is
> migrated. This repository will then be retired.

The plugin contains no Erstan API key. Each user signs in to
`https://api-qa.erstan.com/v1/mcp` with OAuth through their AI host. Erstan's
server-side beta access policy remains the access boundary; repository
visibility does not grant product access.

## What is included

- `erstan-agent-builder` — create, revise, validate, test, and publish Agent
  graphs.
- `erstan-agent-optimizer` — retrieve an existing Agent and produce the
  smallest version-correlated optimization proposal.
- `erstan-agent-review` — review Agent definitions and diagnose runs from
  durable evidence.
- `erstan-run-operator` — launch published Agents and safely handle waits,
  approvals, and traces.
- `erstan-skill-manager` — manage complete, versioned Erstan Skill packages.
- `erstan-skill-optimizer` — retrieve a complete workspace Skill package and
  optimize it without losing business rules, files, or action metadata.
- `erstan-work-manager` — work with complete authorized Task properties,
  selectable relations, subtasks, attachments/references, comments,
  participants, reactions, lifecycle, Task-linked runs/approvals, projects,
  documents, native Sheets, folders, and files.

The conceptual `agent:optimize` and `skill:optimize` operations are distributed
as the `$erstan-agent-optimizer` and `$erstan-skill-optimizer` Skills. They are
not npm CLI commands. By default they stop at an evidence-backed local proposal
and validation result; updates, live Agent previews, and publication each
require separate explicit authorization.

### SDK and versioned authoring

`@erstan/sdk` is the separate JavaScript/TypeScript client for developers who
want to keep Agents, complete Skill packages, and prompt files in their own
private repositories. Its examples are optional; this plugin does not install
the SDK or require a particular layout, test runner, or CI workflow. Follow the
SDK's reviewed release instructions rather than assuming an npm release exists.

The packaged Skills check the connected server's live authoring capabilities.
With staged saves supported, saving preserves published content; preview and
publication remain separate, explicitly authorized actions. Run reviews use
the selected immutable Skill snapshots when that evidence is available. Older
servers are not assumed to support staging or exact draft Skill previews.

Hosted MCP schemas come from the connected environment. Packaged instructions
are static: backend or SDK updates do not update them. Beta instructions must
be synced from a reviewed production-plugin ref and released separately.

## Permission model

Erstan is the source of truth for what the connection may access. Users manage
connected apps, workspace scope, allowed tool families, project or team
allowlists, and Erstan-side approval policy in **Settings > Connected apps**.

Initial authorization defaults to the recommended **Build** profile. It includes
**View agents**, **Build agents**, **Run agents**, **Publish agents**, and
the read-only **View runs**, **View work**, **View documents**, and **View
files** permissions. It does not permit task, document, or file writes. Use
**Review** for read-only access. For writes, use **Custom** with the applicable
**Manage work**, **Edit documents**, or **Edit files** permission, or choose
**Full access**. **Manage work** includes Task updates, structured attachments,
and Task-linked run replies/approval decisions. **View work** includes runs and
traces reached through an exact visible Task relationship; those Task paths do
not also require **View runs** or **Run agents**. Retrieving Team-file bytes
still requires **View files**.

Users manage and revoke the connection in **Settings > Connected apps**.
Reducing access takes effect directly. Increasing permissions or changing to a
broader profile requires explicit OAuth reauthorization so a background agent
cannot expand its own grant.

Claude, Codex, ChatGPT, or another MCP host owns the local connection session
and its own confirmation controls. A host may narrow access or require an extra
confirmation, but it cannot grant permissions that Erstan denied. Revoking the
connection in Erstan invalidates it for every host session that uses it.

This two-layer model keeps permissions understandable:

1. Erstan decides the maximum authorized data and actions.
2. The AI host decides whether to invoke an action within that boundary.

## Install in Codex

`erstan-beta@erstan-beta` means `plugin-name@marketplace-name`; it is not an
account ID or secret.

```text
codex plugin marketplace add erstanai/erstan-agent-tools-beta
codex plugin add erstan-beta@erstan-beta
```

Open a new Codex session, use `/plugins` to confirm the installation, connect
the `erstan-beta` MCP server when prompted, and complete browser sign-in. The
plugin uses the remote server configuration in
`plugins/erstan-beta/.mcp.json`.

## Install in Claude Code

```text
claude plugin marketplace add erstanai/erstan-agent-tools-beta
claude plugin install erstan-beta@erstan-beta
```

Run `/reload-plugins`, then `/mcp` to connect `erstan-beta` and complete OAuth.
Claude Code initiates the remote MCP authorization; the plugin does not ask the
user to paste a bearer token or API key.

## Install in Claude Cowork / Desktop

Open **Customize > Plugins > Browse plugins**, select **Add marketplace**, and
enter:

```text
https://github.com/erstanai/erstan-agent-tools-beta
```

Install **Erstan Beta** and complete browser sign-in when prompted. Plugins are
available in Claude Cowork and Claude Code, not the standard Claude Chat
surface.

## Update or remove

Use the host's plugin browser to update, disable, or uninstall Erstan Beta.
Removing the local plugin does not revoke an existing Erstan OAuth grant.
Review or revoke grants in **Settings > Connected apps** in Erstan.

Published versions and checksums are available from [GitHub
Releases](https://github.com/erstanai/erstan-agent-tools-beta/releases).

## ChatGPT and other hosts

This temporary beta repository is not submitted to the universal ChatGPT and
Codex plugin directory. It intentionally does not contain `.app.json`: an
OpenAI app mapping must use a real registered `plugin_asdk_app...` or
`asdk_app_...` identifier assigned during publication. See
[Publishing](docs/PUBLISHING.md) for the distribution boundary.

Other MCP clients can connect directly to:

```text
https://api-qa.erstan.com/v1/mcp
```

The deployed server must expose standards-compliant OAuth discovery and
authorization. There is no static-key fallback in this distribution.

## Verify locally

Requirements: Node.js 20 or later, Python 3, and optionally Claude Code for its
native validator.

```text
npm run verify
python C:/Users/<you>/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py plugins/erstan-beta
python C:/Users/<you>/.codex/skills/.system/skill-creator/scripts/quick_validate.py plugins/erstan-beta/skills/erstan-agent-builder
claude plugin validate .
```

Run the skill validator once for each directory under
`plugins/erstan-beta/skills`. CI runs the repository-owned release verifier; the
native Codex, Skill, and Claude validators remain required release gates because
their availability and schemas are owned by their respective hosts.

## Sync from production

The beta distribution is derived from a reviewed production checkout with an
explicit identity and endpoint transform. Locally, run:

```text
npm run sync:production -- --source ../erstan-agent-tools
```

The command copies the production Skills and assets, aligns plugin metadata,
keeps the distinct `erstan-beta` identity, and rewrites the hosted MCP endpoint
to `https://api-qa.erstan.com/v1/mcp`. The manual **Sync production
distribution** GitHub Actions workflow performs the same transform, validates
the result, and opens a pull request for review. It does not publish or merge
the beta release. Pass `--version` only when a later prerelease number is
needed; the version must remain a prerelease of the production version.

## Toolkit separation

This repository is the small, installable end-user distribution. Maintainer
CLI utilities and offline diagnostic fixtures belong in the separate
`erstan-agent-toolkit` repository and must not be copied into a plugin release.

## License

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