@statelyai/agent 1.1.6 → 2.0.0-alpha.11

package/schemas/agent-workflow.json

@@ -0,0 +1,526 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://stately.ai/schemas/agent-workflow.json",
+  "title": "Stately Agent Workflow Definition",
+  "description": "Static, declarative agent workflow definition that can be lowered to a setupAgent(...) XState machine.",
+  "type": "object",
+  "required": ["initial", "states"],
+  "properties": {
+    "$schema": {
+      "description": "JSON Schema reference an editor attaches to the config file. Ignored by the lowering.",
+      "type": "string"
+    },
+    "key": {
+      "description": "Stable workflow key used by tools, storage, and visual editors.",
+      "type": "string",
+      "minLength": 1
+    },
+    "id": {
+      "description": "Optional XState machine id.",
+      "type": "string",
+      "minLength": 1
+    },
+    "version": {
+      "description": "Definition version chosen by the author.",
+      "type": "string"
+    },
+    "description": {
+      "type": "string"
+    },
+    "schemas": {
+      "$ref": "#/$defs/AgentSchemas"
+    },
+    "context": {
+      "description": "Initial XState context. Values may be JSON literals or whole-string {{ }} expressions evaluated with machine input.",
+      "$ref": "#/$defs/ExpressionObject"
+    },
+    "requests": {
+      "description": "Named model requests that become typed invoke sources.",
+      "type": "object",
+      "propertyNames": {
+        "$ref": "#/$defs/Identifier"
+      },
+      "additionalProperties": {
+        "$ref": "#/$defs/Request"
+      },
+      "default": {}
+    },
+    "initial": {
+      "description": "Initial child state key.",
+      "type": "string"
+    },
+    "states": {
+      "description": "Root state nodes.",
+      "type": "object",
+      "minProperties": 1,
+      "propertyNames": {
+        "$ref": "#/$defs/Identifier"
+      },
+      "additionalProperties": {
+        "$ref": "#/$defs/State"
+      }
+    },
+    "meta": {
+      "$ref": "#/$defs/JsonObject"
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "Identifier": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[A-Za-z_$][A-Za-z0-9_$.-]*$"
+    },
+    "ExpressionString": {
+      "description": "Whole-string expression delimited by {{ }}.",
+      "type": "string",
+      "pattern": "^\\{\\{[\\s\\S]*\\}\\}$"
+    },
+    "TemplateString": {
+      "description": "String that may contain {{ }} template expressions. Escape literal delimiters according to the selected expression/template evaluator.",
+      "type": "string"
+    },
+    "JsonValue": {
+      "anyOf": [
+        { "type": "null" },
+        { "type": "boolean" },
+        { "type": "number" },
+        { "type": "string" },
+        {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/JsonValue"
+          }
+        },
+        {
+          "$ref": "#/$defs/JsonObject"
+        }
+      ]
+    },
+    "JsonObject": {
+      "type": "object",
+      "propertyNames": {
+        "type": "string"
+      },
+      "additionalProperties": {
+        "$ref": "#/$defs/JsonValue"
+      }
+    },
+    "ExpressionValue": {
+      "description": "JSON value or whole-string {{ }} expression. Use this for typed values, not prompt templating.",
+      "anyOf": [
+        { "$ref": "#/$defs/ExpressionString" },
+        { "type": "null" },
+        { "type": "boolean" },
+        { "type": "number" },
+        { "type": "string" },
+        {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/ExpressionValue"
+          }
+        },
+        {
+          "type": "object",
+          "propertyNames": {
+            "type": "string"
+          },
+          "additionalProperties": {
+            "$ref": "#/$defs/ExpressionValue"
+          }
+        }
+      ]
+    },
+    "ExpressionObject": {
+      "type": "object",
+      "propertyNames": {
+        "type": "string"
+      },
+      "additionalProperties": {
+        "$ref": "#/$defs/ExpressionValue"
+      }
+    },
+    "JsonSchema": {
+      "description": "JSON Schema object.",
+      "type": "object",
+      "propertyNames": {
+        "type": "string"
+      },
+      "additionalProperties": true
+    },
+    "AgentSchemas": {
+      "type": "object",
+      "properties": {
+        "input": {
+          "$ref": "#/$defs/JsonSchema"
+        },
+        "context": {
+          "$ref": "#/$defs/JsonSchema"
+        },
+        "events": {
+          "type": "object",
+          "propertyNames": {
+            "$ref": "#/$defs/Identifier"
+          },
+          "additionalProperties": {
+            "$ref": "#/$defs/JsonSchema"
+          }
+        },
+        "emitted": {
+          "type": "object",
+          "description": "Schemas for events emitted outward by emit actions, keyed by emitted event type.",
+          "propertyNames": {
+            "$ref": "#/$defs/Identifier"
+          },
+          "additionalProperties": {
+            "$ref": "#/$defs/JsonSchema"
+          }
+        },
+        "output": {
+          "$ref": "#/$defs/JsonSchema"
+        },
+        "meta": {
+          "$ref": "#/$defs/JsonSchema"
+        }
+      },
+      "additionalProperties": false
+    },
+    "Request": {
+      "type": "object",
+      "required": ["model", "input", "output"],
+      "properties": {
+        "mode": {
+          "type": "string",
+          "enum": ["generate", "stream"],
+          "default": "generate"
+        },
+        "description": {
+          "type": "string"
+        },
+        "model": {
+          "$ref": "#/$defs/TemplateString"
+        },
+        "system": {
+          "$ref": "#/$defs/TemplateString"
+        },
+        "prompt": {
+          "$ref": "#/$defs/TemplateString"
+        },
+        "messages": {
+          "anyOf": [
+            { "$ref": "#/$defs/ExpressionString" },
+            {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/Message"
+              }
+            }
+          ]
+        },
+        "input": {
+          "$ref": "#/$defs/JsonSchema"
+        },
+        "output": {
+          "$ref": "#/$defs/JsonSchema"
+        },
+        "tools": {
+          "type": "object",
+          "propertyNames": {
+            "$ref": "#/$defs/Identifier"
+          },
+          "additionalProperties": {
+            "$ref": "#/$defs/Tool"
+          }
+        },
+        "toolChoice": {
+          "anyOf": [
+            {
+              "type": "string",
+              "enum": ["auto", "none", "required"]
+            },
+            {
+              "type": "object",
+              "required": ["type", "name"],
+              "properties": {
+                "type": {
+                  "const": "tool"
+                },
+                "name": {
+                  "$ref": "#/$defs/Identifier"
+                }
+              },
+              "additionalProperties": false
+            },
+            { "$ref": "#/$defs/ExpressionString" }
+          ]
+        },
+        "temperature": {
+          "$ref": "#/$defs/ExpressionValue"
+        },
+        "maxOutputTokens": {
+          "$ref": "#/$defs/ExpressionValue"
+        },
+        "topP": {
+          "$ref": "#/$defs/ExpressionValue"
+        },
+        "topK": {
+          "$ref": "#/$defs/ExpressionValue"
+        },
+        "seed": {
+          "$ref": "#/$defs/ExpressionValue"
+        },
+        "stopSequences": {
+          "anyOf": [
+            { "$ref": "#/$defs/ExpressionString" },
+            {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          ]
+        },
+        "metadata": {
+          "$ref": "#/$defs/ExpressionValue"
+        }
+      },
+      "additionalProperties": false
+    },
+    "Message": {
+      "type": "object",
+      "required": ["role", "content"],
+      "properties": {
+        "role": {
+          "$ref": "#/$defs/TemplateString"
+        },
+        "content": {
+          "$ref": "#/$defs/TemplateString"
+        }
+      },
+      "additionalProperties": {
+        "$ref": "#/$defs/ExpressionValue"
+      }
+    },
+    "Tool": {
+      "type": "object",
+      "properties": {
+        "description": {
+          "type": "string"
+        },
+        "input": {
+          "$ref": "#/$defs/JsonSchema"
+        },
+        "output": {
+          "$ref": "#/$defs/JsonSchema"
+        }
+      },
+      "additionalProperties": {
+        "$ref": "#/$defs/JsonValue"
+      }
+    },
+    "State": {
+      "type": "object",
+      "properties": {
+        "description": {
+          "type": "string"
+        },
+        "type": {
+          "type": "string",
+          "enum": ["parallel", "history", "final", "choice"]
+        },
+        "initial": {
+          "type": "string"
+        },
+        "states": {
+          "type": "object",
+          "propertyNames": {
+            "$ref": "#/$defs/Identifier"
+          },
+          "additionalProperties": {
+            "$ref": "#/$defs/State"
+          }
+        },
+        "invoke": {
+          "anyOf": [
+            { "$ref": "#/$defs/Invoke" },
+            {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/Invoke"
+              }
+            }
+          ]
+        },
+        "choice": {
+          "description": "Choice-state routing, equivalent to XState's type: 'choice' + choice transition function.",
+          "$ref": "#/$defs/TransitionOrArray"
+        },
+        "on": {
+          "type": "object",
+          "propertyNames": {
+            "type": "string"
+          },
+          "additionalProperties": {
+            "$ref": "#/$defs/TransitionOrArray"
+          }
+        },
+        "always": {
+          "$ref": "#/$defs/TransitionOrArray"
+        },
+        "onDone": {
+          "$ref": "#/$defs/TransitionOrArray"
+        },
+        "after": {
+          "type": "object",
+          "propertyNames": {
+            "type": "string"
+          },
+          "additionalProperties": {
+            "$ref": "#/$defs/TransitionOrArray"
+          }
+        },
+        "entry": {
+          "$ref": "#/$defs/ActionOrArray"
+        },
+        "exit": {
+          "$ref": "#/$defs/ActionOrArray"
+        },
+        "tags": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "output": {
+          "$ref": "#/$defs/ExpressionValue"
+        },
+        "meta": {
+          "$ref": "#/$defs/ExpressionObject"
+        }
+      },
+      "additionalProperties": false
+    },
+    "Invoke": {
+      "type": "object",
+      "required": ["src"],
+      "properties": {
+        "id": {
+          "type": "string"
+        },
+        "src": {
+          "description": "Actor source name. 'agent.decide' invokes are special: decision delivery is automatic (the chosen event is sent as soon as the model decides) and 'onDone' must be omitted — see the 'onDone' description.",
+          "$ref": "#/$defs/Identifier"
+        },
+        "input": {
+          "$ref": "#/$defs/ExpressionValue"
+        },
+        "onDone": {
+          "description": "Not valid on an 'agent.decide' invoke — the built-in lowering rejects it at setupAgent.fromConfig(...) time. A decision has no output value of its own (its output IS the chosen event), so delivery is automatic and not configurable from JSON. 'onError' (retries exhausted) still applies to 'agent.decide' invokes.",
+          "$ref": "#/$defs/TransitionOrArray"
+        },
+        "onError": {
+          "$ref": "#/$defs/TransitionOrArray"
+        },
+        "meta": {
+          "$ref": "#/$defs/ExpressionObject"
+        }
+      },
+      "additionalProperties": false
+    },
+    "TransitionOrArray": {
+      "anyOf": [
+        { "$ref": "#/$defs/Transition" },
+        {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/Transition"
+          }
+        }
+      ]
+    },
+    "Transition": {
+      "type": "object",
+      "properties": {
+        "target": {
+          "anyOf": [
+            { "type": "string" },
+            {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          ]
+        },
+        "guard": {
+          "anyOf": [
+            { "$ref": "#/$defs/ExpressionString" },
+            {
+              "type": "object",
+              "required": ["type"],
+              "properties": {
+                "type": {
+                  "type": "string"
+                },
+                "params": {
+                  "$ref": "#/$defs/ExpressionValue"
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "assign": {
+          "description": "Context assignments applied when this transition is taken.",
+          "$ref": "#/$defs/ExpressionObject"
+        },
+        "actions": {
+          "$ref": "#/$defs/ActionOrArray"
+        },
+        "description": {
+          "type": "string"
+        },
+        "reenter": {
+          "type": "boolean"
+        },
+        "meta": {
+          "$ref": "#/$defs/ExpressionObject"
+        }
+      },
+      "additionalProperties": false
+    },
+    "ActionOrArray": {
+      "anyOf": [
+        { "$ref": "#/$defs/Action" },
+        {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/Action"
+          }
+        }
+      ]
+    },
+    "Action": {
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string"
+        },
+        "params": {
+          "$ref": "#/$defs/ExpressionValue"
+        },
+        "assign": {
+          "$ref": "#/$defs/ExpressionObject"
+        },
+        "emit": {
+          "description": "Event emitted outward through runAgent's on handlers.",
+          "$ref": "#/$defs/ExpressionValue"
+        }
+      },
+      "anyOf": [{ "required": ["type"] }, { "required": ["assign"] }, { "required": ["emit"] }],
+      "additionalProperties": {
+        "$ref": "#/$defs/ExpressionValue"
+      }
+    }
+  }
+}

package/.changeset/README.md

@@ -1,8 +0,0 @@
-# Changesets
-
-Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
-with multi-package repos, or single-package repos to help you version and publish your code. You can
-find the full documentation for it [in our repository](https://github.com/changesets/changesets)
-
-We have a quick list of common questions to get you started engaging with this project in
-[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)

package/.changeset/config.json

@@ -1,11 +0,0 @@
-{
-  "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
-  "changelog": ["@changesets/changelog-github", { "repo": "statelyai/agent" }],
-  "commit": false,
-  "fixed": [],
-  "linked": [],
-  "access": "restricted",
-  "baseBranch": "main",
-  "updateInternalDependencies": "patch",
-  "ignore": []
-}

package/.env.template

@@ -1,3 +0,0 @@
-
-# Get your OpenAI API key from: https://platform.openai.com/signup/
-OPENAI_API_KEY="sk-..."

package/.github/actions/ci-setup/action.yml

@@ -1,24 +0,0 @@
-name: Setup Workflow
-description: Composite action that sets up pnpm
-runs:
-  using: 'composite'
-  steps:
-    - uses: pnpm/action-setup@v2
-    - uses: actions/setup-node@v4
-      with:
-        node-version: 20.x
-        
-    - name: install pnpm
-      run: npm i pnpm@latest -g
-      shell: bash
-
-    - name: Setup npmrc
-      run: echo "//registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}" > .npmrc
-      shell: bash
-
-    - name: setup pnpm config
-      run: pnpm config set store-dir $PNPM_CACHE_FOLDER
-      shell: bash
-
-    - run: pnpm install
-      shell: bash

package/.github/workflows/release.yml

@@ -1,46 +0,0 @@
-name: Release
-
-on:
-  push:
-    branches:
-      - main
-
-concurrency: ${{ github.workflow }}-${{ github.ref }}
-
-permissions: {}
-jobs:
-  release:
-    permissions:
-      contents: write # to create release (changesets/action)
-      issues: write # to post issue comments (changesets/action)
-      pull-requests: write # to create pull request (changesets/action)
-
-    if: github.repository == 'statelyai/agent'
-
-    timeout-minutes: 20
-
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: checkout code repository
-        uses: actions/checkout@v3
-        with:
-          fetch-depth: 0
-      - name: setup node.js
-        uses: actions/setup-node@v3
-        with:
-          node-version: 20
-      - name: install pnpm
-        run: npm i pnpm@latest -g
-      - name: setup pnpm config
-        run: pnpm config set store-dir $PNPM_CACHE_FOLDER
-      - name: install dependencies
-        run: pnpm install
-      - name: create and publish versions
-        uses: changesets/action@v1
-        with:
-          publish: pnpm run release
-          version: pnpm run version
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.vscode/launch.json

@@ -1,28 +0,0 @@
-{
-  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
-  "version": "0.2.0",
-  "configurations": [
-    {
-      "type": "node",
-      "request": "launch",
-      "name": "Debug Current Test File",
-      "autoAttachChildProcesses": true,
-      "skipFiles": ["<node_internals>/**", "**/node_modules/**", "examples/**"],
-      "program": "${workspaceRoot}/node_modules/vitest/vitest.mjs",
-      "args": ["run", "${relativeFile}"],
-      "smartStep": true,
-      "console": "integratedTerminal"
-    },
-    {
-      "type": "node",
-      "request": "launch",
-      "name": "Debug Current File",
-      "program": "${file}",
-      "cwd": "${workspaceFolder}",
-      "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/ts-node",
-      "outFiles": ["${workspaceFolder}/dist/**/*.js"],
-      "sourceMaps": true,
-      "console": "integratedTerminal"
-    }
-  ]
-}