{
  "$comment": "Source of truth for the operator class. PROFILE.md and SKILL.md are views and must not disagree. Second worked class here, chosen because it shares almost nothing with Calendar.",
  "id": "org.classprofiles.operator",
  "state": "draft",
  "title": "Operator",
  "summary": "Address a surface, read what is on it, act on one thing, and know when it has settled.",
  "ten_jobs": [
    "See which surfaces I am able to work with",
    "Read what is currently on one of them",
    "Find one control by what it does rather than where it sits",
    "Press a control",
    "Enter text into a field",
    "Know whether what I just did changed anything at all",
    "Wait until things stop moving before looking again",
    "Fail loudly when the thing I meant to use is gone",
    "Bring something further down into view",
    "Read the words on a surface without asking for pixels"
  ],
  "objects": {
    "Surface": {
      "type": "object",
      "required": [
        "id",
        "kind"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "kind": {
          "type": "string",
          "enum": [
            "browser",
            "desktop",
            "terminal",
            "other"
          ]
        },
        "label": {
          "type": "string"
        }
      }
    },
    "Target": {
      "type": "object",
      "required": [
        "ref",
        "role"
      ],
      "properties": {
        "ref": {
          "type": "string"
        },
        "role": {
          "type": "string"
        },
        "name": {
          "type": "string"
        }
      }
    },
    "Receipt": {
      "type": "object",
      "required": [
        "changed",
        "readiness"
      ],
      "properties": {
        "changed": {
          "type": "boolean"
        },
        "readiness": {
          "type": "string",
          "enum": [
            "settled",
            "changing",
            "loading"
          ]
        },
        "blocked_by": {
          "type": "string"
        }
      }
    }
  },
  "verbs": [
    {
      "id": "org.classprofiles.operator/list_surfaces@1",
      "name": "operator.list_surfaces",
      "tier": "baseline",
      "since": "org.classprofiles.operator/core@1",
      "summary": "Lists what can currently be seen and worked with.",
      "risk": {
        "readOnlyHint": true
      },
      "tool": {
        "inputSchema": {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "enum": [
                "browser",
                "desktop",
                "terminal",
                "other"
              ]
            }
          }
        }
      },
      "contract": {
        "structuredContent": {
          "type": "object",
          "required": [
            "surfaces"
          ],
          "properties": {
            "surfaces": {
              "type": "array",
              "items": {
                "$ref": "#/objects/Surface"
              }
            }
          }
        }
      },
      "example": {
        "request": {},
        "result": {
          "structuredContent": {
            "surfaces": [
              {
                "id": "sfc_2ab9",
                "kind": "browser",
                "label": "Reference document"
              }
            ]
          }
        }
      }
    },
    {
      "id": "org.classprofiles.operator/perceive@1",
      "name": "operator.perceive",
      "tier": "baseline",
      "since": "org.classprofiles.operator/core@1",
      "summary": "Returns the present state and the things that can be acted upon.",
      "risk": {
        "readOnlyHint": true
      },
      "$risk_note": "Reading is not marked open-world false: what a surface shows is decided elsewhere, unlike a calendar's own records.",
      "tool": {
        "inputSchema": {
          "type": "object",
          "required": [
            "surface_id"
          ],
          "properties": {
            "surface_id": {
              "type": "string"
            },
            "query": {
              "type": "string"
            },
            "limit": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          }
        }
      },
      "contract": {
        "structuredContent": {
          "type": "object",
          "required": [
            "targets",
            "readiness"
          ],
          "properties": {
            "targets": {
              "type": "array",
              "items": {
                "$ref": "#/objects/Target"
              }
            },
            "readiness": {
              "type": "string",
              "enum": [
                "settled",
                "changing",
                "loading"
              ]
            },
            "text": {
              "type": "string"
            },
            "next_cursor": {
              "type": "string"
            }
          }
        }
      },
      "example": {
        "request": {
          "surface_id": "sfc_2ab9",
          "query": "submit"
        },
        "result": {
          "structuredContent": {
            "targets": [
              {
                "ref": "e47",
                "role": "button",
                "name": "Submit"
              }
            ],
            "readiness": "settled"
          }
        }
      }
    },
    {
      "id": "org.classprofiles.operator/act@1",
      "name": "operator.act",
      "tier": "baseline",
      "since": "org.classprofiles.operator/core@1",
      "summary": "Performs a single input and reports what changed as a result.",
      "reissue": "at_most_once_unenforced",
      "socially_irreversible": true,
      "$risk_note": "No annotation is weakened. What an input does is decided by the surface, not by this service, so the pessimistic defaults are correct and a re-issue cannot be de-duplicated.",
      "tool": {
        "inputSchema": {
          "type": "object",
          "required": [
            "surface_id",
            "target",
            "action"
          ],
          "properties": {
            "surface_id": {
              "type": "string"
            },
            "target": {
              "type": "string"
            },
            "action": {
              "type": "string",
              "enum": [
                "press",
                "enter_text",
                "scroll",
                "hover"
              ]
            },
            "value": {
              "type": "string"
            }
          }
        }
      },
      "contract": {
        "structuredContent": {
          "$ref": "#/objects/Receipt"
        }
      },
      "example": {
        "request": {
          "surface_id": "sfc_2ab9",
          "target": "e47",
          "action": "press"
        },
        "result": {
          "structuredContent": {
            "changed": true,
            "readiness": "settled"
          }
        }
      }
    },
    {
      "id": "org.classprofiles.operator/settle@1",
      "name": "operator.settle",
      "tier": "baseline",
      "since": "org.classprofiles.operator/core@1",
      "summary": "Waits until nothing more is changing, or until the allowed time expires.",
      "risk": {
        "readOnlyHint": true
      },
      "tool": {
        "inputSchema": {
          "type": "object",
          "required": [
            "surface_id"
          ],
          "properties": {
            "surface_id": {
              "type": "string"
            },
            "wait_ms": {
              "type": "integer",
              "minimum": 0,
              "maximum": 30000,
              "default": 5000
            }
          }
        }
      },
      "contract": {
        "structuredContent": {
          "type": "object",
          "required": [
            "readiness"
          ],
          "properties": {
            "readiness": {
              "type": "string",
              "enum": [
                "settled",
                "changing",
                "loading"
              ]
            }
          }
        }
      },
      "example": {
        "request": {
          "surface_id": "sfc_2ab9"
        },
        "result": {
          "structuredContent": {
            "readiness": "settled"
          }
        }
      }
    },
    {
      "id": "org.classprofiles.operator/navigate@1",
      "name": "operator.navigate",
      "tier": "facet",
      "since": "operator/browser@1",
      "summary": "Sends a browsing surface to a new address.",
      "reissue": "at_most_once_unenforced",
      "socially_irreversible": true,
      "facet": "operator/browser@1",
      "degrades_to": {
        "target": null,
        "loss": "The surface cannot be sent anywhere; an agent can only work with what is already open.",
        "mode": "graceful"
      },
      "tool": {
        "inputSchema": {
          "type": "object",
          "required": [
            "surface_id",
            "url"
          ],
          "properties": {
            "surface_id": {
              "type": "string"
            },
            "url": {
              "type": "string"
            }
          }
        }
      },
      "contract": {
        "structuredContent": {
          "$ref": "#/objects/Receipt"
        }
      },
      "example": {
        "request": {
          "surface_id": "sfc_2ab9",
          "url": "https://example.org/docs"
        },
        "result": {
          "structuredContent": {
            "changed": true,
            "readiness": "loading"
          }
        }
      }
    },
    {
      "id": "org.classprofiles.operator/focus_app@1",
      "name": "operator.focus_app",
      "tier": "facet",
      "since": "operator/desktop@1",
      "summary": "Brings a named app to the front so it can be worked with.",
      "reissue": "idempotent",
      "facet": "operator/desktop@1",
      "degrades_to": {
        "target": null,
        "loss": "An application cannot be raised; an agent can only work with whatever already has focus.",
        "mode": "graceful"
      },
      "tool": {
        "inputSchema": {
          "type": "object",
          "required": [
            "surface_id",
            "application"
          ],
          "properties": {
            "surface_id": {
              "type": "string"
            },
            "application": {
              "type": "string"
            }
          }
        }
      },
      "contract": {
        "structuredContent": {
          "$ref": "#/objects/Receipt"
        }
      },
      "example": {
        "request": {
          "surface_id": "sfc_7c10",
          "application": "Text Editor"
        },
        "result": {
          "structuredContent": {
            "changed": true,
            "readiness": "settled"
          }
        }
      }
    },
    {
      "id": "org.classprofiles.operator/capture@1",
      "name": "operator.capture",
      "tier": "facet",
      "since": "operator/screenshot@1",
      "summary": "Returns a picture of the surface, with its measurements.",
      "risk": {
        "readOnlyHint": true
      },
      "facet": "operator/screenshot@1",
      "degrades_to": {
        "target": "org.classprofiles.operator/perceive@1",
        "loss": "No picture is available; an agent must work from the structured reading alone, which is cheaper but cannot show layout.",
        "mode": "graceful"
      },
      "tool": {
        "inputSchema": {
          "type": "object",
          "required": [
            "surface_id"
          ],
          "properties": {
            "surface_id": {
              "type": "string"
            }
          }
        }
      },
      "contract": {
        "structuredContent": {
          "type": "object",
          "required": [
            "width",
            "height"
          ],
          "properties": {
            "width": {
              "type": "integer"
            },
            "height": {
              "type": "integer"
            }
          }
        },
        "content": {
          "requires": [
            "image"
          ],
          "media_types": [
            "image/png"
          ]
        }
      },
      "example": {
        "request": {
          "surface_id": "sfc_2ab9"
        },
        "result": {
          "structuredContent": {
            "width": 1280,
            "height": 800
          }
        }
      }
    }
  ],
  "properties": [
    {
      "id": "org.classprofiles.operator/address@1",
      "name": "address",
      "tier": "facet",
      "since": "operator/browser@1",
      "attaches_to": [
        "objects/Surface"
      ],
      "summary": "Where a browsing surface currently points.",
      "facet": "operator/browser@1",
      "degrades_to": {
        "target": null,
        "loss": "An agent cannot tell where a browsing surface points, only what is on it.",
        "mode": "graceful"
      },
      "example": {
        "result": "https://example.org/docs"
      },
      "contract": {
        "type": "string"
      }
    },
    {
      "id": "org.classprofiles.operator/application@1",
      "name": "application",
      "tier": "facet",
      "since": "operator/desktop@1",
      "attaches_to": [
        "objects/Surface"
      ],
      "summary": "Which application owns a desktop surface.",
      "facet": "operator/desktop@1",
      "degrades_to": {
        "target": null,
        "loss": "An agent cannot tell which application it is working with, only what the surface shows.",
        "mode": "graceful"
      },
      "example": {
        "result": "Text Editor"
      },
      "contract": {
        "type": "string"
      }
    }
  ],
  "sandbox_contract": "Before every fixture scenario, implementations reset to a pinned reference surface with known structure and no user data, addressed through the identifier returned by operator.list_surfaces. The reference surface is 1280x800, is settled on arrival, and does not change on its own during a scenario. Semantics that require it to change underneath the caller are therefore outside what this sandbox can exercise and are declared unfixturable in PROFILE.md.",
  "licenses": {
    "spec": "Apache-2.0"
  },
  "baseline": "org.classprofiles.operator/core@1",
  "digest_note": "Draft artifacts are undigested and do not yet define canonical serialization. Publication is blocked until a later revision specifies reproducible canonical bytes.",
  "facets": [
    {
      "id": "operator/browser@1",
      "summary": "For agents that control a browser: send a surface to an address, and read where it points."
    },
    {
      "id": "operator/desktop@1",
      "summary": "For agents that control a desktop: raise an application, and read which one owns a surface."
    },
    {
      "id": "operator/screenshot@1",
      "summary": "For layout a structured reading cannot express: a picture, with its measurements."
    }
  ]
}