Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/langgenius/mosoo-connector


https://github.com/langgenius/mosoo-connector

Last synced: 16 days ago
JSON representation

Awesome Lists containing this project

README 

          
# mosoo-connector



Generated Go CLI for Mosoo integrators: Public Thread API, Console GraphQL, and console REST.



## Build



```sh

make build

```



This clones or updates the Mosoo repository 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.



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

```



## Install



Install the latest published Go module without cloning the repository:



```sh

go install github.com/langgenius/mosoo-connector/cmd/mosoo@latest

```



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.



## 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

    `-- 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`, or `public-thread-api`). Root-level flat mounting is not used

because the CLI ships three 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



Three API surfaces 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` | `/agents/{id}/files`, `/agents/{id}/threads`, `/threads/{id}/events` |



Defaults are baked at codegen time (`MOSOO_HOST_BASE`, default `http://127.0.0.1:8787`).

Override any command with `--hostname` or `$MOSOO_HOST`.



## 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)

  -> current directory looks like the Mosoo source repo

  -> default local target

```



Generated API commands still default to the local Mosoo development stack when

no target config exists:



```json

{

  "target": "local",

  "baseUrl": "http://127.0.0.1:8787"

}

```



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://try.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, create a personal access token, and write the

CLI credentials for both hostname bases. This only works against a loopback Mosoo

API with the development backdoor enabled.



For cloud and custom targets, sign in at `https://try.mosoo.ai` or the configured

web app, use a Mosoo API token from that logged-in web session, then run

`mosoo auth login`. `--hostname` remains available as an advanced override for

one-off host selection.

The generated `mosoo console-rest access create` command maps to `POST /access-tokens`,

but it still needs viewer-level authentication; it is not a first-login mechanism by itself.



## Common commands



```sh

mosoo console user viewer

mosoo ls --app-limit 20 --agent-limit 20 --credential-limit 20 -o json

mosoo add-key --input-app-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-app-id  --input-agent-id  -o json

mosoo run --input-app-id  --input-agent-id  --input-prompt "Summarize this repository" -o json

mosoo console sessions events --app-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  \

  --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

{

  "input": {

    "content": [{ "type": "text", "text": "Summarize the attachment." }],

    "type": "user.message"

  },

  "resources": [{ "type": "file", "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}`.