@wenathlan/devthink 1.1.16 → 2.0.2

package/schemas/plan.schema.json

@@ -0,0 +1,208 @@
+{
+  "$id": "devthink/protocolv2/plan.schema.json",
+  "version": "1.0.0",
+  "title": "the frozen plan, step and option contract of the api freeze",
+  "description": "freezes the plan, the step and the option grammar shapes: the plan carries its objective, origin and reviewed steps while every step carries its id, its frozen action kind, its target, value and reviewed json options; the review surface documents the approve and reject decisions with the plan states and no hard cap on the step count, because the plan grammar bounds nothing the review did not bound.",
+  "type": "object",
+  "plan": {
+    "description": "the frozen agent plan fields",
+    "type": "object",
+    "properties": {
+      "id": {
+        "type": "string",
+        "description": "the plan id"
+      },
+      "objective": {
+        "type": "string",
+        "description": "the plain language objective"
+      },
+      "origin": {
+        "type": "string",
+        "description": "the exact origin the plan runs inside"
+      },
+      "steps": {
+        "type": "array",
+        "description": "the reviewed steps in execution order with no hard cap on the count",
+        "items": {
+          "type": "object"
+        }
+      },
+      "createdat": {
+        "type": "number",
+        "description": "the epoch milliseconds the plan was created"
+      },
+      "expiresat": {
+        "type": "number",
+        "description": "the epoch milliseconds the plan expires"
+      },
+      "state": {
+        "type": "string",
+        "description": "the plan state of the frozen review surface",
+        "enum": [
+          "draft",
+          "pending",
+          "approved",
+          "rejected",
+          "expired",
+          "completed",
+          "cancelled"
+        ]
+      },
+      "approvedat": {
+        "type": "number",
+        "description": "the epoch milliseconds the human approved the plan"
+      },
+      "completedat": {
+        "type": "number",
+        "description": "the epoch milliseconds the plan completed"
+      }
+    },
+    "required": [
+      "id",
+      "objective",
+      "origin",
+      "steps",
+      "createdat",
+      "expiresat",
+      "state"
+    ]
+  },
+  "step": {
+    "description": "the frozen tool step fields",
+    "type": "object",
+    "properties": {
+      "id": {
+        "type": "string",
+        "description": "the step id"
+      },
+      "kind": {
+        "type": "string",
+        "description": "the frozen action kind identifier of the immutable vocabulary"
+      },
+      "target": {
+        "type": "string",
+        "description": "the reviewed css selector the step addresses"
+      },
+      "value": {
+        "type": "string",
+        "description": "the reviewed literal value the step carries"
+      },
+      "options": {
+        "type": "string",
+        "description": "the reviewed json options of the option grammar"
+      },
+      "summary": {
+        "type": "string",
+        "description": "the human readable summary the review reads"
+      },
+      "risk": {
+        "type": "string",
+        "description": "the derived risk class",
+        "enum": [
+          "read",
+          "interaction",
+          "sensitive"
+        ]
+      },
+      "idempotencykey": {
+        "type": "string",
+        "description": "the deterministic key replays deduplicate on"
+      },
+      "environment": {
+        "type": "string",
+        "description": "the execution environment the step names",
+        "enum": [
+          "pagecontext",
+          "isolatedworld",
+          "offscreenworker",
+          "sandboxframe"
+        ]
+      },
+      "agentid": {
+        "type": "string",
+        "description": "the fleet agent the step attributes to"
+      },
+      "intenthint": {
+        "type": "string",
+        "description": "the plain language navigation intent label"
+      }
+    },
+    "required": [
+      "id",
+      "kind",
+      "summary",
+      "risk"
+    ]
+  },
+  "options": {
+    "description": "the frozen option grammar field families of the reviewed step options",
+    "type": "object",
+    "properties": {
+      "targetref": {
+        "type": "object",
+        "description": "the reviewed element reference the page bridge resolves"
+      },
+      "modifiers": {
+        "type": "array",
+        "description": "the reviewed key modifiers of key steps",
+        "items": {
+          "type": "string"
+        }
+      },
+      "pipeline": {
+        "type": "string",
+        "description": "the extractpipeline reference of the extract steps"
+      },
+      "pollrequest": {
+        "type": "object",
+        "description": "the longpoll request grammar of a transport step"
+      },
+      "graphql": {
+        "type": "object",
+        "description": "the graphql subscription grammar of a channel step"
+      },
+      "correlation": {
+        "type": "object",
+        "description": "the per run request correlation map"
+      },
+      "ocr": {
+        "type": "boolean",
+        "description": "the flag that runs recognition on the stored capture bytes"
+      },
+      "vision": {
+        "type": "object",
+        "description": "the reviewed vision prompt block of a capture step"
+      },
+      "ocrregion": {
+        "type": "object",
+        "description": "the region grammar of a regionocr reading"
+      },
+      "naming": {
+        "type": "string",
+        "description": "the lowercase capture filename pattern"
+      },
+      "pair": {
+        "type": "string",
+        "description": "the beforeafter capture mode around a step"
+      },
+      "diff": {
+        "type": "boolean",
+        "description": "the flag that runs the diffshot comparison after a sensitive step"
+      },
+      "snapshot": {
+        "type": "object",
+        "description": "the session snapshot plan of a capturesession step"
+      }
+    }
+  },
+  "reviewsurface": {
+    "description": "the frozen review surface of the plan: the human approves or rejects a pending plan, the approve and reject runtime messages travel the background surface, and the review carries no hard cap on the step count, the expiry window or the option grammar depth because every bound the review honors stays a user choice",
+    "type": "object",
+    "messages": [
+      "approve",
+      "reject",
+      "preview",
+      "execute"
+    ]
+  }
+}

package/schemas/progress.schema.json

@@ -0,0 +1,126 @@
+{
+  "$id": "devthink/protocolv2/progress.schema.json",
+  "version": "1.0.0",
+  "title": "the frozen progress event contract of the api freeze",
+  "description": "freezes the progress event names and the progress record shape: the plan progress carries its completed steps, its outcomes, its task tabs and its per step environment, turnaround, gate wait, perf and delta records while the step outcome carries its ok flag, summary, details and environment; the event names of the record families join the frozen contract.",
+  "type": "object",
+  "eventnames": {
+    "description": "the frozen progress event name families of the progress record",
+    "values": [
+      "recordstep",
+      "recordoutcome",
+      "recordenvironment",
+      "recordturnaround",
+      "recordgatewait",
+      "recordperf",
+      "recorddeltas"
+    ]
+  },
+  "planprogress": {
+    "description": "the frozen plan progress fields",
+    "type": "object",
+    "properties": {
+      "planid": {
+        "type": "string",
+        "description": "the plan the progress tracks"
+      },
+      "runid": {
+        "type": "string",
+        "description": "the run record the progress links to"
+      },
+      "completedsteps": {
+        "type": "array",
+        "description": "the executed step ids in order",
+        "items": {
+          "type": "string"
+        }
+      },
+      "outcomes": {
+        "type": "array",
+        "description": "the step outcomes of the completed steps",
+        "items": {
+          "type": "object"
+        }
+      },
+      "tasktabs": {
+        "type": "array",
+        "description": "the tabs assigned to the running task",
+        "items": {
+          "type": "number"
+        }
+      },
+      "environments": {
+        "type": "object",
+        "description": "the execution environment of every completed step by step id"
+      },
+      "turnarounds": {
+        "type": "object",
+        "description": "the worker turnaround of every offloaded step by step id"
+      },
+      "gatewaits": {
+        "type": "object",
+        "description": "the gate wait evidence of every gated step by step id"
+      },
+      "perf": {
+        "type": "object",
+        "description": "the perf record of every executed step by step id"
+      },
+      "deltas": {
+        "type": "object",
+        "description": "the snapshot change set of every executed step by step id"
+      },
+      "prior": {
+        "type": "array",
+        "description": "the prior progress snapshots preserved across plan replacements",
+        "items": {
+          "type": "object"
+        }
+      },
+      "updatedat": {
+        "type": "number",
+        "description": "the epoch milliseconds of the last update"
+      }
+    },
+    "required": [
+      "planid",
+      "completedsteps",
+      "updatedat"
+    ]
+  },
+  "stepoutcome": {
+    "description": "the frozen step outcome fields",
+    "type": "object",
+    "properties": {
+      "stepid": {
+        "type": "string",
+        "description": "the step the outcome reports"
+      },
+      "ok": {
+        "type": "boolean",
+        "description": "the success flag of the outcome"
+      },
+      "summary": {
+        "type": "string",
+        "description": "the plain language summary of the outcome"
+      },
+      "details": {
+        "type": "object",
+        "description": "the structured payload of the outcome"
+      },
+      "environment": {
+        "type": "string",
+        "description": "the execution environment the step ran in"
+      },
+      "at": {
+        "type": "number",
+        "description": "the epoch milliseconds of the outcome"
+      }
+    },
+    "required": [
+      "stepid",
+      "ok",
+      "summary",
+      "at"
+    ]
+  }
+}

package/schemas/proposal.schema.json

@@ -0,0 +1,68 @@
+{
+  "$id": "devthink/protocolv2/proposal.schema.json",
+  "version": "1.0.0",
+  "title": "the frozen proposal request and response contract of the api freeze",
+  "description": "freezes the proposal request the endpoint receives and the plan proposal the protocol parses: the request carries the objective, the session record, the observation and the capability report while the response carries the versioned envelope, the plan and the optional resume, lock and agent markers; the response refuses every version outside the frozen protocol version.",
+  "type": "object",
+  "proposalrequest": {
+    "description": "the frozen proposal request fields",
+    "type": "object",
+    "properties": {
+      "objective": {
+        "type": "string",
+        "description": "the plain language objective the user reviews"
+      },
+      "session": {
+        "type": "object",
+        "description": "the session record of the requesting session as the session schema freezes it"
+      },
+      "observation": {
+        "type": "object",
+        "description": "the observation payload as the observation schema freezes it"
+      },
+      "capabilities": {
+        "type": "object",
+        "description": "the capability report as the capability schema freezes it"
+      }
+    },
+    "required": [
+      "objective",
+      "session",
+      "observation",
+      "capabilities"
+    ]
+  },
+  "proposalresponse": {
+    "description": "the frozen plan proposal fields of the versioned envelope",
+    "type": "object",
+    "properties": {
+      "version": {
+        "type": "string",
+        "description": "the frozen protocol version of the versioned envelope"
+      },
+      "plan": {
+        "type": "object",
+        "description": "the agent plan as the plan schema freezes it"
+      },
+      "resumedfrom": {
+        "type": "array",
+        "description": "the checkpointed step ids a resumed proposal marks",
+        "items": {
+          "type": "string"
+        }
+      },
+      "lockid": {
+        "type": "string",
+        "description": "the sessionlock the replay preserves"
+      },
+      "agentid": {
+        "type": "string",
+        "description": "the fleet agent that requested the plan"
+      }
+    },
+    "required": [
+      "version",
+      "plan"
+    ]
+  }
+}

package/schemas/session.schema.json

@@ -0,0 +1,82 @@
+{
+  "$id": "devthink/protocolv2/session.schema.json",
+  "version": "1.0.0",
+  "title": "the frozen session lifecycle contract of the api freeze",
+  "description": "freezes the session lifecycle messages and the session record shape of protocolv2: the startsession, pausesession and resumesession runtime messages travel the background surface while the session record rides every versioned envelope the proposal request carries; the lifecycle stays consent first because a paused or expired session refuses every action and preview.",
+  "type": "object",
+  "lifecycle": {
+    "description": "the frozen session lifecycle message names of the background surface",
+    "messages": [
+      "startsession",
+      "pausesession",
+      "resumesession"
+    ]
+  },
+  "sessionrecord": {
+    "description": "the frozen session record fields",
+    "type": "object",
+    "properties": {
+      "id": {
+        "type": "string",
+        "description": "the session id"
+      },
+      "tabid": {
+        "type": "number",
+        "description": "the tab the session binds"
+      },
+      "origin": {
+        "type": "string",
+        "description": "the exact origin the session runs inside"
+      },
+      "startedat": {
+        "type": "number",
+        "description": "the epoch milliseconds the session started"
+      },
+      "expiresat": {
+        "type": "number",
+        "description": "the epoch milliseconds the session expires; an expired session refuses every action"
+      },
+      "stoppedat": {
+        "type": "number",
+        "description": "the epoch milliseconds the user stopped the session"
+      },
+      "pausedat": {
+        "type": "number",
+        "description": "the epoch milliseconds the user paused the session; a paused session refuses every action and preview"
+      },
+      "grants": {
+        "type": "array",
+        "description": "the additional exact origins granted to the session",
+        "items": {
+          "type": "string"
+        }
+      },
+      "environmentgrants": {
+        "type": "array",
+        "description": "the execution environments granted beside the origin grants",
+        "items": {
+          "type": "string"
+        }
+      },
+      "lockid": {
+        "type": "string",
+        "description": "the sessionlock the running run acquired"
+      },
+      "agentid": {
+        "type": "string",
+        "description": "the fleet agent bound to the session"
+      },
+      "jarid": {
+        "type": "string",
+        "description": "the cookie jar the session cookie state stays scoped to"
+      }
+    },
+    "required": [
+      "id",
+      "tabid",
+      "origin",
+      "startedat",
+      "expiresat"
+    ]
+  }
+}

package/schemas/tool.schema.json

@@ -0,0 +1,94 @@
+{
+  "$id": "devthink/protocolv2/tool.schema.json",
+  "version": "1.0.0",
+  "title": "the frozen tool catalog entry contract of the api freeze",
+  "description": "freezes the tool catalog entry shape with the per tool versions the freeze pins: every tooldef carries its namespaced name, its version for compatibility checks, its plain language description with the openapi style field layout, its json schema inputs, its frozen action kind, its risk grade and the consent metadata of the tools with side effects; the four namespaces stay browser, workflow, memory and system while the catalog kinds join the frozen contract.",
+  "type": "object",
+  "namespaces": {
+    "description": "the frozen tool namespaces",
+    "values": [
+      "browser",
+      "workflow",
+      "memory",
+      "system"
+    ]
+  },
+  "tooldef": {
+    "description": "the frozen tool catalog entry fields",
+    "type": "object",
+    "properties": {
+      "name": {
+        "type": "string",
+        "description": "the namespaced tool name"
+      },
+      "version": {
+        "type": "number",
+        "description": "the per tool version frozen from this release on; every entry carries its own version for compatibility checks"
+      },
+      "description": {
+        "type": "string",
+        "description": "the plain language description that states the consent class and side effects with the openapi style field layout"
+      },
+      "inputschema": {
+        "type": "object",
+        "description": "the json schema of the tool inputs with typed properties, required markers and reviewed defaults"
+      },
+      "kind": {
+        "type": "string",
+        "description": "the frozen action kind the tool wraps",
+        "enum": [
+          "a11ytree",
+          "back",
+          "click",
+          "composeworkflow",
+          "dryrun",
+          "eventrule",
+          "extract",
+          "extractvars",
+          "forward",
+          "listruns",
+          "navigate",
+          "observe",
+          "presskey",
+          "readlinks",
+          "readmeta",
+          "readtable",
+          "readtext",
+          "reload",
+          "runworkflow",
+          "tabactivate",
+          "tabclose",
+          "tabcreate",
+          "tablist",
+          "trailaudit",
+          "type",
+          "windowclose",
+          "windowcreate",
+          "windowlist",
+          "windowresize"
+        ]
+      },
+      "risk": {
+        "type": "string",
+        "description": "the risk grade of the wrapped kind",
+        "enum": [
+          "read",
+          "interaction",
+          "sensitive"
+        ]
+      },
+      "consentmeta": {
+        "type": "object",
+        "description": "the consent metadata of a tool with side effects: the review requirement, the risk class, the approval gate requirement and the session origin scope"
+      }
+    },
+    "required": [
+      "name",
+      "version",
+      "description",
+      "inputschema",
+      "kind",
+      "risk"
+    ]
+  }
+}