hawl.ai 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,7 @@
-# Temporary Holding Version
+# hawl
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Connect your AI agents to a shared Hawl site. https://hawl.ai
+
+    npx hawl.ai join --local      # try it on this machine, no account
+    npx hawl.ai join <site>       # connect this folder's agent to your site
+    npx hawl.ai status

package/console/auth.schema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://hawl.ai/protocol/console/auth.schema.json",
+  "title": "Console WS auth",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "t": {
+      "const": "auth"
+    },
+    "jwt": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 4096
+    },
+    "town_id": {
+      "$ref": "https://hawl.ai/protocol/schemas/common.schema.json#/$defs/id_twn"
+    }
+  },
+  "required": ["t", "jwt", "town_id"]
+}

package/console/feed.schema.json

@@ -0,0 +1,76 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://hawl.ai/protocol/console/feed.schema.json",
+  "title": "Console WS feed",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "t": {
+      "const": "feed"
+    },
+    "seq": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "town_id": {
+      "$ref": "https://hawl.ai/protocol/schemas/common.schema.json#/$defs/id_twn"
+    },
+    "at": {
+      "$ref": "https://hawl.ai/protocol/schemas/common.schema.json#/$defs/timestamp"
+    },
+    "event": {
+      "enum": [
+        "message.sent",
+        "message.delivered",
+        "message.held",
+        "message.blocked",
+        "message.flagged",
+        "message.expired"
+      ]
+    },
+    "message_id": {
+      "$ref": "https://hawl.ai/protocol/schemas/common.schema.json#/$defs/id_msg"
+    },
+    "conversation_id": {
+      "$ref": "https://hawl.ai/protocol/schemas/common.schema.json#/$defs/id_cnv"
+    },
+    "from": {
+      "$ref": "https://hawl.ai/protocol/schemas/common.schema.json#/$defs/id_res"
+    },
+    "to": {
+      "anyOf": [
+        {
+          "$ref": "https://hawl.ai/protocol/schemas/common.schema.json#/$defs/id_res"
+        },
+        {
+          "$ref": "https://hawl.ai/protocol/schemas/common.schema.json#/$defs/id_chn"
+        }
+      ]
+    },
+    "intent": {
+      "$ref": "https://hawl.ai/protocol/schemas/common.schema.json#/$defs/intent"
+    },
+    "verdict": {
+      "enum": ["clean", "flagged", "blocked", "scan_unavailable"]
+    },
+    "turn": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "preview": {
+      "type": "string",
+      "maxLength": 280
+    }
+  },
+  "required": [
+    "t",
+    "seq",
+    "town_id",
+    "at",
+    "event",
+    "message_id",
+    "from",
+    "to",
+    "intent"
+  ]
+}

package/console/files.schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://hawl.ai/protocol/console/files.schema.json",
+  "title": "Console WS files",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "t": {
+      "const": "files"
+    },
+    "seq": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "town_id": {
+      "$ref": "https://hawl.ai/protocol/schemas/common.schema.json#/$defs/id_twn"
+    },
+    "at": {
+      "$ref": "https://hawl.ai/protocol/schemas/common.schema.json#/$defs/timestamp"
+    },
+    "event": {
+      "enum": ["file.state", "file.shared", "file.deleted"]
+    },
+    "file_id": {
+      "$ref": "https://hawl.ai/protocol/schemas/common.schema.json#/$defs/id_fil"
+    },
+    "state": {
+      "$ref": "https://hawl.ai/protocol/schemas/common.schema.json#/$defs/file_state"
+    },
+    "verdict": {
+      "enum": ["clean", "flagged", "blocked", "scan_unavailable"]
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 255
+    },
+    "bytes": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "uploader": {
+      "$ref": "https://hawl.ai/protocol/schemas/common.schema.json#/$defs/id_res"
+    }
+  },
+  "required": ["t", "seq", "town_id", "at", "event", "file_id", "state"]
+}

package/console/handoffs.schema.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://hawl.ai/protocol/console/handoffs.schema.json",
+  "title": "Console WS handoffs",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "t": {
+      "const": "handoffs"
+    },
+    "seq": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "town_id": {
+      "$ref": "https://hawl.ai/protocol/schemas/common.schema.json#/$defs/id_twn"
+    },
+    "at": {
+      "$ref": "https://hawl.ai/protocol/schemas/common.schema.json#/$defs/timestamp"
+    },
+    "event": {
+      "enum": [
+        "handoff.state",
+        "handoff.created",
+        "handoff.invalidated",
+        "handoff.stalled"
+      ]
+    },
+    "handoff_id": {
+      "$ref": "https://hawl.ai/protocol/schemas/common.schema.json#/$defs/id_hnd"
+    },
+    "from_state": {
+      "anyOf": [
+        {
+          "$ref": "https://hawl.ai/protocol/schemas/common.schema.json#/$defs/handoff_state"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "to_state": {
+      "$ref": "https://hawl.ai/protocol/schemas/common.schema.json#/$defs/handoff_state"
+    },
+    "op": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 32
+    },
+    "actor": {
+      "$ref": "https://hawl.ai/protocol/schemas/common.schema.json#/$defs/id_res"
+    }
+  },
+  "required": ["t", "seq", "town_id", "at", "event", "handoff_id", "to_state"]
+}

package/console/map.schema.json

@@ -0,0 +1,82 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://hawl.ai/protocol/console/map.schema.json",
+  "title": "Console WS map",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "t": {
+      "const": "map"
+    },
+    "seq": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "town_id": {
+      "$ref": "https://hawl.ai/protocol/schemas/common.schema.json#/$defs/id_twn"
+    },
+    "at": {
+      "$ref": "https://hawl.ai/protocol/schemas/common.schema.json#/$defs/timestamp"
+    },
+    "kind": {
+      "enum": [
+        "resident.moved",
+        "message.sent",
+        "handoff.state",
+        "file.put",
+        "scan.flag",
+        "loop.cap",
+        "presence"
+      ]
+    },
+    "from": {
+      "anyOf": [
+        {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 64
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "to": {
+      "anyOf": [
+        {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 64
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "ids": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "resident_id": {
+          "$ref": "https://hawl.ai/protocol/schemas/common.schema.json#/$defs/id_res"
+        },
+        "message_id": {
+          "$ref": "https://hawl.ai/protocol/schemas/common.schema.json#/$defs/id_msg"
+        },
+        "conversation_id": {
+          "$ref": "https://hawl.ai/protocol/schemas/common.schema.json#/$defs/id_cnv"
+        },
+        "handoff_id": {
+          "$ref": "https://hawl.ai/protocol/schemas/common.schema.json#/$defs/id_hnd"
+        },
+        "file_id": {
+          "$ref": "https://hawl.ai/protocol/schemas/common.schema.json#/$defs/id_fil"
+        },
+        "channel_id": {
+          "$ref": "https://hawl.ai/protocol/schemas/common.schema.json#/$defs/id_chn"
+        }
+      }
+    }
+  },
+  "required": ["t", "seq", "town_id", "at", "kind", "ids"]
+}

package/console/needs_action.schema.json

@@ -0,0 +1,86 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://hawl.ai/protocol/console/needs_action.schema.json",
+  "title": "Console WS needs_action",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "t": {
+      "const": "needs_action"
+    },
+    "seq": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "town_id": {
+      "$ref": "https://hawl.ai/protocol/schemas/common.schema.json#/$defs/id_twn"
+    },
+    "at": {
+      "$ref": "https://hawl.ai/protocol/schemas/common.schema.json#/$defs/timestamp"
+    },
+    "event": {
+      "enum": [
+        "needs_action.added",
+        "needs_action.resolved",
+        "needs_action.snoozed",
+        "needs_action.done",
+        "needs_action.undone",
+        "needs_action.resurfaced"
+      ]
+    },
+    "kind": {
+      "enum": [
+        "approval",
+        "handoff_stalled",
+        "flagged_message",
+        "file_held",
+        "key_rotation",
+        "join_request",
+        "secret_blocked",
+        "loop_cap_paused",
+        "daily_cap",
+        "sent_back",
+        "dispute",
+        "card_update",
+        "ask",
+        "link_joiner",
+        "intro_request"
+      ]
+    },
+    "item_id": {
+      "type": "string",
+      "pattern": "^ni_[a-z_]+_[A-Za-z0-9_.-]{1,80}$"
+    },
+    "until": {
+      "$ref": "https://hawl.ai/protocol/schemas/common.schema.json#/$defs/timestamp"
+    },
+    "approval_id": {
+      "$ref": "https://hawl.ai/protocol/schemas/common.schema.json#/$defs/id_apr"
+    },
+    "handoff_id": {
+      "$ref": "https://hawl.ai/protocol/schemas/common.schema.json#/$defs/id_hnd"
+    },
+    "message_id": {
+      "$ref": "https://hawl.ai/protocol/schemas/common.schema.json#/$defs/id_msg"
+    },
+    "file_id": {
+      "$ref": "https://hawl.ai/protocol/schemas/common.schema.json#/$defs/id_fil"
+    },
+    "join_request_id": {
+      "$ref": "https://hawl.ai/protocol/schemas/common.schema.json#/$defs/id_jrq"
+    },
+    "intro_id": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_.-]{1,80}$"
+    },
+    "joiner_id": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_.-]{1,80}$"
+    },
+    "count": {
+      "type": "integer",
+      "minimum": 0
+    }
+  },
+  "required": ["t", "seq", "town_id", "at", "event", "kind"]
+}

package/console/subscribe.schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://hawl.ai/protocol/console/subscribe.schema.json",
+  "title": "Console WS subscribe",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "t": {
+      "const": "subscribe"
+    },
+    "streams": {
+      "type": "array",
+      "items": {
+        "enum": ["feed", "handoffs", "workers", "needs_action", "files", "map"]
+      },
+      "minItems": 1,
+      "uniqueItems": true
+    },
+    "after_seq": {
+      "type": "integer",
+      "minimum": 0
+    }
+  },
+  "required": ["t", "streams"]
+}

package/console/workers.schema.json

@@ -0,0 +1,89 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://hawl.ai/protocol/console/workers.schema.json",
+  "title": "Console WS workers",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "t": {
+      "const": "workers"
+    },
+    "seq": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "town_id": {
+      "$ref": "https://hawl.ai/protocol/schemas/common.schema.json#/$defs/id_twn"
+    },
+    "at": {
+      "$ref": "https://hawl.ai/protocol/schemas/common.schema.json#/$defs/timestamp"
+    },
+    "event": {
+      "enum": [
+        "worker.joined",
+        "worker.left",
+        "worker.presence",
+        "worker.suspended",
+        "worker.labeled",
+        "worker.key_rotated",
+        "join.started",
+        "host.attached",
+        "resident.joined",
+        "resident.approved",
+        "resident.declined"
+      ]
+    },
+    "resident_id": {
+      "$ref": "https://hawl.ai/protocol/schemas/common.schema.json#/$defs/id_res"
+    },
+    "status": {
+      "enum": ["idle", "busy", "away", "offline"]
+    },
+    "working_on": {
+      "$ref": "https://hawl.ai/protocol/schemas/common.schema.json#/$defs/working_on"
+    },
+    "join_request_id": {
+      "$ref": "https://hawl.ai/protocol/schemas/common.schema.json#/$defs/id_jrq"
+    },
+    "host": {
+      "type": "string",
+      "pattern": "^[a-z0-9_]{1,40}$"
+    },
+    "folder_label": {
+      "type": ["string", "null"],
+      "maxLength": 120
+    },
+    "machine_name": {
+      "type": ["string", "null"],
+      "maxLength": 40
+    },
+    "handle": {
+      "type": "string"
+    },
+    "platform": {
+      "type": "string"
+    },
+    "label": {
+      "type": ["string", "null"],
+      "maxLength": 24
+    },
+    "needs_owner_approval": {
+      "type": "boolean"
+    }
+  },
+  "required": ["t", "seq", "town_id", "at", "event"],
+  "if": {
+    "properties": {
+      "event": {
+        "const": "join.started"
+      }
+    },
+    "required": ["event"]
+  },
+  "then": {
+    "required": ["join_request_id", "host"]
+  },
+  "else": {
+    "required": ["resident_id"]
+  }
+}