@clowder-ai/plugin-contract 0.1.0-beta.1 → 0.1.0-beta.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clowder-ai/plugin-contract",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.0-beta.10",
   "private": false,
   "description": "Clowder AI plugin contract — the single machine-readable truth source for plugin schema, types, capability table, and conformance fixtures (P15)",
   "license": "MIT",
@@ -10,8 +10,14 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./conformance": {
+      "types": "./dist/conformance/index.d.ts",
+      "import": "./dist/conformance/index.js"
+    },
     "./schemas/messaging": "./src/schemas/messaging.schema.json",
     "./schemas/manifest": "./src/schemas/manifest.schema.json",
+    "./schemas/signals": "./src/schemas/signal.schema.json",
+    "./schemas/physical-limb": "./src/schemas/physical-limb.schema.json",
     "./schemas/behavior-fixture": "./src/schemas/behavior-fixture.schema.json"
   },
   "main": "./dist/index.js",
@@ -27,9 +33,9 @@
   "scripts": {
     "generate": "node --import tsx src/codegen/generate-contract.ts",
     "generate:check": "node --import tsx src/codegen/generate-contract.ts --check",
-    "build": "pnpm clean && tsc -p tsconfig.build.json",
+    "build": "pnpm clean && tsc -p tsconfig.build.json && node --test scripts/conformance-public-boundary.test.mjs",
     "typecheck": "tsc --noEmit",
-    "test": "node --import tsx --test src/**/*.test.ts",
+    "test": "node --import tsx --test src/**/*.test.ts src/**/**/*.test.ts",
     "conformance": "node --import tsx src/conformance/runner.ts",
     "lint": "tsc --noEmit",
     "clean": "rm -rf dist",
@@ -37,11 +43,13 @@
   },
   "devDependencies": {
     "@types/node": "^20.17.0",
-    "ajv": "^8.17.0",
-    "ajv-formats": "^3.0.0",
     "tsx": "^4.19.0",
     "typescript": "^5.7.0"
   },
+  "dependencies": {
+    "ajv": "^8.17.0",
+    "ajv-formats": "^3.0.0"
+  },
   "publishConfig": {
     "access": "public"
   },

package/src/schemas/manifest.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://clowder-ai.dev/schemas/manifest/v0.1",
   "title": "Clowder AI Plugin Manifest (v0.1)",
-  "description": "Machine-readable truth source for plugin manifest (§3.4/§3.5). v0.1 covers core manifest + features + data classification. Signals/events (C-2) and schedule/state (C-3) are schema deltas in future contract versions.",
+  "description": "Machine-readable truth source for plugin manifest (§3.4/§3.5). beta.9 adds the C-2 declared-signal contribution while schedule/state (C-3) remain future contract deltas.",
   "x-clowder-capability-layers": {
     "L0": ["plugin.config.read", "plugin.state.get", "plugin.state.set"],
     "L1": ["messaging.send", "schedule.register", "events.publish", "messaging.appendElements"],
@@ -179,7 +179,10 @@
       "type": "array",
       "items": { "$ref": "#/$defs/DataDeclaration" }
     },
-    "runtime": { "$ref": "#/$defs/RuntimeDeclaration" }
+    "runtime": { "$ref": "#/$defs/RuntimeDeclaration" },
+    "signals": {
+      "$ref": "https://clowder-ai.dev/schemas/signals/v0.2#/$defs/SignalContribution"
+    }
   },
   "required": ["pluginId", "version", "contractVersion", "name", "features", "runtime"],
   "additionalProperties": false

package/src/schemas/messaging.schema.json

@@ -354,6 +354,7 @@
         "messageId": { "type": "string", "minLength": 1 },
         "threadId": { "type": "string", "minLength": 1 },
         "revision": { "type": "integer", "minimum": 1 },
+        "handle": { "$ref": "#/$defs/MessageHandle" },
         "publishSequence": { "type": "integer", "minimum": 0 }
       },
       "required": ["messageId", "threadId", "revision"],

package/src/schemas/physical-limb.schema.json

@@ -0,0 +1,319 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://clowder-ai.dev/schemas/physical-limb/v0.1",
+  "title": "Clowder AI Physical Limb Contribution (v0.1)",
+  "description": "Typed, bounded contract for a Host-governed physical limb contribution. Raw sensor media is intentionally absent.",
+  "x-clowder-physical-limb-grants": [
+    "limb.action.motion",
+    "limb.action.display",
+    "limb.action.light",
+    "limb.action.speaker",
+    "limb.observe.touch",
+    "limb.sensor.microphone",
+    "limb.sensor.camera"
+  ],
+  "x-clowder-physical-limb-bounds": {
+    "maxIdentifierLength": 128,
+    "maxTranscriptCodePoints": 4096,
+    "maxTouchDurationMs": 10000,
+    "minListenDurationMs": 100,
+    "maxListenDurationMs": 30000,
+    "maxActionTimeoutMs": 30000
+  },
+  "$defs": {
+    "PhysicalLimbIdentifier": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128
+    },
+    "PhysicalLimbGrant": {
+      "type": "string",
+      "enum": [
+        "limb.action.motion",
+        "limb.action.display",
+        "limb.action.light",
+        "limb.action.speaker",
+        "limb.observe.touch",
+        "limb.sensor.microphone",
+        "limb.sensor.camera"
+      ]
+    },
+    "PhysicalLimbSafePose": {
+      "type": "object",
+      "properties": {
+        "yawDeg": { "type": "number", "minimum": -90, "maximum": 90 },
+        "pitchDeg": { "type": "number", "minimum": -90, "maximum": 90 },
+        "timeoutMs": { "type": "integer", "minimum": 100, "maximum": 30000 }
+      },
+      "required": ["yawDeg", "pitchDeg", "timeoutMs"],
+      "additionalProperties": false
+    },
+    "PhysicalLimbContribution": {
+      "type": "object",
+      "properties": {
+        "contributionId": { "$ref": "#/$defs/PhysicalLimbIdentifier" },
+        "nodeType": { "$ref": "#/$defs/PhysicalLimbIdentifier" },
+        "displayName": { "type": "string", "minLength": 1, "maxLength": 128 },
+        "grants": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/PhysicalLimbGrant" },
+          "minItems": 1,
+          "maxItems": 7,
+          "uniqueItems": true
+        },
+        "safePose": { "$ref": "#/$defs/PhysicalLimbSafePose" }
+      },
+      "required": ["contributionId", "nodeType", "displayName", "grants", "safePose"],
+      "additionalProperties": false
+    },
+    "PhysicalLimbExpressionSource": {
+      "type": "object",
+      "properties": {
+        "kind": { "type": "string", "enum": ["cat_state", "play", "degraded"] },
+        "ref": { "$ref": "#/$defs/PhysicalLimbIdentifier" }
+      },
+      "required": ["kind", "ref"],
+      "additionalProperties": false
+    },
+    "PhysicalLimbTouchPayload": {
+      "type": "object",
+      "properties": {
+        "gesture": { "type": "string", "enum": ["tap", "stroke"] },
+        "durationMs": { "type": "integer", "minimum": 0, "maximum": 10000 },
+        "confidence": { "type": "number", "minimum": 0, "maximum": 1 }
+      },
+      "required": ["gesture", "durationMs", "confidence"],
+      "additionalProperties": false
+    },
+    "PhysicalLimbTranscriptPayload": {
+      "type": "object",
+      "properties": {
+        "interactionId": { "$ref": "#/$defs/PhysicalLimbIdentifier" },
+        "text": { "type": "string", "minLength": 1, "maxLength": 4096 },
+        "language": { "type": "string", "minLength": 1, "maxLength": 32 },
+        "captureDurationMs": { "type": "integer", "minimum": 100, "maximum": 30000 }
+      },
+      "required": ["interactionId", "text", "captureDurationMs"],
+      "additionalProperties": false
+    },
+    "PhysicalLimbTouchObservation": {
+      "type": "object",
+      "properties": {
+        "v": { "const": 1 },
+        "observationId": { "$ref": "#/$defs/PhysicalLimbIdentifier" },
+        "nodeId": { "$ref": "#/$defs/PhysicalLimbIdentifier" },
+        "occurredAt": { "type": "string", "format": "date-time" },
+        "sessionId": { "$ref": "#/$defs/PhysicalLimbIdentifier" },
+        "kind": { "const": "touch" },
+        "payload": { "$ref": "#/$defs/PhysicalLimbTouchPayload" }
+      },
+      "required": ["v", "observationId", "nodeId", "occurredAt", "sessionId", "kind", "payload"],
+      "additionalProperties": false
+    },
+    "PhysicalLimbTranscriptObservation": {
+      "type": "object",
+      "properties": {
+        "v": { "const": 1 },
+        "observationId": { "$ref": "#/$defs/PhysicalLimbIdentifier" },
+        "nodeId": { "$ref": "#/$defs/PhysicalLimbIdentifier" },
+        "occurredAt": { "type": "string", "format": "date-time" },
+        "sessionId": { "$ref": "#/$defs/PhysicalLimbIdentifier" },
+        "kind": { "const": "transcript" },
+        "payload": { "$ref": "#/$defs/PhysicalLimbTranscriptPayload" }
+      },
+      "required": ["v", "observationId", "nodeId", "occurredAt", "sessionId", "kind", "payload"],
+      "additionalProperties": false
+    },
+    "PhysicalLimbObservation": {
+      "oneOf": [
+        { "$ref": "#/$defs/PhysicalLimbTouchObservation" },
+        { "$ref": "#/$defs/PhysicalLimbTranscriptObservation" }
+      ]
+    },
+    "PhysicalLimbMotionPayload": {
+      "type": "object",
+      "properties": {
+        "yawDeg": { "type": "number", "minimum": -90, "maximum": 90 },
+        "pitchDeg": { "type": "number", "minimum": -90, "maximum": 90 },
+        "speedDps": { "type": "number", "exclusiveMinimum": 0, "maximum": 240 },
+        "accelerationDps2": { "type": "number", "exclusiveMinimum": 0, "maximum": 720 }
+      },
+      "required": ["yawDeg", "pitchDeg", "speedDps", "accelerationDps2"],
+      "additionalProperties": false
+    },
+    "PhysicalLimbDisplayPayload": {
+      "type": "object",
+      "properties": {
+        "expression": { "type": "string", "minLength": 1, "maxLength": 128 },
+        "expressionSource": { "$ref": "#/$defs/PhysicalLimbExpressionSource" }
+      },
+      "required": ["expression", "expressionSource"],
+      "additionalProperties": false
+    },
+    "PhysicalLimbRgb": {
+      "type": "array",
+      "items": { "type": "integer", "minimum": 0, "maximum": 255 },
+      "minItems": 3,
+      "maxItems": 3
+    },
+    "PhysicalLimbLightPayload": {
+      "type": "object",
+      "properties": {
+        "colors": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/PhysicalLimbRgb" },
+          "minItems": 1,
+          "maxItems": 256
+        }
+      },
+      "required": ["colors"],
+      "additionalProperties": false
+    },
+    "PhysicalLimbSpeakerPayload": {
+      "type": "object",
+      "properties": {
+        "text": { "type": "string", "minLength": 1, "maxLength": 4096 },
+        "voiceProfileRef": { "$ref": "#/$defs/PhysicalLimbIdentifier" },
+        "volumePercent": { "type": "integer", "minimum": 0, "maximum": 100 }
+      },
+      "required": ["text", "voiceProfileRef", "volumePercent"],
+      "additionalProperties": false
+    },
+    "PhysicalLimbMotionAction": {
+      "type": "object",
+      "properties": {
+        "v": { "const": 1 },
+        "actionId": { "$ref": "#/$defs/PhysicalLimbIdentifier" },
+        "nodeId": { "$ref": "#/$defs/PhysicalLimbIdentifier" },
+        "deadlineUnixMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
+        "timeoutMs": { "type": "integer", "minimum": 1, "maximum": 30000 },
+        "cancelToken": { "$ref": "#/$defs/PhysicalLimbIdentifier" },
+        "kind": { "const": "motion" },
+        "payload": { "$ref": "#/$defs/PhysicalLimbMotionPayload" }
+      },
+      "required": ["v", "actionId", "nodeId", "deadlineUnixMs", "timeoutMs", "cancelToken", "kind", "payload"],
+      "additionalProperties": false
+    },
+    "PhysicalLimbDisplayAction": {
+      "type": "object",
+      "properties": {
+        "v": { "const": 1 },
+        "actionId": { "$ref": "#/$defs/PhysicalLimbIdentifier" },
+        "nodeId": { "$ref": "#/$defs/PhysicalLimbIdentifier" },
+        "deadlineUnixMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
+        "timeoutMs": { "type": "integer", "minimum": 1, "maximum": 30000 },
+        "cancelToken": { "$ref": "#/$defs/PhysicalLimbIdentifier" },
+        "kind": { "const": "display" },
+        "payload": { "$ref": "#/$defs/PhysicalLimbDisplayPayload" }
+      },
+      "required": ["v", "actionId", "nodeId", "deadlineUnixMs", "timeoutMs", "cancelToken", "kind", "payload"],
+      "additionalProperties": false
+    },
+    "PhysicalLimbLightAction": {
+      "type": "object",
+      "properties": {
+        "v": { "const": 1 },
+        "actionId": { "$ref": "#/$defs/PhysicalLimbIdentifier" },
+        "nodeId": { "$ref": "#/$defs/PhysicalLimbIdentifier" },
+        "deadlineUnixMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
+        "timeoutMs": { "type": "integer", "minimum": 1, "maximum": 30000 },
+        "cancelToken": { "$ref": "#/$defs/PhysicalLimbIdentifier" },
+        "kind": { "const": "light" },
+        "payload": { "$ref": "#/$defs/PhysicalLimbLightPayload" }
+      },
+      "required": ["v", "actionId", "nodeId", "deadlineUnixMs", "timeoutMs", "cancelToken", "kind", "payload"],
+      "additionalProperties": false
+    },
+    "PhysicalLimbSpeakerAction": {
+      "type": "object",
+      "properties": {
+        "v": { "const": 1 },
+        "actionId": { "$ref": "#/$defs/PhysicalLimbIdentifier" },
+        "nodeId": { "$ref": "#/$defs/PhysicalLimbIdentifier" },
+        "deadlineUnixMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
+        "timeoutMs": { "type": "integer", "minimum": 1, "maximum": 30000 },
+        "cancelToken": { "$ref": "#/$defs/PhysicalLimbIdentifier" },
+        "kind": { "const": "speaker" },
+        "payload": { "$ref": "#/$defs/PhysicalLimbSpeakerPayload" }
+      },
+      "required": ["v", "actionId", "nodeId", "deadlineUnixMs", "timeoutMs", "cancelToken", "kind", "payload"],
+      "additionalProperties": false
+    },
+    "PhysicalLimbAction": {
+      "oneOf": [
+        { "$ref": "#/$defs/PhysicalLimbMotionAction" },
+        { "$ref": "#/$defs/PhysicalLimbDisplayAction" },
+        { "$ref": "#/$defs/PhysicalLimbLightAction" },
+        { "$ref": "#/$defs/PhysicalLimbSpeakerAction" }
+      ]
+    },
+    "PhysicalLimbCancel": {
+      "type": "object",
+      "properties": {
+        "v": { "const": 1 },
+        "nodeId": { "$ref": "#/$defs/PhysicalLimbIdentifier" },
+        "actionId": { "$ref": "#/$defs/PhysicalLimbIdentifier" },
+        "cancelToken": { "$ref": "#/$defs/PhysicalLimbIdentifier" },
+        "reason": { "type": "string", "enum": ["user", "timeout", "lease_lost", "host_lost", "superseded"] }
+      },
+      "required": ["v", "nodeId", "actionId", "cancelToken", "reason"],
+      "additionalProperties": false
+    },
+    "PhysicalLimbActionResult": {
+      "type": "object",
+      "properties": {
+        "v": { "const": 1 },
+        "actionId": { "$ref": "#/$defs/PhysicalLimbIdentifier" },
+        "nodeId": { "$ref": "#/$defs/PhysicalLimbIdentifier" },
+        "outcome": { "type": "string", "enum": ["succeeded", "refused", "failed", "canceled"] },
+        "reason": { "type": "string", "maxLength": 512 },
+        "observedAt": { "type": "string", "format": "date-time" }
+      },
+      "required": ["v", "actionId", "nodeId", "outcome", "observedAt"],
+      "additionalProperties": false
+    },
+    "PhysicalLimbReadinessReason": {
+      "type": "string",
+      "enum": [
+        "gateway_disconnected",
+        "device_disconnected",
+        "firmware_incompatible",
+        "sensor_unavailable",
+        "speech_dependency_missing",
+        "skin_unavailable",
+        "grant_revoked",
+        "host_unavailable"
+      ]
+    },
+    "PhysicalLimbReadyReadiness": {
+      "type": "object",
+      "properties": {
+        "v": { "const": 1 },
+        "nodeId": { "$ref": "#/$defs/PhysicalLimbIdentifier" },
+        "status": { "const": "ready" },
+        "observedAt": { "type": "string", "format": "date-time" }
+      },
+      "required": ["v", "nodeId", "status", "observedAt"],
+      "additionalProperties": false
+    },
+    "PhysicalLimbUnavailableReadiness": {
+      "type": "object",
+      "properties": {
+        "v": { "const": 1 },
+        "nodeId": { "$ref": "#/$defs/PhysicalLimbIdentifier" },
+        "status": { "type": "string", "enum": ["degraded", "offline"] },
+        "reason": { "$ref": "#/$defs/PhysicalLimbReadinessReason" },
+        "observedAt": { "type": "string", "format": "date-time" }
+      },
+      "required": ["v", "nodeId", "status", "reason", "observedAt"],
+      "additionalProperties": false
+    },
+    "PhysicalLimbReadiness": {
+      "oneOf": [
+        { "$ref": "#/$defs/PhysicalLimbReadyReadiness" },
+        { "$ref": "#/$defs/PhysicalLimbUnavailableReadiness" }
+      ]
+    }
+  },
+  "$ref": "#/$defs/PhysicalLimbContribution"
+}

package/src/schemas/signal.schema.json

@@ -0,0 +1,129 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://clowder-ai.dev/schemas/signals/v0.2",
+  "title": "Clowder AI Signal Ingress Contract (C-2)",
+  "description": "Declared external signals and the closed events.publish wire payload. Producer identity, provenance, grants, routing, and liveness are Host-bound and intentionally absent from plugin input.",
+  "x-clowder-payload-max-encoded-bytes": 65536,
+  "x-clowder-forbidden-privacy-classes": ["av-raw", "input-raw"],
+  "x-clowder-forbidden-source-classes": ["av-capture", "input-hardware"],
+  "$defs": {
+    "SignalType": {
+      "type": "string",
+      "minLength": 3,
+      "maxLength": 128,
+      "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_-]*)+$"
+    },
+    "SignalSchemaRef": {
+      "type": "string",
+      "description": "Package-local schema applied to the {payload, source} signal content at publish admission.",
+      "minLength": 21,
+      "maxLength": 256,
+      "pattern": "^schemas/([A-Za-z0-9][A-Za-z0-9._-]*/)*[A-Za-z0-9][A-Za-z0-9._-]*\\.schema\\.json$"
+    },
+    "SignalEpistemicStatus": {
+      "type": "string",
+      "enum": ["observation", "inference"]
+    },
+    "SignalPrivacyClass": {
+      "type": "string",
+      "enum": ["behavioral", "content-adjacent", "content", "av-raw", "input-raw"]
+    },
+    "AdmissibleSignalPrivacyClass": {
+      "type": "string",
+      "enum": ["behavioral", "content-adjacent", "content"]
+    },
+    "SignalSourceClass": {
+      "type": "string",
+      "enum": ["os-metadata", "accessibility-api", "remote-service", "av-capture", "input-hardware"]
+    },
+    "AdmissibleSignalSourceClass": {
+      "type": "string",
+      "enum": ["os-metadata", "accessibility-api", "remote-service"]
+    },
+    "SignalDeclaration": {
+      "type": "object",
+      "properties": {
+        "type": { "$ref": "#/$defs/SignalType" },
+        "schemaRef": { "$ref": "#/$defs/SignalSchemaRef" },
+        "epistemicStatus": { "$ref": "#/$defs/SignalEpistemicStatus" },
+        "privacyClass": { "$ref": "#/$defs/AdmissibleSignalPrivacyClass" },
+        "sourceClass": { "$ref": "#/$defs/AdmissibleSignalSourceClass" }
+      },
+      "required": ["type", "schemaRef", "epistemicStatus", "privacyClass", "sourceClass"],
+      "additionalProperties": false
+    },
+    "SignalContribution": {
+      "type": "object",
+      "properties": {
+        "provides": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/SignalDeclaration" },
+          "minItems": 1,
+          "maxItems": 64,
+          "uniqueItems": true
+        }
+      },
+      "required": ["provides"],
+      "additionalProperties": false
+    },
+    "SignalEventId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
+    },
+    "SignalIdempotencyKey": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 256,
+      "pattern": "^[^\\u0000-\\u001F\\u007F\\uD800-\\uDFFF]+$"
+    },
+    "OpaqueSourceHandle": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 512,
+      "pattern": "^[^\\u0000-\\u001F\\u007F\\uD800-\\uDFFF]+$"
+    },
+    "SignalSourceRef": {
+      "type": "object",
+      "properties": {
+        "handle": { "$ref": "#/$defs/OpaqueSourceHandle" }
+      },
+      "required": ["handle"],
+      "additionalProperties": false
+    },
+    "EventsPublishInput": {
+      "type": "object",
+      "properties": {
+        "signalType": { "$ref": "#/$defs/SignalType" },
+        "eventId": { "$ref": "#/$defs/SignalEventId" },
+        "idempotencyKey": { "$ref": "#/$defs/SignalIdempotencyKey" },
+        "occurredAt": {
+          "type": "string",
+          "format": "date-time",
+          "minLength": 20,
+          "maxLength": 30,
+          "pattern": "Z$"
+        },
+        "payload": { "type": "object", "additionalProperties": true },
+        "source": { "$ref": "#/$defs/SignalSourceRef" }
+      },
+      "required": ["signalType", "eventId", "idempotencyKey", "occurredAt", "payload", "source"],
+      "additionalProperties": false
+    },
+    "EventsPublishDisposition": {
+      "type": "string",
+      "enum": ["accepted", "duplicate"]
+    },
+    "EventsPublishResult": {
+      "type": "object",
+      "properties": {
+        "publicationId": { "$ref": "#/$defs/SignalEventId" },
+        "disposition": { "$ref": "#/$defs/EventsPublishDisposition" }
+      },
+      "required": ["publicationId", "disposition"],
+      "additionalProperties": false
+    }
+  },
+  "$ref": "#/$defs/EventsPublishInput"
+}