@semiont/backend 0.5.2 → 0.5.4

package/dist/index.js

@@ -3,7 +3,7 @@ import winston from 'winston';
 import { recordSubscriberConnect, recordSubscriberDisconnect, withTraceparent, withSpan, recordBusEmit, SpanKind, injectTraceparent, getLogTraceContext } from '@semiont/observability';
 import { z } from 'zod';
 import jwt from 'jsonwebtoken';
-import { email, userId, googleCredential, EventBus, accessToken, resourceId, CHANNEL_SCHEMAS, userToDid, busLog, getPrimaryMediaType, decodeRepresentation } from '@semiont/core';
+import { email, userId, googleCredential, agentToDid, EventBus, accessToken, userToDid, resourceId, CHANNEL_SCHEMAS, busLog, getPrimaryMediaType, decodeRepresentation } from '@semiont/core';
 import { cors } from 'hono/cors';
 import { serve } from '@hono/node-server';
 import { Hono } from 'hono';
@@ -180,6 +180,12 @@ var init_jwt_types = __esm({
       domain: z.string(),
       provider: z.string(),
       isAdmin: z.boolean(),
+      // For software-agent tokens: the agent's DID is asserted by the auth
+      // route (which knows the (inferenceProvider, model) the token is being
+      // issued for) and carried on the JWT. The bus uses this directly as
+      // `_userId` instead of recomputing `userToDid(user)`. Unset for human
+      // tokens.
+      agentDid: z.string().optional(),
       iat: z.number().optional(),
       exp: z.number().optional()
     });
@@ -222,6 +228,18 @@ var init_jwt = __esm({
         }
         return this.siteConfig;
       }
+      /**
+       * Get the deployment domain to use for issuing agent identities.
+       * Used by `/api/tokens/agent` to mint DIDs of the shape
+       * `did:web:<domain>:agents:<provider>:<model>`.
+       */
+      static getDomainForAgent() {
+        const config2 = this.getSiteConfig();
+        if (!config2.domain) {
+          throw new Error("site.domain is required to issue agent tokens");
+        }
+        return config2.domain;
+      }
       /**
        * Override configuration for testing purposes
        * @param config The configuration to use
@@ -10538,48 +10556,103 @@ var openapi_default = {
         ]
       },
       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 \u2014 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: {
@@ -10637,7 +10710,8 @@ var openapi_default = {
             description: "W3C Web Annotation body. Optional per the W3C spec \u2014 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 \u2014 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"
@@ -10646,7 +10720,34 @@ var openapi_default = {
             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 \u2014 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 \u2014 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: [
@@ -11731,18 +11832,6 @@ var openapi_default = {
           contentByteSize: {
             type: "integer"
           },
-          creationMethod: {
-            type: "string",
-            enum: [
-              "api",
-              "upload",
-              "ui",
-              "reference",
-              "cli",
-              "clone",
-              "generated"
-            ]
-          },
           entityTypes: {
             type: "array",
             items: {
@@ -11794,8 +11883,7 @@ var openapi_default = {
         required: [
           "name",
           "format",
-          "contentChecksum",
-          "creationMethod"
+          "contentChecksum"
         ]
       },
       ResourceClonedPayload: {
@@ -11817,18 +11905,6 @@ var openapi_default = {
           parentResourceId: {
             type: "string"
           },
-          creationMethod: {
-            type: "string",
-            enum: [
-              "api",
-              "upload",
-              "ui",
-              "reference",
-              "cli",
-              "clone",
-              "generated"
-            ]
-          },
           entityTypes: {
             type: "array",
             items: {
@@ -11843,8 +11919,7 @@ var openapi_default = {
           "name",
           "format",
           "contentChecksum",
-          "parentResourceId",
-          "creationMethod"
+          "parentResourceId"
         ]
       },
       ResourceUpdatedPayload: {
@@ -11988,6 +12063,18 @@ var openapi_default = {
           "entityType"
         ]
       },
+      TagSchemaAddedPayload: {
+        type: "object",
+        description: "Payload for frame:tag-schema-added domain event (system-level, no resourceId \u2014 fan-out is global to the KB).",
+        properties: {
+          schema: {
+            $ref: "#/components/schemas/TagSchema"
+          }
+        },
+        required: [
+          "schema"
+        ]
+      },
       EntityTagChangedPayload: {
         type: "object",
         description: "Payload for mark:entity-tag-added and mark:entity-tag-removed domain events",
@@ -12398,6 +12485,20 @@ var openapi_default = {
           "entityReferences"
         ]
       },
+      GetTagSchemasResponse: {
+        type: "object",
+        properties: {
+          tagSchemas: {
+            type: "array",
+            items: {
+              $ref: "#/components/schemas/TagSchema"
+            }
+          }
+        },
+        required: [
+          "tagSchemas"
+        ]
+      },
       GoogleAuthRequest: {
         type: "object",
         properties: {
@@ -12958,19 +13059,6 @@ var openapi_default = {
             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"
@@ -14162,6 +14250,34 @@ var openapi_default = {
           "path"
         ]
       },
+      BrowseTagSchemasRequest: {
+        type: "object",
+        description: "Request to browse registered tag schemas",
+        properties: {
+          correlationId: {
+            type: "string"
+          }
+        },
+        required: [
+          "correlationId"
+        ]
+      },
+      BrowseTagSchemasResult: {
+        type: "object",
+        description: "Result of browsing tag schemas",
+        properties: {
+          correlationId: {
+            type: "string"
+          },
+          response: {
+            $ref: "#/components/schemas/GetTagSchemasResponse"
+          }
+        },
+        required: [
+          "correlationId",
+          "response"
+        ]
+      },
       FragmentSelector: {
         type: "object",
         description: "W3C Web Annotation FragmentSelector for media fragment identifiers (RFC 3778 for PDFs)",
@@ -15022,6 +15138,22 @@ var openapi_default = {
           "tag"
         ]
       },
+      FrameAddTagSchemaCommand: {
+        type: "object",
+        description: "Bus command to register a tag schema with the KB's runtime registry. Carried on the `frame:add-tag-schema` channel \u2014 Frame is the schema-layer flow that owns vocabulary writes. Most-recent registration of a given `schema.id` wins; the projection reflects the latest content. Identical re-registrations are silent; differing content overwrites and logs a warning.",
+        properties: {
+          schema: {
+            $ref: "#/components/schemas/TagSchema"
+          },
+          _userId: {
+            type: "string",
+            description: "Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this."
+          }
+        },
+        required: [
+          "schema"
+        ]
+      },
       MarkArchiveCommand: {
         type: "object",
         description: "Bus command to archive a resource and optionally remove its file.",
@@ -15558,6 +15690,61 @@ var openapi_default = {
           "value"
         ]
       },
+      TagCategory: {
+        type: "object",
+        description: "A single category within a tag schema (e.g. 'Issue' in IRAC, 'distinguished' in legal-citation-treatment). Each category carries methodology-bound semantics: a name, a description, and examples used in the LLM prompt.",
+        properties: {
+          name: {
+            type: "string"
+          },
+          description: {
+            type: "string"
+          },
+          examples: {
+            type: "array",
+            items: {
+              type: "string"
+            }
+          }
+        },
+        required: [
+          "name",
+          "description",
+          "examples"
+        ]
+      },
+      TagSchema: {
+        type: "object",
+        description: "A structural-analysis schema (e.g. legal-irac, scientific-imrad, argument-toulmin). Defines a methodology framework as an id, name, description, domain hint, and an ordered list of categories. KBs and their skills register schemas with the runtime registry via `frame.addTagSchema(...)` at session start.",
+        properties: {
+          id: {
+            type: "string"
+          },
+          name: {
+            type: "string"
+          },
+          description: {
+            type: "string"
+          },
+          domain: {
+            type: "string",
+            description: "Free-form domain hint (e.g. 'legal', 'scientific', 'general'). Used in the LLM prompt to tune the model's analysis voice. KB authors choose."
+          },
+          tags: {
+            type: "array",
+            items: {
+              $ref: "#/components/schemas/TagCategory"
+            }
+          }
+        },
+        required: [
+          "id",
+          "name",
+          "description",
+          "domain",
+          "tags"
+        ]
+      },
       YieldCloneCreateCommand: {
         type: "object",
         description: "Bus command to create a cloned resource from a clone token.",
@@ -15674,9 +15861,6 @@ var openapi_default = {
               type: "string"
             }
           },
-          creationMethod: {
-            type: "string"
-          },
           isDraft: {
             type: "boolean"
           },
@@ -15770,57 +15954,6 @@ var openapi_default = {
           "toUri"
         ]
       },
-      YieldRequestCommand: {
-        type: "object",
-        description: "Bus command to request yield (generation) of a new resource from an annotation.",
-        properties: {
-          correlationId: {
-            type: "string",
-            description: "Client-supplied id used to match this command to its result event(s) on the events-stream. Generated by the route handler if absent."
-          },
-          annotationId: {
-            type: "string"
-          },
-          resourceId: {
-            type: "string"
-          },
-          options: {
-            type: "object",
-            properties: {
-              title: {
-                type: "string"
-              },
-              prompt: {
-                type: "string"
-              },
-              language: {
-                type: "string"
-              },
-              temperature: {
-                type: "number"
-              },
-              maxTokens: {
-                type: "integer"
-              },
-              context: {
-                $ref: "#/components/schemas/GatheredContext"
-              },
-              storageUri: {
-                type: "string"
-              }
-            },
-            required: [
-              "title",
-              "storageUri"
-            ]
-          }
-        },
-        required: [
-          "annotationId",
-          "resourceId",
-          "options"
-        ]
-      },
       YieldUpdateCommand: {
         type: "object",
         description: "Bus command to update a yielded resource's storage content.",
@@ -16066,7 +16199,15 @@ var OAuthService = class {
     const refreshToken = JWTService.generateToken(jwtPayload, "30d");
     return { user, token, refreshToken, isNewUser };
   }
-  static async getUserFromToken(token) {
+  /**
+   * Resolve a JWT to its authenticated principal — the User row plus the
+   * principal's DID when the token was issued for a software agent. The
+   * `agentDid` is set by `/api/tokens/agent` and is the read-side
+   * inverse of "who is this token *acting as*?" — bus middleware uses it
+   * directly so emits attribute to the agent rather than the synthetic
+   * service-account User backing the token.
+   */
+  static async getPrincipalFromToken(token) {
     const payload = JWTService.verifyToken(token);
     if (!payload.userId) {
       throw new Error("Invalid token: missing userId");
@@ -16078,7 +16219,7 @@ var OAuthService = class {
     if (!user || !user.isActive) {
       throw new Error("User not found or inactive");
     }
-    return user;
+    return payload.agentDid ? { user, agentDid: payload.agentDid } : { user };
   }
   static async acceptTerms(userId2) {
     const prisma2 = DatabaseConnection.getClient();
@@ -16135,9 +16276,10 @@ var authMiddleware = async (c, next) => {
     return c.json({ error: "Unauthorized" }, 401);
   }
   try {
-    const user = await OAuthService.getUserFromToken(accessToken(tokenStr));
+    const { user, agentDid } = await OAuthService.getPrincipalFromToken(accessToken(tokenStr));
     c.set("user", user);
     c.set("token", tokenStr);
+    c.set("principalDid", agentDid ?? userToDid(user));
     logger2.debug("Authentication successful", {
       type: "auth_success",
       userId: user.id,
@@ -16522,10 +16664,10 @@ authRouter.post("/api/tokens/mcp-generate", authMiddleware, async (c) => {
     return c.json({ error: "Failed to generate refresh token" }, 401);
   }
 });
-authRouter.post("/api/tokens/worker", async (c) => {
+authRouter.post("/api/tokens/agent", async (c) => {
   const workerSecret = process.env.SEMIONT_WORKER_SECRET;
   if (!workerSecret) {
-    return c.json({ error: "Worker authentication not configured" }, 503);
+    return c.json({ error: "Agent authentication not configured" }, 503);
   }
   let body;
   try {
@@ -16534,24 +16676,51 @@ authRouter.post("/api/tokens/worker", async (c) => {
     return c.json({ error: "Invalid request body" }, 400);
   }
   if (body.secret !== workerSecret) {
-    return c.json({ error: "Invalid worker secret" }, 401);
-  }
+    return c.json({ error: "Invalid agent secret" }, 401);
+  }
+  if (!body.provider || typeof body.provider !== "string") {
+    return c.json({ error: "provider is required" }, 400);
+  }
+  if (!body.model || typeof body.model !== "string") {
+    return c.json({ error: "model is required" }, 400);
+  }
+  const inferenceProvider = body.provider;
+  const model = body.model;
+  const siteDomain = JWTService.getDomainForAgent();
+  const emailHost = siteDomain.split(":")[0];
+  const providerId = `${inferenceProvider}:${model}`;
+  const slug = providerId.replace(/[^a-zA-Z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
+  const agentEmail = `${slug}@agents.${emailHost}`;
+  const agentName = `${inferenceProvider} ${model}`;
   const prisma2 = DatabaseConnection.getClient();
-  const workerUser = await prisma2.user.findUnique({
-    where: { email: "worker@semiont.local" }
+  const agentUser = await prisma2.user.upsert({
+    where: { provider_providerId: { provider: "agent", providerId } },
+    update: {
+      name: agentName,
+      isActive: true,
+      lastLogin: /* @__PURE__ */ new Date()
+    },
+    create: {
+      email: agentEmail,
+      name: agentName,
+      provider: "agent",
+      providerId,
+      domain: siteDomain,
+      isActive: true,
+      isAdmin: false
+    }
   });
-  if (!workerUser) {
-    return c.json({ error: "Worker user not found \u2014 run: semiont useradd --email worker@semiont.local --generate-password --upsert" }, 503);
-  }
+  const did = agentToDid({ domain: siteDomain, provider: inferenceProvider, model });
   const token = JWTService.generateToken({
-    userId: userId(workerUser.id),
-    email: email(workerUser.email),
-    name: workerUser.name ?? "Worker Pool",
-    domain: workerUser.domain,
-    provider: workerUser.provider,
-    isAdmin: false
+    userId: userId(agentUser.id),
+    email: email(agentUser.email),
+    name: agentUser.name ?? agentName,
+    domain: agentUser.domain,
+    provider: agentUser.provider,
+    isAdmin: false,
+    agentDid: did
   }, "24h");
-  return c.json({ token }, 200);
+  return c.json({ token, did }, 200);
 });
 authRouter.post("/api/tokens/media", authMiddleware, async (c) => {
   const user = c.get("user");
@@ -17135,7 +17304,8 @@ function deriveStorageUri(name, format) {
 function registerCreateResource(router) {
   router.post("/resources", async (c) => {
     const user = c.get("user");
-    if (!user) {
+    const principalDid = c.get("principalDid");
+    if (!user || !principalDid) {
       throw new HTTPException(401, { message: "Authentication required" });
     }
     const formData = await c.req.formData();
@@ -17144,7 +17314,6 @@ function registerCreateResource(router) {
     const formatRaw = formData.get("format");
     const language = formData.get("language");
     const entityTypesStr = formData.get("entityTypes");
-    const creationMethod = formData.get("creationMethod");
     const storageUri = formData.get("storageUri");
     const sourceAnnotationId = formData.get("sourceAnnotationId");
     const sourceResourceId = formData.get("sourceResourceId");
@@ -17192,13 +17361,12 @@ function registerCreateResource(router) {
               format,
               language: language || void 0,
               entityTypes,
-              creationMethod: creationMethod || void 0,
               generatedFrom,
               generationPrompt: generationPrompt || void 0,
               generator,
               isDraft: isDraftStr ? isDraftStr === "true" : void 0
             },
-            userId(userToDid(user)),
+            userId(principalDid),
             eventBus2
           );
         },
@@ -17537,9 +17705,9 @@ function createBusRouter(authMiddleware2) {
         throw new HTTPException(400, { message: `Invalid payload for ${channel}: ${errorMessage}` });
       }
     }
-    const user = c.get("user");
-    if (user) {
-      payload._userId = userToDid(user);
+    const principalDid = c.get("principalDid");
+    if (principalDid) {
+      payload._userId = principalDid;
     }
     const traceparent = c.req.header("traceparent");
     const tracestate = c.req.header("tracestate");