# mosoo-connector
**AI agent CLI and coding-agent Skill for [mosoo](https://mosoo.ai).**
The generated `mosoo` CLI creates durable Sessions directly from Project credentials and harness/model/instructions, with saved Agents available as optional presets. It also configures, publishes, and inspects Agents through the [mosoo API and control plane](https://github.com/langgenius/mosoo). Use it from a terminal or install the bundled Skill so coding agents can discover the same commands. It supports mosoo Cloud, local development, and self-hosted targets.
This repository is mosoo client tooling, not an Agent runtime or a general-purpose OpenAPI generator.
## Quick Start
```sh
go install github.com/langgenius/mosoo-connector/cmd/mosoo@latest
mosoo setup
mosoo auth login
mosoo doctor --json
mosoo ls -o json
```
## Development Build
```sh
make build
```
This checks out the full Mosoo commit recorded in `specs/mosoo-contract.json`
under `.cache/mosoo`, exports OpenAPI / GraphQL
specs, renders `specs/sources.yaml` and `overlays/*.yaml`, runs Lathe code generation, and
builds `bin/mosoo`. Generated CLI command indexes are rendered into
`publish/skills/mosoo/references/cli/`; the CLI guide at
`publish/skills/mosoo/references/cli.md` is rendered from Lathe Skill include
resources under `publish/skills/mosoo/lathe-include/`; and the top-level mosoo
Skill entrypoint lives at `publish/skills/mosoo/SKILL.md`.
Lathe is managed by this repository. `make build` first compiles the pinned Lathe CLI from
`go.mod` into `.cache/bin/lathe`, then uses that local binary for code generation.
The same contract record is embedded into the CLI and bundled Skill. Query the
CLI copy with `mosoo doctor --json`; read the Skill copy at
`references/provenance.json`. Both include the full upstream Mosoo SHA and a
SHA-256 over canonical JSON (sorted object keys) for the Public Thread OpenAPI.
To refresh the contract, resolve and review a full Mosoo commit SHA, then run:
```sh
make build MOSOO_REF=<40-character-mosoo-commit>
make catalog-test
```
Commit the lock, source overlays, and all generated changes together. Pull
request CI and tag release run `make contract-gate`, which repeats that build
from the recorded commit and fails on a generated diff. Runtime/OpenAPI changes
land in `langgenius/mosoo` first; connector maintainers then refresh this lock,
generated CLI, and Skill before a connector release. Downstream docs should
consume the same upstream commit and normalized digest before publication.
Builds inject deterministic CLI version metadata from Git into Lathe's standard
`Version`, `Commit`, and `Date` fields:
```text
VERSION=$(git describe --tags --always --dirty)
COMMIT=$(git rev-parse --short=12 HEAD)
BUILD_DATE=$(git show -s --format=%cI HEAD)
```
Override `VERSION`, `COMMIT`, or `BUILD_DATE` for release builds when the
release pipeline has already computed those values.
Override the API host base baked into per-module defaults:
```sh
make build MOSOO_HOST_BASE=https://api.example.com
```
## Other Install Options
Install a specific release:
```sh
go install github.com/langgenius/mosoo-connector/cmd/mosoo@vX.Y.Z
```
`go install` downloads the module source and compiles it locally. It does not
run `make build`, so release tags include the generated CLI manifest and Go
command sources needed by `cmd/mosoo`. Make sure `go env GOBIN`, or
`$(go env GOPATH)/bin` when `GOBIN` is empty, is on `PATH`.
Install from a local checkout:
```sh
make install
```
By default, installation uses `go env GOBIN`, or `$(go env GOPATH)/bin` when
`GOBIN` is empty. Override the destination with `BINDIR`:
```sh
make install BINDIR="$HOME/.bin"
```
`make install` runs `make verify-install`, which checks that the installed
binary's `mosoo --version` output exactly matches the build metadata.
### Homebrew
After a release's generated Homebrew formula pull request is merged, tap this
repository and install the formula:
```sh
brew tap langgenius/mosoo-connector https://github.com/langgenius/mosoo-connector
brew install langgenius/mosoo-connector/mosoo
```
Release automation opens a GoReleaser pull request to add or update the
formula. Merged formula revisions install the matching prebuilt `mosoo` archive
from GitHub Releases.
## Installer
The source for the mosoo installer lives at `publish/installers/install.sh`.
The current stable public entrypoint is:
```sh
curl -fsSL https://install.mosoo.ai/install.sh | bash
```
The installer is interactive by default and asks for `y` or `n` before high-impact
steps. Use `--yes` for automation and `--dry-run` to preview the plan.
After a successful Skill copy, it retires the former
`$HOME/.codex/skills/mosoo` target when that path differs from the active
`$CODEX_HOME/skills/mosoo` target, preventing two stale Mosoo Skills from being
discovered at once.
## Non-production contract smoke
The manually dispatched `Non-production Public Thread smoke` workflow reads its
deployment URL, Agent ID, user ID, and environment label from the protected
`public-thread-smoke-non-production` GitHub environment and its token from an
environment secret. The script refuses `prod`/`production`, known production
Mosoo hosts, non-HTTPS targets, and environment labels that do not explicitly
identify a development, staging, preview, test, QA, sandbox, or non-production
deployment. It submits the minimal `{ "userId": "..." }` create shape, verifies
`thread.id`, and deletes the smoke Thread afterward.
## Published Skill layout
The publishable mosoo Skill is rooted at `publish/skills/mosoo`.
```text
publish/skills/mosoo/
|-- SKILL.md
`-- references/
|-- setup.md
|-- cli.md
|-- api.md
|-- provenance.json
`-- cli/
|-- catalog.md
`-- modules/
```
`references/cli.md`, `references/cli/catalog.md`, and
`references/cli/modules/*.md` are generated from Lathe's CLI Skill output during
`make build`. To change the guide text in `references/cli.md`, edit the matching
Lathe include file under `lathe-include/`. Treat the module files as CLI command
indexes, not as the top-level mosoo Skill.
## Command layout
`cli.command_path` is `namespaced`: every generated command lives under its source module
(`console`, `console-rest`, `public-thread-api`, or `public-thread-api-v2`). Root-level flat mounting is not used
because the CLI ships multiple API surfaces.
Help text, examples, and error hints for generated commands come from `overlays/*.yaml`
(regenerated by `scripts/render-overlays.ts` during `make build`). The generated
catalog is the complete control-plane surface; overlays are usability polish, and
the mosoo Skill reference explains high-frequency workflows.
High-frequency root commands such as `mosoo ls`, `mosoo run`, `mosoo add-key`,
and `mosoo create-agent` are Lathe overlay `shortcuts` for generated operations.
They execute the same generated command specs as their canonical paths and are
reported in the generated command catalog.
## Hostnames and auth
Four API modules share one deployment but use different URL bases:
| CLI module | Default hostname (from `MOSOO_HOST_BASE`) | Example paths |
|------------|-------------------------------------------|---------------|
| `console`, `console-rest` | `{base}/api` | `/graphql`, `/access-tokens`, `/files` |
| `public-thread-api` | `{base}/api/v1` | Published-Agent compatibility API; `userId` required |
| `public-thread-api-v2` | `{base}/api/v2` | Project Session creation, optional Agent presets and `userId`, persisted `/threads/{id}/usage` |
Generated specs carry baked fallback hostnames from codegen (`MOSOO_HOST_BASE`).
Normal mosoo commands resolve a target before using those fallbacks. Override
any command with `--hostname` or `$MOSOO_HOST`.
## Direct Project Sessions (v2)
Use a deployment that advertises `GET /api/v2/openapi.json` and confirm its
available features before changing a production integration. The CLI keeps
the existing v1 commands unchanged and exposes v2 explicitly. Configure your
model provider credentials in the Project (BYOK), then save this as `session.json`:
```json
{
"configuration": {
"type": "inline",
"harness": "openai-runtime",
"provider": "openai",
"model": "<model-id>",
"instructions": "Analyze the supplied material and save the results."
},
"input": {
"type": "user.message",
"content": [{ "type": "text", "text": "Summarize the attachment." }]
},
"resources": [{ "type": "file", "file_id": "<uploaded-file-id>" }]
}
```
```sh
mosoo --target custom --base-url <service-origin> public-thread-api-v2 files upload --project-id <project-id> --file ./brief.txt -o json
mosoo --target custom --base-url <service-origin> public-thread-api-v2 threads create --project-id <project-id> --file session.json --idempotency-key <stable-key> -o json
mosoo --target custom --base-url <service-origin> public-thread-api-v2 events send --thread-id <thread-id> --file events.json --idempotency-key <new-turn-key> -o json
mosoo --target custom --base-url <service-origin> public-thread-api-v2 events wait --thread-id <thread-id> --final-output
mosoo --target custom --base-url <service-origin> public-thread-api-v2 threads usage --thread-id <thread-id> --limit 100 -o json
```
Use the uploaded `file.id` in `resources`; omit resources when no file is needed.
Project creation requires `configuration`. Choose `type: "inline"` with harness,
provider, model and non-blank instructions, or `type: "agent"` with `agent_id`
for an optional saved private preset. These modes cannot be mixed. Input and
`userId` are optional; omitted input creates an idle Session, omitted userId is
`null`. Inline execution creates no Agent. The admitted configuration stays
fixed; continue through the same returned `thread.id`.
A Project key cannot cross Projects. Account login also requires an explicit
owned `--project-id` on these operations. Reusing an idempotency key with a
changed configuration returns 409. The compatibility `threads create --agent-id`
and `files upload --agent-id` forms remain available; `--agent-id` and
`--project-id` cannot be combined. Platform model supply, top-ups and commercial
billing are separate work in [#636](https://github.com/langgenius/mosoo/issues/636).
All existing file upload, wait and transcript helpers work under both modules.
Usage preserves `null` for unreported values; `reportedCostUsd` is a runtime
estimate, not an invoice. Pass `nextCursor` as `--after` to paginate. Keep the
same idempotency key for a retry with an unchanged body, and a new key for a new
turn. Run `mosoo auth login` for the chosen target once after upgrading to add the
v2 credential. Configure Project keys against the explicit v2 hostname.
API commands never recreate credentials removed by logout.
### Pi Sessions
Pi is an explicit harness choice on deployments that enable it. Configure a
built-in provider key or a custom provider in the Project. Built-in models use
the protocol from Mosoo's model catalog; custom models use the credential's
`modelProtocol`. Pi supports OpenAI Chat Completions, OpenAI Responses,
Anthropic Messages, and Google Gemini, including streaming and tool calls.
For custom providers, use the exact configured model ID, never the catalog
placeholder `custom-model`. OpenCode remains the default for custom providers;
select Pi explicitly. This integration uses Project API-key credentials, not
standalone Pi's subscription OAuth or Bedrock/Vertex ambient authentication.
For a custom Responses endpoint, create the credential with:
```sh
mosoo console credentials create-vendor-credential \
--input-project-id <project-id> \
--input-vendor-id openai-compatible \
--input-name "Custom Responses" \
--input-api-base https://models.example.com/v1 \
--input-model-protocol openai-responses \
--input-models <model-id> \
--input-api-key-env MODEL_API_KEY -o json
```
The custom provider ID stays `openai-compatible` for every supported protocol.
Set `modelProtocol` on the credential, not on the Session configuration. New
custom credentials default to `openai-chat-completions` if omitted. Existing
credentials without a stored protocol retain legacy runtime-based routing;
set their protocol explicitly to match the endpoint. Omitting the field during
an update preserves its value. Use the same protocol, base URL and model ID in
`test-vendor-credential`; then verify a representative tool-using Run.
| Model protocol | Claude Runtime | OpenAI Runtime | OpenCode | Pi |
| --- | --- | --- | --- | --- |
| `anthropic-messages` | Anthropic provider only | — | Yes | Yes |
| `openai-responses` | — | Yes | Yes | Yes |
| `openai-chat-completions` | — | — | Yes | Yes |
| `google-gemini` | — | — | Yes | Yes |
A provider can offer models from multiple protocol families; built-in catalog
routing is resolved per model. The built-in Gemini provider keeps its existing
Chat Completions endpoint. Use a custom `google-gemini` credential with Google's
native base URL for the native Gemini protocol.
Save this as `pi-session.json`:
```json
{
"configuration": {
"type": "inline",
"harness": "pi",
"provider": "openai-compatible",
"model": "<custom-model-id>",
"instructions": "Use tools to inspect the supplied repository and summarize your findings."
},
"input": {
"type": "user.message",
"content": [{ "type": "text", "text": "List the files in the working directory." }]
}
}
```
```sh
mosoo --target custom --base-url <service-origin> public-thread-api-v2 threads create --project-id <project-id> --file pi-session.json --idempotency-key <stable-create-key> -o json
mosoo --target custom --base-url <service-origin> public-thread-api-v2 events wait --thread-id <thread-id> --final-output
```
The returned `thread.id` is used for follow-ups. Existing Sessions retain their
original runtime. For an optional saved Agent preset, use `runtimeId: "pi"`
and a compatible provider/model in the Agent input or round-tripped manifest; inspect `mosoo agent manifest apply --dry-run`
before applying changes. Pi requires full access with unrestricted built-in
tools; do not configure permission modes or tool restrictions it cannot enforce.
## Target resolution
Generated API commands resolve a default target before falling back to baked-in hostnames.
Explicit hostname overrides always win:
```text
--hostname
-> MOSOO_HOST
-> --target / --base-url
-> MOSOO_TARGET / MOSOO_BASE_URL
-> project config .mosoo/config.json
-> global config in the OS config dir (or $MOSOO_CONFIG_DIR/config.json)
-> default mosoo Cloud target
```
Generated API commands default to mosoo Cloud when no target config exists:
```json
{
"target": "cloud",
"baseUrl": "https://cloud.mosoo.ai"
}
```
First-time cloud users should use the zero-config setup and login path:
```sh
mosoo setup
mosoo auth login
```
`mosoo setup` stores the root target (`https://cloud.mosoo.ai`) in config. The CLI
derives the console API (`/api`) and Public API (`/api/v1`) hosts internally.
`mosoo auth login` defaults to mosoo Cloud when no config exists, validates the
token against the console API, and stores the same credential for both derived
API hosts.
Self-hosted and local targets use explicit setup subcommands:
```sh
mosoo setup self-host --base-url https://mosoo.example.com
mosoo setup custom --api-url https://mosoo.example.com/api
mosoo setup local
```
Cloud and custom targets are also supported with explicit command flags:
```sh
mosoo doctor --json --target cloud
mosoo console user viewer --target custom --base-url https://example.com
```
Check the resolved target and readiness:
```sh
mosoo doctor --json
```
The JSON output is versioned with `schemaVersion` and groups machine-readable
readiness data under `target`, `auth`, `install`, `checks`, and `failures`.
Failure entries include stable `code` and `action` fields so automation can
branch without parsing human messages.
For local development targets, the installer can sign in through the local development
backdoor with an `@mosoo.ai` email, authorize a CLI device flow, and write the
account login credentials for both hostname bases. This only works against a loopback mosoo
API with the development backdoor enabled.
Run `mosoo auth login` for browser authorization. The resulting `mcli_` credential
grants account access, including operations across your Projects. `--hostname`
remains available for one-off host selection. Non-interactive installers can use
an existing account credential through `MOSOO_CLI_TOKEN`.
Application backends use Project API keys (`msp_`). Each key permits Agent
configuration, execution, and files within one Project. It cannot create or delete
Projects, manage API keys, or access another Project. After account login, create
or list keys with:
```sh
mosoo console-rest access create --set projectId=<project-id> --set label="backend" -o json
mosoo console-rest access list --project-id <project-id> -o json
```
Legacy `mst_` and `grt_pat_` credentials no longer work after the Project key
upgrade. Run `mosoo auth login` again for CLI access. For deployed integrations,
create a key under the matching Project and replace the old secret. Revoking a
Project key blocks later requests while existing tasks continue.
## Common commands
```sh
mosoo console user viewer
mosoo ls --project-limit 20 --agent-limit 20 --credential-limit 20 -o json
mosoo add-key --input-project-id <project-id> --input-vendor-id openai --input-name OpenAI --input-api-key-env OPENAI_API_KEY -o json
mosoo create-agent --file agent-create.json -o json
mosoo console agents publish --input-project-id <project-id> --input-agent-id <agent-id> -o json
mosoo run --input-project-id <project-id> --input-agent-id <agent-id> --input-prompt "Summarize this repository" -o json
mosoo console sessions events --project-id <project-id> --session-id <session-id> --limit 100 -o json
mosoo search "run agent" --json
mosoo commands show run --json
```
Use `commands show` before executing an unfamiliar generated command so flags,
body shape, auth, and output format are explicit.
### Public Thread file uploads
The Public API uses one multipart upload before a Thread references the file.
Upload a local file to the Agent endpoint and save `file.id` from the response:
```sh
mosoo public-thread-api files upload \
--agent-id <agent-id> \
--file ./brief.txt \
-o json
```
Then put that ID in `resources[].file_id` when creating a Thread or sending a
follow-up `user_message` event:
```json
{
"userId": "demo-user-001",
"input": {
"content": [{ "type": "text", "text": "Summarize the attachment." }],
"type": "user.message"
},
"resources": [{ "type": "file", "file_id": "<file-id>" }]
}
```
There is no public create-upload, PUT, complete, or post-create attach step.
`GET /threads/{threadId}/files` lists claimed attachments and artifacts;
metadata, content download, and deletion are exposed under `/files/{fileId}`.