om-marketplace-client
Client side of Agent Market for zylos Agents.
How it works
- Runs as a PM2 service (
om-marketplace-client).
- Talks only to the Workspace BFF (
bff_url), authenticated with this Agent's
own Workspace API key. There is no marketplace-specific key.
- Every request carries the
X-Market-Client-Version header. If the market
answers CLIENT_VERSION_TOO_OLD, the client stops executing new intents
(reconciliation and revocation pulls continue) and the owner should run
zylos upgrade om-marketplace-client.
- Poll loop (~5 min, ±20% jitter): install intents and revocations.
- Reconcile (every 45 to 51 min, inside the poll loop): compare local state with the market.
- Installs never execute package content; packages are verified by sha256
before anything is written.
- Local skill report (at start, then with reconcile): directory name, frontmatter
name and version, and source of the skills the market did not install.
Metadata only; never file contents, paths or hashes.
Configuration
zylos add om-marketplace-client needs no settings on an Agent with the openmax
component. hooks/post-install.js takes COCO_BFF_URL, COCO_API_KEY,
COCO_ORG_ID, COCO_MEMBER_ID (required) and COCO_IDENTITY_ID (optional)
from the environment; each one not set is taken from the openmax component
config (~/zylos/components/openmax/config.json, or under $ZYLOS_DIR). Only
enabled orgs count: the primary is the one matching COCO_ORG_ID, else the
enabled org with the lowest id; the other enabled orgs go into the orgs map.
It writes config.json (mode 0600) and logs each field's source, never its
value. Without a TTY it never prompts; if a required value is in neither place
it exits with code 78, naming the missing variables and why the openmax
component config could not supply them. Unset any COCO_* variables after
install; the PM2 app filters them out and the service removes any it inherits,
logging only their names. At runtime the service reads only config.json. Key
rotation: rerun post-install with the new COCO_API_KEY.
Post-install and post-upgrade declare the template session-start shards and run
the zylos hook sync only when their hooks are missing. On Claude the agent
restarts once when idle; memory and context are kept. On Codex the templates
take effect when the Codex session next starts. Until then a template write
raises an alert and waits at most 15 minutes, then is reported as failed
(inject_unavailable).
Each template shard prints a fixed priority line (organization rules > template
the agent's own habits), the template's file path, the template's duty and
boundary (role.json, one line each; no boundary line when it is empty), then
inject.md. Duty, boundary and inject.md together stay within 8000 estimated
tokens. A template that does not fit one zylos 2200-token shard is split across
the four shards, each part marked (part k of n) and starting with the
priority line; cuts prefer paragraph, then line, then word breaks and never
fall inside the generated customizations.json file-list line. A template that cannot be
placed this way is refused at install. Templates over 2000 tokens need client
0.4.0 or later; the market refuses older clients with CLIENT_VERSION_TOO_OLD.
Template activation (0.6.0, always on): a template write, upgrade or uninstall
reaches the Agent at its next session start. Once the Agent has been idle for 5
minutes with no open OpenMax turn and runtime health ok, the client asks it,
through the control queue, to start a new session with the new-session skill
(one queued request at a time, at most every 30 minutes, 4 times a day, 3 times
per change). Templates adopted before 0.6.0 are confirmed by the next natural
session. The first shard records what the
session was given in injected.json; from that the client reports
template_activated (or template_inject_missing) to the market at once.
Commands
market-client status | sync | rollback <slug> | enable <slug> | disable <slug> | uninstall <slug>.
The Agent never installs or upgrades on its own; those run only from workbench
orders. Enable, disable, uninstall and rollback change the skill locally, then
report it. While the service runs, commands are handed to it. Exit codes: 0 done,
1 failed, 2 usage, 3 refused, 4 service did not answer, 78 configuration error.
See README.md for config (orgs map, primary org, data dir), status messages and
uninstall behaviour.
1---2name: om-marketplace-client3version: 0.6.04description: >-5 Agent Market client. Pulls install intents placed by humans in the Agent Market6 workbench, installs approved skills and expert templates into this Agent after7 sha256 verification, and reports results and reconciliation back to the market.8 The Agent never decides on its own what to install.9 Config at ~/zylos/components/om-marketplace-client/config.json.10 Service: pm2 zylos-om-marketplace-client.11type: capability1213lifecycle:14 npm: false15 service:16 type: pm217 name: zylos-om-marketplace-client18 entry: src/main.js19 data_dir: ~/zylos/components/om-marketplace-client20 hooks:21 post-install: hooks/post-install.js22 post-upgrade: hooks/post-upgrade.js23 configure: hooks/configure.js24 pre-uninstall: hooks/pre-uninstall.js25 preserve:26 - config.json27 - logs/2829bin:30 market-client: src/cli.js3132upgrade:33 repo: github:openmaxai/om-marketplace-client34 branch: main3536# Read by hooks/post-install.js from the environment, falling back per field to the openmax component config;37# not prompted by zylos so the API key is never collected through chat or written to ~/zylos/.env.38config:39 optional:40 - name: COCO_BFF_URL41 description: Workspace BFF base URL (https; http only for localhost). Required unless the openmax component config provides it (server.bff_url).42 - name: COCO_API_KEY43 description: This Agent's Workspace API key. Required unless the openmax component config provides it (agent.api_key).44 sensitive: true45 - name: COCO_ORG_ID46 description: Primary organization ID. Required unless the openmax component config provides it (an enabled org).47 - name: COCO_MEMBER_ID48 description: This Agent's member ID in COCO_ORG_ID. Required unless the openmax component config provides it (that org's self.member_id).49 - name: COCO_IDENTITY_ID50 description: This Agent's identity ID (openmax agent.identity_id).51metadata:52 source: https://skillmd.com/skills/openmaxai/om-marketplace-client53---5455# om-marketplace-client5657Client side of Agent Market for zylos Agents.5859## How it works6061- Runs as a PM2 service (`om-marketplace-client`).62- Talks only to the Workspace BFF (`bff_url`), authenticated with this Agent's63 own Workspace API key. There is no marketplace-specific key.64- Every request carries the `X-Market-Client-Version` header. If the market65 answers `CLIENT_VERSION_TOO_OLD`, the client stops executing new intents66 (reconciliation and revocation pulls continue) and the owner should run67 `zylos upgrade om-marketplace-client`.68- Poll loop (~5 min, ±20% jitter): install intents and revocations.69- Reconcile (every 45 to 51 min, inside the poll loop): compare local state with the market.70- Installs never execute package content; packages are verified by sha25671 before anything is written.72- Local skill report (at start, then with reconcile): directory name, frontmatter73 name and version, and source of the skills the market did not install.74 Metadata only; never file contents, paths or hashes.7576## Configuration7778`zylos add om-marketplace-client` needs no settings on an Agent with the openmax79component. `hooks/post-install.js` takes `COCO_BFF_URL`, `COCO_API_KEY`,80`COCO_ORG_ID`, `COCO_MEMBER_ID` (required) and `COCO_IDENTITY_ID` (optional)81from the environment; each one not set is taken from the openmax component82config (`~/zylos/components/openmax/config.json`, or under `$ZYLOS_DIR`). Only83enabled orgs count: the primary is the one matching `COCO_ORG_ID`, else the84enabled org with the lowest id; the other enabled orgs go into the `orgs` map.85It writes `config.json` (mode 0600) and logs each field's source, never its86value. Without a TTY it never prompts; if a required value is in neither place87it exits with code 78, naming the missing variables and why the openmax88component config could not supply them. Unset any `COCO_*` variables after89install; the PM2 app filters them out and the service removes any it inherits,90logging only their names. At runtime the service reads only `config.json`. Key91rotation: rerun post-install with the new `COCO_API_KEY`.92Post-install and post-upgrade declare the template session-start shards and run93the zylos hook sync only when their hooks are missing. On Claude the agent94restarts once when idle; memory and context are kept. On Codex the templates95take effect when the Codex session next starts. Until then a template write96raises an alert and waits at most 15 minutes, then is reported as failed97(`inject_unavailable`).98Each template shard prints a fixed priority line (organization rules > template99> the agent's own habits), the template's file path, the template's duty and100boundary (`role.json`, one line each; no boundary line when it is empty), then101`inject.md`. Duty, boundary and `inject.md` together stay within 8000 estimated102tokens. A template that does not fit one zylos 2200-token shard is split across103the four shards, each part marked `(part k of n)` and starting with the104priority line; cuts prefer paragraph, then line, then word breaks and never105fall inside the generated `customizations.json` file-list line. A template that cannot be106placed this way is refused at install. Templates over 2000 tokens need client1070.4.0 or later; the market refuses older clients with `CLIENT_VERSION_TOO_OLD`.108Template activation (0.6.0, always on): a template write, upgrade or uninstall109reaches the Agent at its next session start. Once the Agent has been idle for 5110minutes with no open OpenMax turn and runtime health ok, the client asks it,111through the control queue, to start a new session with the new-session skill112(one queued request at a time, at most every 30 minutes, 4 times a day, 3 times113per change). Templates adopted before 0.6.0 are confirmed by the next natural114session. The first shard records what the115session was given in `injected.json`; from that the client reports116`template_activated` (or `template_inject_missing`) to the market at once.117118## Commands119120`market-client status | sync | rollback <slug> | enable <slug> | disable <slug> | uninstall <slug>`.121The Agent never installs or upgrades on its own; those run only from workbench122orders. Enable, disable, uninstall and rollback change the skill locally, then123report it. While the service runs, commands are handed to it. Exit codes: 0 done,1241 failed, 2 usage, 3 refused, 4 service did not answer, 78 configuration error.125See README.md for config (`orgs` map, primary org, data dir), status messages and126uninstall behaviour.