@jambonz/schema 0.2.2 → 0.3.0

package/commands/llm-tool-output.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/commands/llm:tool-output",
+  "title": "LLM Tool Output Command",
+  "description": "Command sent from the application to feature-server over the session websocket, carrying the result of a tool invocation that the LLM initiated during an agent verb. Sent in response to an `agent:tool-call` event. The result is fed back into the LLM so it can continue generating using the tool output.",
+  "type": "object",
+  "required": ["type", "command", "tool_call_id", "data"],
+  "properties": {
+    "type": { "const": "command" },
+    "command": { "const": "llm:tool-output" },
+    "tool_call_id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The tool_call_id echoed from the originating `agent:tool-call` event."
+    },
+    "data": {
+      "type": "object",
+      "description": "Tool output payload. `{result: ...}` is the canonical shape — the wrapped value is what the LLM sees as the tool's return value. Other object shapes are accepted (they're JSON-stringified as-is into the tool_result content block on the wire) but `result` is preferred for clarity.",
+      "properties": {
+        "result": {}
+      },
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": false,
+  "examples": [
+    {
+      "type": "command",
+      "command": "llm:tool-output",
+      "tool_call_id": "toolu_017NKXtgnD7fuo1KaTeSM1ok",
+      "data": {
+        "result": "The current temperature in Boston is 9.3°C with wind speed 17 km/h."
+      }
+    }
+  ]
+}

package/index.js

@@ -1,9 +1,10 @@
-const {validate, validateVerb, validateApp} = require('./lib/validator');
+const {validate, validateVerb, validateApp, validateCommand} = require('./lib/validator');
 const {normalizeJambones} = require('./lib/normalize');
 
 module.exports = {
   validate,
   validateVerb,
   validateApp,
+  validateCommand,
   normalizeJambones,
 };

package/lib/validator.js

@@ -54,6 +54,12 @@ function getAjv() {
     _ajv.addSchema(schema);
   }
 
+  /* register command schemas (app → server over the session websocket) */
+  for (const name of discoverSchemas('commands')) {
+    const schema = loadSchema(`commands/${name}.schema.json`);
+    _ajv.addSchema(schema);
+  }
+
   /* compile the root app schema */
   const appSchema = loadSchema('jambonz-app.schema.json');
   _validateApp = _ajv.compile(appSchema);
@@ -103,6 +109,45 @@ function validateVerb(name, data, logger) {
   }
 }
 
+/**
+ * Validate a command message sent from the app to feature-server over the
+ * session websocket.
+ *
+ * Commands are the inverse of callbacks: callbacks flow server → app; commands
+ * flow app → server. Currently defined commands:
+ *   - llm:tool-output — response to an agent:tool-call event.
+ *
+ * @param {string} name - Command name (e.g. 'llm:tool-output').
+ * @param {object} message - The full command message including `type` and `command`.
+ * @param {object} logger - Logger instance.
+ * @throws {Error} If the command is unknown or validation fails.
+ */
+function validateCommand(name, message, logger) {
+  const ajv = getAjv();
+  const schemaId = `https://jambonz.org/schema/commands/${name}`;
+  const validate = ajv.getSchema(schemaId);
+  if (!validate) {
+    throw new Error(`invalid command: ${name}`);
+  }
+  const valid = validate(message);
+  if (!valid) {
+    const errors = validate.errors || [];
+    const details = errors.map((e) => {
+      const path = e.instancePath || '(root)';
+      let msg = `'${path}': ${e.message}`;
+      if (e.params) {
+        if (e.params.type) msg += ` (expected ${e.params.type})`;
+        if (e.params.allowedValues) msg += ` (allowed: ${e.params.allowedValues.join(', ')})`;
+        if (e.params.missingProperty) msg += ` (missing: ${e.params.missingProperty})`;
+      }
+      return msg;
+    }).join('; ');
+    const errMsg = `command '${name}' validation failed — ${details}. Schema: ${schemaId}`;
+    debug(errMsg);
+    throw new Error(errMsg);
+  }
+}
+
 /**
  * Validate a complete jambonz application (array of verbs).
  *
@@ -144,4 +189,4 @@ function validateApp(app) {
   };
 }
 
-module.exports = {validate, validateVerb, validateApp};
+module.exports = {validate, validateVerb, validateApp, validateCommand};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jambonz/schema",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "JSON Schema definitions and validation for jambonz verb applications",
   "main": "index.js",
   "scripts": {
@@ -32,6 +32,7 @@
     "verbs/",
     "components/",
     "callbacks/",
+    "commands/",
     "docs/",
     "jambonz-app.schema.json",
     "AGENTS.md"

package/verbs/agent.schema.json

@@ -86,8 +86,89 @@
     },
     "llm": {
       "type": "object",
-      "description": "LLM configuration for the agent. See the 'llm' verb schema for details.",
-      "additionalProperties": true
+      "description": "LLM configuration for the agent.",
+      "required": ["vendor", "model"],
+      "properties": {
+        "vendor": {
+          "type": "string",
+          "enum": [
+            "openai",
+            "anthropic",
+            "google",
+            "vertex-gemini",
+            "vertex-openai",
+            "bedrock",
+            "deepseek"
+          ],
+          "description": "LLM vendor id. Must match a `@jambonz/llm` registered adapter."
+        },
+        "model": {
+          "type": "string",
+          "description": "Vendor-specific model id (e.g. 'gpt-4o', 'claude-sonnet-4-5-20250929')."
+        },
+        "label": {
+          "type": "string",
+          "description": "Optional label to disambiguate when the account has multiple credentials for the same vendor."
+        },
+        "auth": {
+          "type": "object",
+          "description": "Optional inline credentials. When omitted, feature-server looks up credentials by (vendor, label) from the database.",
+          "properties": {
+            "apiKey": { "type": "string" }
+          },
+          "additionalProperties": true
+        },
+        "connectOptions": {
+          "type": "object",
+          "description": "SDK-level client options.",
+          "properties": {
+            "timeout": { "type": "number", "minimum": 0 },
+            "maxRetries": { "type": "integer", "minimum": 0 },
+            "endpoint": { "type": "string" },
+            "baseURL": { "type": "string" }
+          },
+          "additionalProperties": false
+        },
+        "llmOptions": {
+          "type": "object",
+          "description": "Per-call LLM configuration.",
+          "properties": {
+            "systemPrompt": {
+              "type": "string",
+              "description": "System prompt for the model. Placed vendor-appropriately (top-level for Anthropic/Bedrock, config.systemInstruction for Gemini, role:'system' for OpenAI-compatibles)."
+            },
+            "messages": {
+              "type": "array",
+              "description": "Seed conversation history. A role:'system' entry is extracted into systemPrompt internally.",
+              "items": { "$ref": "#/$defs/llmMessage" }
+            },
+            "initialMessages": {
+              "type": "array",
+              "description": "Alias of 'messages' (historical).",
+              "items": { "$ref": "#/$defs/llmMessage" }
+            },
+            "maxTokens": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "Maximum tokens the model may generate per turn."
+            },
+            "temperature": {
+              "type": "number",
+              "minimum": 0,
+              "description": "Sampling temperature."
+            },
+            "tools": {
+              "type": "array",
+              "description": "Tool / function definitions available to the model. The MCP-flat shape `{name, description, parameters}` is canonical; the OpenAI-wrapped form `{type:'function', function:{...}}` is also accepted.",
+              "items": {
+                "type": "object"
+              }
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
     },
     "actionHook": {
       "$ref": "../components/actionHook",
@@ -177,6 +258,21 @@
   "required": [
     "llm"
   ],
+  "$defs": {
+    "llmMessage": {
+      "type": "object",
+      "description": "A conversation-history message. The library normalizes content to a string; adapters may carry vendor-native shapes internally.",
+      "required": ["role", "content"],
+      "properties": {
+        "role": {
+          "type": "string",
+          "enum": ["system", "user", "assistant", "tool"]
+        },
+        "content": {}
+      },
+      "additionalProperties": true
+    }
+  },
   "examples": [
     {
       "verb": "agent",