@semiont/backend 0.5.3 → 0.5.4

package/dist/openapi.json

@@ -256,10 +256,10 @@
         }
       }
     },
-    "/api/tokens/worker": {
+    "/api/tokens/agent": {
       "post": {
-        "summary": "Worker Token Exchange",
-        "description": "Exchange a shared secret for a bearer JWT. Used by workers and actors connecting to the EventBus.",
+        "summary": "Software-Agent Token Exchange",
+        "description": "Exchange the shared secret plus an inference (provider, model) pair for a bearer JWT issued for that agent identity. Used by worker processes that emit on behalf of one or more software peers.\n\nThe issued JWT carries the agent's DID (shape `did:web:<host>:agents:<provider>:<model>`); the bus stamps that DID onto `_userId` so events the agent emits attribute to the agent rather than to a generic worker pool.",
         "tags": [
           "Authentication"
         ],
@@ -273,11 +273,21 @@
                 "properties": {
                   "secret": {
                     "type": "string",
-                    "description": "The shared worker secret (SEMIONT_WORKER_SECRET)"
+                    "description": "The shared secret (SEMIONT_WORKER_SECRET)"
+                  },
+                  "provider": {
+                    "type": "string",
+                    "description": "Inference provider (e.g. ollama, anthropic)"
+                  },
+                  "model": {
+                    "type": "string",
+                    "description": "Model identifier (e.g. gemma2:27b, claude-3-5-sonnet)"
                   }
                 },
                 "required": [
-                  "secret"
+                  "secret",
+                  "provider",
+                  "model"
                 ]
               }
             }
@@ -294,17 +304,32 @@
                     "token": {
                       "type": "string",
                       "description": "Bearer JWT for subsequent authenticated requests"
+                    },
+                    "did": {
+                      "type": "string",
+                      "description": "DID of the software-agent identity the token is acting as"
                     }
                   },
                   "required": [
-                    "token"
+                    "token",
+                    "did"
                   ]
                 }
               }
             }
           },
+          "400": {
+            "description": "Missing or invalid request fields",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
           "401": {
-            "description": "Invalid worker secret",
+            "description": "Invalid agent secret",
             "content": {
               "application/json": {
                 "schema": {
@@ -314,7 +339,7 @@
             }
           },
           "503": {
-            "description": "Worker authentication not configured",
+            "description": "Agent authentication not configured",
             "content": {
               "application/json": {
                 "schema": {
@@ -1386,10 +1411,6 @@
                     "type": "string",
                     "description": "JSON-stringified array of entity type names"
                   },
-                  "creationMethod": {
-                    "type": "string",
-                    "description": "How this resource was created (api, ui, upload, reference, cli, clone, generated)"
-                  },
                   "sourceAnnotationId": {
                     "type": "string",
                     "description": "For AI-generated resources: the annotation that triggered generation. Nested into generatedFrom.annotationId on the persisted event."
@@ -1870,48 +1891,103 @@
         ]
       },
       "Agent": {
-        "type": "object",
-        "description": "Minimal Person/Organization for attribution (W3C PROV compatible)",
-        "additionalProperties": true,
-        "properties": {
-          "@id": {
-            "type": "string",
-            "format": "uri",
-            "description": "Unique identifier for the agent"
-          },
-          "@type": {
-            "description": "Type(s) of agent (Person, Organization, Software)",
-            "oneOf": [
-              {
+        "description": "Web Annotation / W3C PROV Agent. Discriminated by @type — Person, Organization, or Software. Each branch carries fields appropriate to its kind. Software peers are first-class participants, not a sub-class of Person.",
+        "oneOf": [
+          {
+            "type": "object",
+            "additionalProperties": true,
+            "properties": {
+              "@type": {
+                "type": "string",
+                "const": "Person"
+              },
+              "@id": {
+                "type": "string",
+                "format": "uri",
+                "description": "DID-shaped identifier (e.g. did:web:host:users:email%40host)"
+              },
+              "name": {
+                "type": "string",
+                "description": "Display name"
+              },
+              "nickname": {
                 "type": "string"
               },
-              {
-                "type": "array",
-                "items": {
-                  "type": "string"
-                },
-                "minItems": 1
+              "email": {
+                "type": "string"
+              },
+              "email_sha1": {
+                "type": "string"
+              },
+              "homepage": {
+                "type": "string"
               }
+            },
+            "required": [
+              "@type",
+              "name"
             ]
           },
-          "name": {
-            "type": "string"
-          },
-          "nickname": {
-            "type": "string"
-          },
-          "email": {
-            "type": "string"
-          },
-          "email_sha1": {
-            "type": "string"
+          {
+            "type": "object",
+            "additionalProperties": true,
+            "properties": {
+              "@type": {
+                "type": "string",
+                "const": "Organization"
+              },
+              "@id": {
+                "type": "string",
+                "format": "uri"
+              },
+              "name": {
+                "type": "string"
+              },
+              "homepage": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "@type",
+              "name"
+            ]
           },
-          "homepage": {
-            "type": "string"
+          {
+            "type": "object",
+            "additionalProperties": true,
+            "properties": {
+              "@type": {
+                "type": "string",
+                "const": "Software"
+              },
+              "@id": {
+                "type": "string",
+                "format": "uri",
+                "description": "DID-shaped identifier (e.g. did:web:host:agents:provider:model)"
+              },
+              "name": {
+                "type": "string",
+                "description": "Stable human-friendly label. Not parsed; UI composes display from structured fields."
+              },
+              "provider": {
+                "type": "string",
+                "description": "Inference provider (e.g. ollama, anthropic)"
+              },
+              "model": {
+                "type": "string",
+                "description": "Model identifier (e.g. gemma2:27b, claude-3-5-sonnet)"
+              },
+              "parameters": {
+                "type": "object",
+                "additionalProperties": true,
+                "description": "Inference parameters (temperature, maxTokens, systemPrompt, etc.). Runtime metadata, not part of identity."
+              }
+            },
+            "required": [
+              "@type",
+              "name"
+            ]
           }
-        },
-        "required": [
-          "name"
         ]
       },
       "Annotation": {
@@ -1969,7 +2045,8 @@
             "description": "W3C Web Annotation body. Optional per the W3C spec — annotations whose motivation alone is meaningful (highlighting) legitimately omit it. Present values are either a single body or a non-empty array of bodies; the prior empty-array 'stub' branch has been removed (it was a naming lie shared between highlights and never-actually-emitted stub references, and the source of the #651 reference-annotation validator bug)."
           },
           "creator": {
-            "$ref": "#/components/schemas/Agent"
+            "$ref": "#/components/schemas/Agent",
+            "description": "Web Annotation creator — the entity that initiated the annotation. For human-driven work this is a Person; for autonomous-agent work this is a Software peer."
           },
           "created": {
             "type": "string"
@@ -1978,7 +2055,34 @@
             "type": "string"
           },
           "generator": {
-            "$ref": "#/components/schemas/Agent"
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/Agent"
+              },
+              {
+                "type": "array",
+                "items": {
+                  "$ref": "#/components/schemas/Agent"
+                },
+                "minItems": 1
+              }
+            ],
+            "description": "Web Annotation generator — the SoftwareAgent that produced the annotation, when software was involved. Absent for purely manual annotations. Single object is the common case; array supports pipelines that combine multiple software peers."
+          },
+          "wasAttributedTo": {
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/Agent"
+              },
+              {
+                "type": "array",
+                "items": {
+                  "$ref": "#/components/schemas/Agent"
+                },
+                "minItems": 1
+              }
+            ],
+            "description": "PROV-O wasAttributedTo — all parties responsible for this annotation. For human-prompted AI work this combines `creator` (the Person) and `generator` (the Software). For purely manual annotations it equals `[creator]`; for autonomous-agent work it equals `[generator]` (and `creator` may be the same Software)."
           }
         },
         "required": [
@@ -3063,18 +3167,6 @@
           "contentByteSize": {
             "type": "integer"
           },
-          "creationMethod": {
-            "type": "string",
-            "enum": [
-              "api",
-              "upload",
-              "ui",
-              "reference",
-              "cli",
-              "clone",
-              "generated"
-            ]
-          },
           "entityTypes": {
             "type": "array",
             "items": {
@@ -3126,8 +3218,7 @@
         "required": [
           "name",
           "format",
-          "contentChecksum",
-          "creationMethod"
+          "contentChecksum"
         ]
       },
       "ResourceClonedPayload": {
@@ -3149,18 +3240,6 @@
           "parentResourceId": {
             "type": "string"
           },
-          "creationMethod": {
-            "type": "string",
-            "enum": [
-              "api",
-              "upload",
-              "ui",
-              "reference",
-              "cli",
-              "clone",
-              "generated"
-            ]
-          },
           "entityTypes": {
             "type": "array",
             "items": {
@@ -3175,8 +3254,7 @@
           "name",
           "format",
           "contentChecksum",
-          "parentResourceId",
-          "creationMethod"
+          "parentResourceId"
         ]
       },
       "ResourceUpdatedPayload": {
@@ -4316,19 +4394,6 @@
             "type": "boolean",
             "description": "Application-specific: Whether this resource is a draft"
           },
-          "creationMethod": {
-            "type": "string",
-            "enum": [
-              "api",
-              "upload",
-              "ui",
-              "reference",
-              "cli",
-              "clone",
-              "generated"
-            ],
-            "description": "Application-specific: How this resource was created"
-          },
           "sourceAnnotationId": {
             "type": "string",
             "description": "Application-specific: ID of annotation that triggered generation"
@@ -7131,9 +7196,6 @@
               "type": "string"
             }
           },
-          "creationMethod": {
-            "type": "string"
-          },
           "isDraft": {
             "type": "boolean"
           },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@semiont/backend",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "type": "module",
   "description": "Semiont backend server - pre-built for npm consumption",
   "main": "dist/index.js",
@@ -20,10 +20,10 @@
     "@hono/swagger-ui": "^0.6.1",
     "@prisma/adapter-pg": "^7.5.0",
     "@prisma/client": "^7.5.0",
-    "@semiont/core": "^0.5.3",
-    "@semiont/event-sourcing": "^0.5.3",
-    "@semiont/jobs": "^0.5.3",
-    "@semiont/make-meaning": "^0.5.3",
+    "@semiont/core": "^0.5.4",
+    "@semiont/event-sourcing": "^0.5.4",
+    "@semiont/jobs": "^0.5.4",
+    "@semiont/make-meaning": "^0.5.4",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "argon2": "^0.44.0",