grix-connector 4.2.3 → 4.2.5

package/openclaw-plugin/index.js

@@ -3135,7 +3135,7 @@ import { homedir as homedir5 } from "node:os";
 import { dirname as dirname3, join as join7 } from "node:path";
 import { promisify } from "node:util";
 var execFileAsync = promisify(execFile);
-var CLI_TIMEOUT_MS = 3e4;
+var CLI_TIMEOUT_MS = 12e4;
 var GRIX_PROVIDER_ID = "grix";
 function stateDir() {
   const explicit = process.env.OPENCLAW_STATE_DIR?.trim();
@@ -3150,8 +3150,14 @@ function sidecarPath() {
 async function runOpenClaw(args, stdin) {
   const child = execFileAsync("openclaw", args, { timeout: CLI_TIMEOUT_MS });
   child.child.stdin?.end(stdin ?? "");
-  const { stdout } = await child;
-  return stdout;
+  try {
+    const { stdout } = await child;
+    return stdout;
+  } catch (err2) {
+    const e = err2;
+    const why = e.killed || e.signal ? `timed out after ${CLI_TIMEOUT_MS}ms` : (e.stderr ?? "").trim() || e.message;
+    throw new Error(`openclaw ${args.join(" ")} failed: ${why}`);
+  }
 }
 function configFilePath() {
   const explicit = process.env.OPENCLAW_CONFIG_PATH?.trim();
@@ -10866,6 +10872,51 @@ var TOOLS = [
       }
     }
   },
+  {
+    name: "grix_egg_search",
+    description: "Search the Grix egg market (published skill/persona packages the owner can hatch into a new agent or install into an existing one). Keyword matching is per-term AND over name + description + category, so search short keywords (one concept per call) rather than a whole sentence; omit keyword to browse a category. Results include id, name, description, category, install_count, can_create_agent, and existing_agent_client_types.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        keyword: { type: "string", description: "Short search keyword(s); terms are ANDed. Omit to list by category." },
+        categoryId: { type: "string", description: "Optional egg category ID to restrict results." },
+        locale: { type: "string", description: "Optional locale such as zh-CN or en; defaults to the owner's locale." },
+        page: { type: "integer", description: "Page number, starting from 1." },
+        pageSize: { type: "integer", description: "Items per page (1-50), default 20." }
+      }
+    },
+    validation: {
+      required: [],
+      properties: {
+        keyword: { type: "string", maxLength: 200 },
+        categoryId: { type: "string" },
+        locale: { type: "string", maxLength: 16 },
+        page: { type: "integer", minimum: 1 },
+        pageSize: { type: "integer", minimum: 1, maximum: 50 }
+      }
+    }
+  },
+  {
+    name: "grix_egg_get",
+    description: "Get one Grix egg by id \u2014 full description, current version, and whether it can create a new agent or install into existing agents. Use after grix_egg_search to show details before the owner decides to hatch.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "Egg ID from grix_egg_search." },
+        locale: { type: "string", description: "Optional locale." },
+        version: { type: "integer", description: "Optional specific version; defaults to the current one." }
+      },
+      required: ["id"]
+    },
+    validation: {
+      required: ["id"],
+      properties: {
+        id: { type: "string" },
+        locale: { type: "string", maxLength: 16 },
+        version: { type: "integer", minimum: 1 }
+      }
+    }
+  },
   {
     name: "grix_skill_set",
     description: "Create, update, or delete one of your owner's custom skills in the platform skill library. The skill library auto-syncs to every machine the owner runs an agent on (a per-machine `grix/skills` directory), so defining a skill here makes it available on all of them. A skill is a plain SKILL.md package (frontmatter + body), same standard as other Grix skills. Provide `name` and the full `content` (the SKILL.md text) to create or overwrite by name. To delete a skill, pass its `name` with an empty `content` string. How and when any agent actually loads/uses a synced skill is arranged by the owner (in a system prompt or in conversation); this tool only manages the library.",
@@ -11098,6 +11149,10 @@ function toolCallToInvoke(toolName, args) {
       return buildAccessControlInvoke(args);
     case "grix_widget_visitor_ban":
       return buildWidgetVisitorBanInvoke(args);
+    case "grix_egg_search":
+      return buildEggSearchInvoke(args);
+    case "grix_egg_get":
+      return buildEggGetInvoke(args);
     case "grix_skill_set":
       return buildSkillSetInvoke(args);
     case "grix_skill_get":
@@ -11128,6 +11183,21 @@ function buildQueryInvoke(args) {
   if (args.beforeId != null) params.before_id = args.beforeId;
   return { action: invokeAction, params };
 }
+function buildEggSearchInvoke(args) {
+  const params = {};
+  if (args.keyword != null) params.keyword = args.keyword;
+  if (args.categoryId != null) params.category_id = args.categoryId;
+  if (args.locale != null) params.locale = args.locale;
+  if (args.page != null) params.page = args.page;
+  if (args.pageSize != null) params.page_size = args.pageSize;
+  return { action: "egg_search", params };
+}
+function buildEggGetInvoke(args) {
+  const params = { id: args.id };
+  if (args.locale != null) params.locale = args.locale;
+  if (args.version != null) params.version = args.version;
+  return { action: "egg_get", params };
+}
 var AUDIT_DATA_ACTION_MAP = {
   get_manifest: "audit_get_manifest",
   list_spans: "audit_list_spans",
@@ -11618,6 +11688,49 @@ function createGrixQueryTool(api, ctx) {
   };
 }
 
+// src/openclaw/admin/egg-market-tools.ts
+function createEggMarketTool(toolName, label, api, ctx) {
+  const def = TOOLS.find((t) => t.name === toolName);
+  const contextAccountId = ctx?.agentAccountId;
+  return {
+    name: toolName,
+    label,
+    description: def.description,
+    parameters: def.inputSchema,
+    async execute(_toolCallId, params) {
+      try {
+        const accountId = resolveStrictToolAccountId({ toolName, contextAccountId });
+        const account = resolveGrixAccount({
+          cfg: api.config,
+          accountId,
+          strictAccountScope: true
+        });
+        if (!account.enabled) {
+          throw new Error(`Grix account "${account.accountId}" is disabled.`);
+        }
+        if (!account.configured) {
+          throw new Error(`Grix account "${account.accountId}" is not configured.`);
+        }
+        const { action, params: invokeParams } = toolCallToInvoke(toolName, params);
+        const client = requireActiveAibotClient(accountId);
+        const data = await client.agentInvoke(action, invokeParams);
+        return jsonToolResult({ ok: true, accountId: account.accountId, action, data });
+      } catch (err2) {
+        return jsonToolResult({
+          ok: false,
+          error: err2 instanceof Error ? err2.message : String(err2)
+        });
+      }
+    }
+  };
+}
+function createGrixEggSearchTool(api, ctx) {
+  return createEggMarketTool("grix_egg_search", "Grix Egg Search", api, ctx);
+}
+function createGrixEggGetTool(api, ctx) {
+  return createEggMarketTool("grix_egg_get", "Grix Egg Get", api, ctx);
+}
+
 // src/openclaw/admin/audit-data-tool.ts
 var auditDataDef = TOOLS.find((tool) => tool.name === "grix_audit_data");
 function createGrixAuditDataTool(api, ctx) {
@@ -12836,6 +12949,8 @@ async function bindAgent(agentName) {
 var DEFAULT_TOOLS_ALLOW = [
   "message",
   "grix_query",
+  "grix_egg_search",
+  "grix_egg_get",
   "grix_group",
   "grix_register",
   "grix_message_send",
@@ -14473,6 +14588,8 @@ var plugin = {
     api.registerTool((ctx) => createGrixGroupTool(api, ctx), { optional: true });
     api.registerTool((ctx) => createGrixAdminTool(api, ctx), { optional: true });
     api.registerTool((ctx) => createGrixEggTool(api, ctx), { optional: true });
+    api.registerTool((ctx) => createGrixEggSearchTool(api, ctx), { optional: true });
+    api.registerTool((ctx) => createGrixEggGetTool(api, ctx), { optional: true });
     api.registerTool((ctx) => createGrixRegisterTool(api, ctx), { optional: true });
     api.registerTool((ctx) => createGrixUpdateTool(api, ctx), { optional: true });
     api.registerTool((ctx) => createGrixMessageSendTool(api, ctx), { optional: true });

package/openclaw-plugin/skills/grix-admin/SKILL.md

@@ -1,164 +1,135 @@
 ---
 name: grix-admin
-description: Responsible for OpenClaw local configuration, binding, and runtime convergence; can create new remote API agents through the current agent's WS channel, and supports querying, creating, modifying agent categories and assigning categories to agents.
+description: Grix agent administration for OpenClaw — create remote API agents, manage agent categories, and rotate API keys through `grix_admin`, and bind an agent's remote parameters into the local OpenClaw configuration with validation and routing verification. For "create me an agent for X" requests, run `grix-egg` discovery first; use this skill when the user already has agent parameters to bind, asks for category management, or grix-egg found no matching egg / the user wants a blank agent.
 ---
 
-# Grix Agent Admin
-
-`grix-admin` is responsible for three things:
-
-1. Landing existing remote agent parameters into local OpenClaw and handling runtime convergence after binding.
-2. When the current main agent is already online and has the corresponding scope, creating new remote API agents through `grix_admin`'s direct actions, then continuing with local landing.
-3. During agent creation or subsequent agent management, reusing `grix_admin`'s direct actions to query categories, create categories, modify categories, and assign categories to agents.
-
-## Entry Method
-
-1. In most cases, enter this skill from `grix_admin`'s `task` entry; the first line of `task` must clearly state `bind-local`, `create-and-bind`, or `category-manage`.
-2. Only when executing remote API agent creation or category operations within this skill should you directly call `grix_admin` once, without passing `task` again.
-3. In new flows, always explicitly pass `action` when directly calling `grix_admin`:
-   - `create_agent`
-   - `list_categories`
-   - `create_category`
-   - `update_category`
-   - `assign_category`
-4. The legacy direct call format for `create_agent` is still compatible, but should not be used in new flows.
-
-## Agent Creation Intake
-
-Before any `create_agent` API call:
-
-1. Ensure both `agentName` and `introduction` are present and specific. Never create an Agent with an empty, generic, or placeholder introduction.
-2. If either the Agent name or a usable introduction is missing or too vague, pause before calling the tool and ask one concise question: “这个 Agent 主要做什么？核心职责、服务对象和工作边界是什么？”
-3. Convert the user's answer into:
-   - A concise, professional `agentName` that reflects the Agent's role.
-   - A professional `introduction` that states its purpose, core responsibilities, intended users or scenarios, operating expectations, and important boundaries.
-4. Preserve the user's facts and intent. Do not invent permissions, business authority, expertise, or responsibilities that the user did not grant.
-5. Treat `introduction` as the Agent's behavioral specification, not promotional copy.
-6. Pass the finalized professional text in the actual `introduction` field of `action=create_agent`.
-
-## Direct Action List
-
-1. `action=create_agent`
-   - Required by this skill: `agentName`, `introduction`
-   - Optional: `isMain`, `categoryId`, `categoryName`, `parentCategoryId`, `categorySortOrder`
-   - `categoryId` and `categoryName` cannot be provided simultaneously
-   - When `categoryName` is given, it first checks for duplicates under `parentCategoryId`; if not found, creates and assigns
-2. `action=list_categories`
-   - Required: none
-3. `action=create_category`
-   - Required: `name`, `parentId`
-   - Optional: `sortOrder`
-4. `action=update_category`
-   - Required: `categoryId`, `name`, `parentId`
-   - Optional: `sortOrder`
-5. `action=assign_category`
-   - Required: `agentId`, `categoryId`
-   - `categoryId=0` means clear the category
-
-## Mode A: bind-local (OpenClaw Local Binding)
-
-Input fields (written in `grix_admin.task`):
-
-1. First line must be `bind-local`
-2. `agent_name` (required)
-3. `agent_id` (required)
-4. `api_endpoint` (required)
-5. `api_key` (required)
-
-Execution rules:
-
-1. Do not perform remote creation; execute local binding directly. Do not call scripts that directly modify `openclaw.json`.
-2. Prepare local directories:
-   - `workspace=~/.openclaw/workspace-<agent_name>`
-   - `agentDir=~/.openclaw/agents/<agent_name>/agent`
-   - Persona files belong only in the workspace root; add minimal `IDENTITY.md`, `SOUL.md`, and `AGENTS.md` if required files are missing.
-3. Read the current account, agent, tool profile, tool allowlist, session visibility, and binding configuration.
-4. Resolve `model` by reusing the existing agent model, then `agents.defaults.model.primary`; if neither exists, report the missing model and stop.
-5. Merge the account and agent entries, bind the agent to `grix:<agent_name>`, set the coding tool profile and required Grix tools, and restore `channels.grix.enabled=true` only if it is explicitly disabled.
-6. Use official OpenClaw CLI commands item by item; do not overwrite the entire config.
-7. Perform static validation:
+# Grix Agent Admin (OpenClaw)
+
+Three workflows:
+
+| Workflow | What it does |
+|---|---|
+| [`bind-local`](#workflow-a--bind-local) | Bind an existing remote agent's parameters into local OpenClaw, validate, verify routing |
+| [`create-and-bind`](#workflow-b--create-and-bind) | Create a remote agent via `grix_admin`, then run `bind-local` |
+| [`category-manage`](#workflow-c--category-manage) | List / create / update / assign categories via `grix_admin` |
+
+## Two ways `grix_admin` is called
+
+1. **Delegated workflow** — the caller passes only `task`, whose first line
+   names the workflow (`bind-local`, `create-and-bind`, `category-manage`)
+   followed by `key=value` lines. `grix-register` hands off this way. You then
+   run the workflow described below.
+2. **Direct action** — pass `action` plus its fields (table below). Use this
+   for every remote call *inside* a workflow. `task` and `action` cannot be
+   combined in one call.
+
+**Creating a new agent from a business description?** Run the `grix-egg` skill
+first (search the egg market, let the owner hatch a ready-made egg). Come here
+for creation only when no egg matched or the user explicitly wants a blank
+agent — and say so in your reply.
+
+All remote operations go through `grix_admin` on the current account's WS
+channel — never hand-written HTTP or scripts, never across accounts, and
+never ask the user for a website account or password.
+
+## `grix_admin` direct actions
+
+| `action` | Required | Optional |
+|---|---|---|
+| `create_agent` | `agentName`, `introduction` | `isMain`, `categoryId`, `categoryName`, `parentCategoryId`, `categorySortOrder` |
+| `list_categories` | — | — |
+| `create_category` | `name`, `parentId` | `sortOrder` |
+| `update_category` | `categoryId`, `name`, `parentId` | `sortOrder` |
+| `assign_category` | `agentId`, `categoryId` (`0` clears) | — |
+| `rotate_api_key` | `agentId` | — |
+
+Notes:
+
+- `categoryId` and `categoryName` are mutually exclusive — report the conflict
+  and stop if both are given.
+- With `categoryName`, the backend looks for an exact match under
+  `parentCategoryId`, creating it if absent. If several exact matches exist,
+  stop and ask the owner for an explicit `categoryId`.
+- `isMain=true` only when actually creating a new main API agent.
+- `code=4003` means a missing scope — report the exact `agent.api.create` or
+  `agent.category.*` scope.
+
+## Agent creation intake (before any `create_agent`)
+
+1. `agentName` and `introduction` must both be present and specific. Never
+   create an agent with an empty, generic, or placeholder introduction.
+2. If either is missing or vague, ask one concise question in the user's
+   language: what does this agent mainly do — core responsibilities, whom it
+   serves, and its boundaries?
+3. Turn the answer into a concise professional `agentName` and an
+   `introduction` that states purpose, core responsibilities, intended users or
+   scenarios, operating expectations, and boundaries. Treat `introduction` as
+   the agent's behavioral specification, not marketing copy.
+4. Preserve the user's facts and intent; do not invent permissions, authority,
+   or expertise they did not grant.
+
+## Workflow A — `bind-local`
+
+Inputs: `agent_name`, `agent_id`, `api_endpoint`, `api_key` (all required).
+Missing field → say which and stop. Do not create anything remotely, and do
+not call back to `grix-register`.
+
+1. Prepare local directories: `workspace=~/.openclaw/workspace-<agent_name>`
+   and `agentDir=~/.openclaw/agents/<agent_name>/agent`. Persona files live
+   only in the workspace root; add minimal `IDENTITY.md`, `SOUL.md`, and
+   `AGENTS.md` if missing.
+2. Read the current account, agent, tool profile, tool allowlist, session
+   visibility, and binding configuration.
+3. Resolve `model`: reuse the existing agent model, else
+   `agents.defaults.model.primary`; if neither exists, report the missing
+   model and stop.
+4. Merge the account and agent entries, bind the agent to
+   `grix:<agent_name>`, set the coding tool profile and required Grix tools,
+   and restore `channels.grix.enabled=true` only if it was explicitly
+   disabled. Apply each change with the official OpenClaw CLI item by item —
+   never overwrite or hand-edit `openclaw.json`.
+5. Static validation:
    - `openclaw config validate`
    - `openclaw config get --json channels.grix.accounts.<agent_name>`
    - `openclaw config get --json agents.list`
    - `openclaw agents bindings --agent <agent_name> --json`
-8. If real routing verification is available, perform it immediately. Falling back to the main agent, default assistant behavior, an old persona, or an ID mismatch means the runtime has not switched.
-9. Only when static validation passes but real routing verification fails may one `openclaw gateway restart` be used as targeted remediation; then repeat the same verification once.
-10. If real verification is unavailable, state “config has been written, runtime not yet tested, needs subsequent upper-level flow to continue verification”.
-
-## Mode B: create-and-bind (Create Remote Agent Then Bind Locally)
-
-Fields written in `grix_admin.task`:
-
-1. First line must be `create-and-bind`
-2. `agentName` (required)
-3. `introduction` (required; professionally organized according to **Agent Creation Intake**)
-4. `isMain` (optional, default `false`)
-5. `categoryId` (optional)
-6. `categoryName` (optional)
-7. `parentCategoryId` (optional, default `0`)
-8. `categorySortOrder` (optional)
-
-Execution rules:
-
-1. Confirm the current session is bound to a valid Grix account; cross-account execution is prohibited.
-2. If both `categoryId` and `categoryName` are provided, report an error and stop.
-3. Call `grix_admin` once with `action=create_agent`, passing `agentName`, `introduction`, and the supplied optional fields.
-4. Read `createdAgent.id`, `createdAgent.agent_name`, `createdAgent.api_endpoint`, and `createdAgent.api_key` from the result.
-5. If category assignment was requested but not completed by the return result, supplement it through the appropriate direct category actions.
-6. In the `categoryName` flow, if multiple exact matches exist under the same parent, stop and ask the owner to use an explicit `categoryId`.
-7. Continue immediately with `bind-local` using the returned parameters.
-8. `isMain=true` should only be used when actually creating a new main API agent.
-9. Do not claim completion until static validation and any available real routing verification pass.
-
-## Mode C: category-manage (Category Management)
-
-Fields written in `grix_admin.task`:
-
-1. First line must be `category-manage`
-2. `operation` (required): `list`, `create`, `update`, or `assign`
-3. `name` (`create` / `update` required)
-4. `parentId` (`create` / `update` required)
-5. `sortOrder` (`create` / `update` optional)
-6. `categoryId` (`update` / `assign` required; `0` clears an assignment)
-7. `agentId` (`assign` required)
-
-Execution rules:
-
-1. Strictly bind all operations to the current session account; cross-account execution is prohibited.
-2. Complete all remote steps through `grix_admin` direct actions; do not hand-write HTTP or temporary scripts.
-3. Map operations directly: `list_categories`, `create_category`, `update_category`, or `assign_category`.
-4. If the task also creates a new agent, use `create-and-bind` instead.
-
-## Remote Creation Fallback
-
-If the task has neither existing agent parameters nor an online main channel with `agent.api.create`, stop and ask the owner to create the remote agent through the backend admin path. After obtaining the parameters, proceed with `bind-local`.
-
-## Guardrails
-
-1. Never ask for a website account or password.
-2. `bind-local` must not call back to `grix-register`.
-3. All remote creation and category actions must go through `grix_admin` direct actions via the current account's WS channel.
-4. Never repeatedly echo the complete `api_key` in plaintext.
-5. Do not manually modify `openclaw.json`; use official OpenClaw CLI commands.
-6. Do not claim full convergence until static validation and any available real routing verification pass.
-7. Use at most one targeted gateway restart, only under the failure conditions defined by `bind-local`.
-
-## Error Handling
-
-1. For missing fields, clearly state which field is missing and stop.
-2. If `agentName` or a usable `introduction` is missing, ask for the Agent's purpose, responsibilities, intended users, and boundaries before remote creation.
-3. If both `categoryId` and `categoryName` are supplied, report the conflict and stop.
-4. For `code=4003`, report the exact missing `agent.api.create` or `agent.category.*` scope.
-5. Report the exact failed OpenClaw CLI command and validation result.
-6. If one permitted restart and retest still fail, report the flow as failed or partially complete.
-
-## Response Style
-
-1. Clearly state whether the execution is `bind-local`, `create-and-bind`, or `category-manage`.
-2. Report remote creation, category handling, local config writing, and validation as separate phases when applicable.
-3. Clearly distinguish static configuration success from verified runtime convergence.
-4. If a later phase fails after remote creation, report the overall result as partially complete.
-
-## References
-
-1. [references/api-contract.md](references/api-contract.md)
+6. If real routing verification is available, run it now. Falling back to the
+   main agent, default assistant behavior, an old persona, or an ID mismatch
+   means the runtime has not switched.
+7. Only when static validation passes but routing verification fails, run
+   **one** `openclaw gateway restart` and repeat the verification once.
+
+Reporting: distinguish "config written and statically valid" from "runtime
+verified". If verification cannot be run, say "config has been written,
+runtime not yet tested, needs the upper-level flow to continue verification".
+Never echo the full `api_key` in plaintext.
+
+## Workflow B — `create-and-bind`
+
+Inputs: `agentName`, `introduction` (required; run the intake above);
+`isMain`, `categoryId` | `categoryName`, `parentCategoryId` (default `0`),
+`categorySortOrder` (optional).
+
+1. Call `grix_admin` once with `action=create_agent` and the supplied fields.
+2. Read `createdAgent.id`, `agent_name`, `api_endpoint`, `api_key` from the
+   result. If a requested category was not applied, finish it with the
+   category actions.
+3. Continue immediately with Workflow A using those values.
+4. Report remote creation and local binding as separate phases; if binding
+   fails after creation succeeded, report the overall result as partial.
+
+Fallback: if no agent parameters exist and the current account lacks
+`agent.api.create`, stop and ask the owner to create the agent in the backend
+admin, then run Workflow A with the parameters they provide.
+
+## Workflow C — `category-manage`
+
+Inputs: `operation` (`list` | `create` | `update` | `assign`) plus the fields
+required by the matching action above. Map directly to `list_categories`,
+`create_category`, `update_category`, `assign_category`. If the request also
+creates an agent, use Workflow B instead.
+
+## Reference
+
+[references/api-contract.md](references/api-contract.md) — request/response
+shapes for each action and the local binding checklist.

package/openclaw-plugin/skills/grix-egg/SKILL.md

@@ -1,10 +1,36 @@
 ---
 name: grix-egg
-description: "Program-driven hatching: AI only organizes parameters and calls `grix_egg`; the program handles creation, installation, binding, acceptance, and status reporting. Use for creating or installing an Agent from an egg package, including collecting and professionally organizing its name and behavioral introduction before remote creation."
+description: "Grix egg market for OpenClaw — the FIRST entry when the user wants a new agent or assistant for some purpose: search published eggs (skill and persona packages) with `grix_egg_search` / `grix_egg_get`, present matches, and hatch the chosen one yourself from the package URLs `grix_egg_get` returns (via the `grix_egg` tool); only when nothing fits fall back to grix-admin. Hatching itself is program-driven: AI organizes parameters and calls `grix_egg`; the program handles creation, installation, binding, acceptance, and status reporting."
 ---
 
 # Grix Egg
 
+## 0. Discovery first — find an egg before creating an agent
+
+When the user describes an agent they want ("帮我建一个跟进外贸询盘的助手",
+"I need a bot that reviews PRs") and there is no install card yet, search the
+egg market before anything else; do **not** go to `grix-admin`.
+
+1. Distill the description into **2–4 short keywords** (role noun, domain,
+   core action). The backend ANDs terms against name + description +
+   category, so a whole sentence returns nothing.
+2. Call `grix_egg_search` **once per keyword** (`pageSize` 10) in the user's
+   language / `locale`; merge, rank by keyword hits then `install_count`. If
+   nothing matches, browse by `categoryId` with no keyword.
+3. Show at most 3–5 candidates: name (+ emoji), one-line description,
+   category, `install_count`, and whether it hatches a **new agent**
+   (`can_create_agent`) or installs as a **skill into an existing agent**
+   (`existing_agent_client_types`). `grix_egg_get` gives the full text.
+4. The user picks one → `grix_egg_get` returns the package URLs
+   (`persona_zip_url` / `skill_zip_url`, each with a `*_sha256`). Call
+   `grix_egg` with structured parameters (section 3, no install card):
+   `route: create_new` + `agentName` + `introduction` + `downloadUrl` =
+   `persona_zip_url` for a new agent, or `route: existing` + `downloadUrl`
+   for an existing one; pass the sha256 as `packageHash`. No `installId`
+   exists in this path, so no status card is sent.
+5. No egg fits, or the user explicitly wants a blank agent → hand over to
+   `grix-admin` and say clearly that no ready-made egg matched.
+
 `grix-egg` follows a "program-first, AI-assists" approach.
 AI no longer manually relays create/bind/accept.