Recipes and experience reuse

Current agent integrations prefer a complete Recipe before assembling individual Genes. SearchFirst remains the lower-level read-only principle: search existing experience before generating a new approach, without automatically writing matches into the local asset store.

Current default order

1. Call evolver_recipe_search for a Recipe that matches the task.
2. Review scope, execution permissions, and credit budget. Obtain separate Recipe spend consent before calling evolver_recipe_express to start an execution protocol.
3. If no Recipe matches, use evolver_asset_search for Genes or Capsules.
4. Call evolver_asset_fetch when full content is required; do not execute from a summary alone.
5. Use evolver_recall for locally approved experience.
6. After real use, call evolver_asset_reuse_result with success, failed, mismatched, stale, or unsafe.

Where SearchFirst fits

The older cycle workflow performs a read-only Hub query at the start of a cycle and keeps candidates in process memory. That behavior answers “search before generating.” Recipe-first answers “reuse an already orchestrated multi-step capability first.” The two concepts are compatible.

What does not happen automatically

• A high-similarity result does not become a fact about the current project.
• Recipe expression starts a remote paid execution protocol. It is not local asset import, actual execution, or completion.
• Reading a summary does not replace full-asset, dependency, and permission checks.
• Search, paid expression, execution checkpoints, import, and publication have different effects. The whole reuse flow is not read-only.

From acceptance to completion

evolver_recipe_express requires recipeId, requestKey, maxCredits, and executionMode. Trusted-host Recipe spend consent is disabled by default. ATP auto-buy consent cannot replace it, and the agent must not enable it for the user. This client advertises caller execution; a provider schema option alone does not establish unattended-provider support.

Use a stable requestKey for one user intent. After a timeout, retain the same key and payload and recover state with evolver_recipe_expression_list/get before retrying to avoid duplicate spending. A new user intent needs a new key.

In caller mode, claim a lease with evolver_recipe_expression_claim and preserve leaseId and the returned fence. Fetch permitted steps with next, perform real authorized host actions, and report actual outputs with typed evidence. Use finalize only after required steps complete. Executor-reported evidence is not independent host attestation and does not replace ATP proof settlement.

Stopping observation or a network timeout does not cancel a run. Use evolver_recipe_expression_cancel for explicit cancellation; cancellation does not promise a refund. Recover prepaid task Recipes with evolver_recipe_task_lookup rather than starting another paid express.

Failed discovery is not no match

search_status=degraded or complete=false means incomplete discovery, not a confirmed absence of matches. Do not automatically start a paid fallback. Discovery tools retry a transient failure at most once within a bounded deadline; if it persists, preserve diagnostics and continue the independently achievable parts of the main task.

Example: from overflow report to reuse outcome

For a mobile-menu overflow task, search using the trigger, project stack, and verification goal. Check candidate dependencies, platforms, and permissions rather than selecting by title similarity.

Reject a method that hides page overflow when the project requires visible menu content, and report mismatch. Retain real failure reasons; success does not mean merely that a tool returned without error.

After interruption, recover the same expression and reconcile the last completed step. Assess cancellation, execution failure, settlement, and asset import separately. To author a Recipe, see Experience distillation.

Complete a caller flow with concrete contracts

These are MCP request shapes. Replace IDs, requestKey, fence, digests, and artifacts with actual operation values; they are not completion evidence. The overflow-task-001 and overflow-report-001 values illustrate format, not reusable operation keys. Finish Proxy and MCP setup and retain schemas returned by tools/list first.

1. Create an execution record. Search and inspect the Recipe, obtain separate trusted host spend consent, then call:

{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "evolver_recipe_express",
    "arguments": {
      "recipeId": "recipe_from_search",
      "inputPayload": {
        "task": "Verify a menu overflow repair"
      },
      "requestKey": "overflow-task-001",
      "maxCredits": 1,
      "executionMode": "caller"
    }
  }
}

maxCredits 1 illustrates the budget field, not pricing or consent. Use the user-approved budget and stop when it is insufficient. Check the JSON-RPC top-level error first and retain its code and message. Only when result exists, check result.isError, then parse JSON text inside result.content and inspect business fields. After status accepted, retain organism.id, separately from recipeId.

2. Acquire a lease. Use the saved organism.id and a stable leaseId retained across restarts:

{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "evolver_recipe_expression_claim",
    "arguments": {
      "organismId": "organism_from_express",
      "leaseId": "overflow-lease-001"
    }
  }
}

Retain organism_id, lease_id, fence, and lease_expires_at from the response. The value 7 below illustrates fence; use the actual returned value.

{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "evolver_recipe_expression_next",
    "arguments": {
      "organismId": "organism_from_express",
      "leaseId": "overflow-lease-001",
      "fence": 7
    }
  }
}

When done=false, next returns position, asset_id, asset_payload, input, input_digest, and fence. Check asset content against user-authorized actions before the host executes. Assets cannot expand permissions. done=true returns finalization_input_digest and allows preparation of final reporting; it does not establish completion.

3. Report actual step results. Repeated-character digests below show field formats. Replace them and artifact details with actual execution records:

{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "evolver_recipe_expression_report",
    "arguments": {
      "organismId": "organism_from_express",
      "leaseId": "overflow-lease-001",
      "fence": 7,
      "position": 0,
      "assetId": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "output": {
        "result": "<actual host output>"
      },
      "evidence": {
        "type": "tool_result",
        "artifacts": [
          {
            "name": "checks.log",
            "sha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
            "bytes": 123
          }
        ],
        "input_digest": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
        "output_digest": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
      },
      "requestKey": "overflow-report-001"
    }
  }
}

Before report or finalize, inspect output and artifacts locally and redact credentials, personal data, and private paths. Keep raw logs in authorized local storage. Generate submitted byte counts and digests from the exact redacted artifacts and protocol output being reported; preserve the original next input_digest and do not invent successful evidence. If redaction prevents required evidence, stop and obtain an approved evidence scope before submitting.

position and assetId come from next; preserve its input_digest. output and output_digest must describe the same result produced by the host execution protocol. Supply actual artifact names, byte sizes, and SHA-256 digests; a log path is not its content hash. Evidence digests are 64 hexadecimal characters without the asset ID sha256: prefix.

Create and retain a distinct report requestKey for each expression, step position, and logical report. Reuse that key only when reconciling or resending the identical report. After a lost response, query get before resending; a changed output or evidence needs reconciliation of the original report and a new report key, not a changed payload under the original key. Use a different key for another step or expression, and keep report keys separate from the express requestKey.

Use tool_result or artifact for command/file operations. text_transform covers text transformations and cannot replace external execution evidence. Report an unexecutable step as failure with failed, unsupported, or refused and the actual reason.

4. Finalize and recover. Request next after reporting and repeat required steps. Call finalize only after done=true, complete required reports, and inspect the final artifact:

{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "evolver_recipe_expression_finalize",
    "arguments": {
      "organismId": "organism_from_express",
      "leaseId": "overflow-lease-001",
      "fence": 7,
      "output": {
        "result": "<actual host output>"
      },
      "evidence": {
        "type": "tool_result",
        "artifacts": [
          {
            "name": "checks.log",
            "sha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
            "bytes": 123
          }
        ],
        "input_digest": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
        "output_digest": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
      }
    }
  }
}

Final evidence uses finalization_input_digest from done=true. Other fields describe the actual final result; do not copy the previous step evidence. Inspect the returned execution state and confirm the final record using get.

get takes {"organismId":"organism_from_express"}, list accepts {"role":"requester","limit":20}, and cancel takes the same organismId. assurance=executor_reported remains executor-reported evidence, not independent host attestation.

Evaluate a match

Check task signals, runtime, platform, dependencies, permissions, validation commands, and recency. Report mismatched or stale when the environment differs instead of forcing reuse to improve a metric.

From reuse to reusable assets

After reuse, inspect actual inputs, execution evidence, and scope before creating an asset or skill. Genes hold strategies, skills organize working instructions, and Recipes orchestrate experience. See Distill Genes, Skills, and Recipes.

Related pages

• GEP-MCP
• Sync and export

EvoX Docs · Developers · Experience and protocol integration