@lightspeed-ai/agent-client 0.1.0

package/schema/workflow.schema.json

@@ -0,0 +1,880 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "definitions": {
+    "BotId": {
+      "type": "string"
+    },
+    "BotTriggerId": {
+      "type": "string"
+    },
+    "ChannelAccountId": {
+      "type": "string"
+    },
+    "ChannelDeliveryCommand": {
+      "description": "One connector activity call. `idempotency_key` is the invocation id, or\n`{invocation}:chunk:{i}/{n}` for a chunk of a split send.",
+      "properties": {
+        "idempotencyKey": {
+          "type": "string"
+        },
+        "invocationId": {
+          "type": "string"
+        },
+        "operation": {
+          "$ref": "#/definitions/ChannelDeliveryOperation"
+        },
+        "route": {
+          "$ref": "#/definitions/ChannelRoute"
+        },
+        "version": {
+          "format": "uint32",
+          "minimum": 0,
+          "type": "integer"
+        }
+      },
+      "required": [
+        "version",
+        "invocationId",
+        "idempotencyKey",
+        "route",
+        "operation"
+      ],
+      "type": "object"
+    },
+    "ChannelDeliveryOperation": {
+      "description": "What a connector executes: provider message ids and their direction.",
+      "oneOf": [
+        {
+          "properties": {
+            "replyContext": {
+              "anyOf": [
+                {
+                  "$ref": "#/definitions/ReplyContext"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "replyTo": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "text": {
+              "type": "string"
+            },
+            "type": {
+              "const": "send",
+              "type": "string"
+            }
+          },
+          "required": [
+            "type",
+            "text"
+          ],
+          "type": "object"
+        },
+        {
+          "properties": {
+            "messageId": {
+              "type": "string"
+            },
+            "text": {
+              "type": "string"
+            },
+            "type": {
+              "const": "edit",
+              "type": "string"
+            }
+          },
+          "required": [
+            "type",
+            "messageId",
+            "text"
+          ],
+          "type": "object"
+        },
+        {
+          "properties": {
+            "emoji": {
+              "type": "string"
+            },
+            "fromMe": {
+              "description": "Whether the reacted-to message is the bot's own.",
+              "type": "boolean"
+            },
+            "messageId": {
+              "type": "string"
+            },
+            "type": {
+              "const": "react",
+              "type": "string"
+            }
+          },
+          "required": [
+            "type",
+            "messageId",
+            "emoji",
+            "fromMe"
+          ],
+          "type": "object"
+        }
+      ]
+    },
+    "ChannelDeliveryResult": {
+      "properties": {
+        "messageIds": {
+          "description": "Every provider id the delivery produced (a chunked send has several;\nthe first is the anchor).",
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "provider": {
+          "$ref": "#/definitions/ChannelProvider"
+        },
+        "version": {
+          "format": "uint32",
+          "minimum": 0,
+          "type": "integer"
+        }
+      },
+      "required": [
+        "version",
+        "provider",
+        "messageIds"
+      ],
+      "type": "object"
+    },
+    "ChannelInboundMedia": {
+      "description": "A provider-owned attachment reference; never bytes. The connector\ndownloads it when the conversation workflow asks (`prepare_channel_media`).",
+      "properties": {
+        "byteSize": {
+          "format": "uint64",
+          "minimum": 0,
+          "type": [
+            "integer",
+            "null"
+          ]
+        },
+        "fileId": {
+          "description": "Provider file handle (a Telegram file id, a sealed WhatsApp locator).",
+          "type": "string"
+        },
+        "kind": {
+          "$ref": "#/definitions/ChannelMediaKind"
+        },
+        "mime": {
+          "type": "string"
+        },
+        "name": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      },
+      "required": [
+        "fileId",
+        "kind",
+        "mime"
+      ],
+      "type": "object"
+    },
+    "ChannelMediaKind": {
+      "enum": [
+        "image",
+        "audio",
+        "document"
+      ],
+      "type": "string"
+    },
+    "ChannelProvider": {
+      "type": "string"
+    },
+    "ChannelRoute": {
+      "description": "Where a delivery goes: one account's chat, optionally a thread.",
+      "properties": {
+        "accountId": {
+          "$ref": "#/definitions/ChannelAccountId"
+        },
+        "chatId": {
+          "type": "string"
+        },
+        "provider": {
+          "$ref": "#/definitions/ChannelProvider"
+        },
+        "threadId": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      },
+      "required": [
+        "provider",
+        "accountId",
+        "chatId"
+      ],
+      "type": "object"
+    },
+    "ChatAccess": {
+      "description": "Who may take a turn and who may issue control commands, by provider\nhandle (Telegram user id, WhatsApp JID). Handle allowlists on the\ntrigger replace any platform membership lookup.",
+      "properties": {
+        "allowed": {
+          "description": "Handles allowed to take a turn when `turn` is `listed`.",
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "controllers": {
+          "description": "Handles allowed to issue `/activation` and `/status`; empty denies\ncontrol commands to everyone.",
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "turn": {
+          "allOf": [
+            {
+              "$ref": "#/definitions/ChatTurnAccess"
+            }
+          ],
+          "default": "anyone"
+        }
+      },
+      "type": "object"
+    },
+    "ChatActivation": {
+      "description": "When the bot acts in a conversation.",
+      "properties": {
+        "group": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/ChatGroupActivation"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "mentionNames": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "triggerPrefixes": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        }
+      },
+      "type": "object"
+    },
+    "ChatGroupActivation": {
+      "oneOf": [
+        {
+          "const": "mention",
+          "description": "Act on mentions, replies to the bot, and trigger prefixes only.",
+          "type": "string"
+        },
+        {
+          "const": "always",
+          "description": "Act on every message.",
+          "type": "string"
+        }
+      ]
+    },
+    "ChatScope": {
+      "enum": [
+        "direct",
+        "group"
+      ],
+      "type": "string"
+    },
+    "ChatTurnAccess": {
+      "oneOf": [
+        {
+          "const": "anyone",
+          "description": "Anyone in the conversation may take a turn.",
+          "type": "string"
+        },
+        {
+          "const": "listed",
+          "description": "Only the listed provider handles may take a turn.",
+          "type": "string"
+        }
+      ]
+    },
+    "ConversationRef": {
+      "description": "The conversation a message belongs to: one account's chat, optionally\na thread inside it.",
+      "properties": {
+        "accountId": {
+          "$ref": "#/definitions/ChannelAccountId"
+        },
+        "chatId": {
+          "type": "string"
+        },
+        "threadId": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      },
+      "required": [
+        "accountId",
+        "chatId"
+      ],
+      "type": "object"
+    },
+    "ConversationStart": {
+      "description": "Secret-free durable input of one conversation workflow: the chat trigger\nit serves and the conversation it fronts. The workflow owns nothing on\nthe core side: the bot controller creates and controls the session; the\nworkflow is the source of the conversation's events and the receiver of\nits `message_*` tools.",
+      "properties": {
+        "access": {
+          "$ref": "#/definitions/ChatAccess"
+        },
+        "accountId": {
+          "$ref": "#/definitions/ChannelAccountId"
+        },
+        "activation": {
+          "$ref": "#/definitions/ChatActivation"
+        },
+        "botId": {
+          "$ref": "#/definitions/BotId"
+        },
+        "connectorTaskQueue": {
+          "description": "Task queue of the connector host serving the account.",
+          "type": "string"
+        },
+        "conversation": {
+          "$ref": "#/definitions/ConversationRef"
+        },
+        "label": {
+          "description": "Human label of the conversation (routed session label, display name).",
+          "type": "string"
+        },
+        "provider": {
+          "$ref": "#/definitions/ChannelProvider"
+        },
+        "scope": {
+          "$ref": "#/definitions/ChatScope"
+        },
+        "triggerId": {
+          "$ref": "#/definitions/BotTriggerId"
+        },
+        "universeId": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "universeId",
+        "botId",
+        "triggerId",
+        "accountId",
+        "provider",
+        "conversation",
+        "scope",
+        "activation",
+        "access",
+        "label",
+        "connectorTaskQueue"
+      ],
+      "type": "object"
+    },
+    "EmissionBody": {
+      "description": "Closed internal vocabulary carried by the shared delivery signal.\n\nWorkflow-tool invocation bodies join this enum when the durable tool\ncontracts land. This first slice folds the two existing transports.",
+      "oneOf": [
+        {
+          "properties": {
+            "failure_message_ref": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "kind": {
+              "const": "run_terminal",
+              "type": "string"
+            },
+            "output_ref": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "run_id": {
+              "format": "uint64",
+              "minimum": 0,
+              "type": "integer"
+            },
+            "status": {
+              "$ref": "#/definitions/RunStatus"
+            },
+            "token": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "kind",
+            "token",
+            "run_id",
+            "status"
+          ],
+          "type": "object"
+        },
+        {
+          "properties": {
+            "kind": {
+              "const": "source_resolution",
+              "type": "string"
+            },
+            "promise_id": {
+              "$ref": "#/definitions/PromiseId"
+            },
+            "resolution": {
+              "$ref": "#/definitions/PromiseResolution"
+            }
+          },
+          "required": [
+            "kind",
+            "promise_id",
+            "resolution"
+          ],
+          "type": "object"
+        },
+        {
+          "properties": {
+            "holder_workflow_id": {
+              "description": "Workflow id of the session that emitted the invocation — the\nendpoint a receiver signals its reply to. Supplied by the\nsubstrate adapter; the engine treats it as opaque.",
+              "type": "string"
+            },
+            "invocation": {
+              "$ref": "#/definitions/WorkflowToolInvocation"
+            },
+            "kind": {
+              "const": "tool_invocation",
+              "type": "string"
+            }
+          },
+          "required": [
+            "kind",
+            "invocation",
+            "holder_workflow_id"
+          ],
+          "type": "object"
+        },
+        {
+          "description": "Best-effort notice to a bound receiver that the session already\nresolved one keyed completion promise as cancelled. The receiver may\nstop the domain work behind that key; a later reply is ignored\nbecause the promise is terminal.",
+          "properties": {
+            "completion_key": {
+              "type": "string"
+            },
+            "invocation_id": {
+              "$ref": "#/definitions/WorkflowToolInvocationId"
+            },
+            "kind": {
+              "const": "invocation_cancellation",
+              "type": "string"
+            },
+            "promise_id": {
+              "$ref": "#/definitions/PromiseId"
+            }
+          },
+          "required": [
+            "kind",
+            "invocation_id",
+            "completion_key",
+            "promise_id"
+          ],
+          "type": "object"
+        }
+      ]
+    },
+    "EmissionEnvelope": {
+      "description": "Bounded cross-workflow fact delivered through the fixed\n`deliver_emission` signal.",
+      "properties": {
+        "body": {
+          "$ref": "#/definitions/EmissionBody"
+        },
+        "emission_id": {
+          "$ref": "#/definitions/EmissionId"
+        },
+        "producer": {
+          "$ref": "#/definitions/EmissionProducer"
+        }
+      },
+      "required": [
+        "emission_id",
+        "producer",
+        "body"
+      ],
+      "type": "object"
+    },
+    "EmissionId": {
+      "description": "Stable identity for one cross-workflow emission.\n\nIds are deterministic digests over a domain-separated, length-prefixed\nproducer/source identity. They are safe to recompute after activity retry,\nworker restart, or workflow continue-as-new.",
+      "type": "string"
+    },
+    "EmissionProducer": {
+      "description": "Durable producer identity carried with every emission.",
+      "oneOf": [
+        {
+          "description": "A session-log-backed emission. `log_seq` is the exact sequence of the\nevent that produced the fact.",
+          "properties": {
+            "kind": {
+              "const": "session",
+              "type": "string"
+            },
+            "log_seq": {
+              "format": "uint64",
+              "minimum": 0,
+              "type": "integer"
+            },
+            "session_id": {
+              "$ref": "#/definitions/SessionId"
+            },
+            "universe_id": {
+              "format": "uuid",
+              "type": "string"
+            }
+          },
+          "required": [
+            "kind",
+            "universe_id",
+            "session_id",
+            "log_seq"
+          ],
+          "type": "object"
+        },
+        {
+          "description": "An emission backed by another durable workflow's state.\n`universe_id` scopes this communication edge; it does not imply that\nthe producing workflow itself is universe-owned. A deployment-global\nworkflow may emit independently authorized facts for multiple\nuniverses.",
+          "properties": {
+            "kind": {
+              "const": "workflow",
+              "type": "string"
+            },
+            "universe_id": {
+              "format": "uuid",
+              "type": "string"
+            },
+            "workflow_id": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "kind",
+            "universe_id",
+            "workflow_id"
+          ],
+          "type": "object"
+        }
+      ]
+    },
+    "MaintainChannelTypingInput": {
+      "description": "`maintain_channel_typing`: keep the provider's typing indicator up for\nthe conversation until the activity is cancelled.",
+      "properties": {
+        "route": {
+          "$ref": "#/definitions/ChannelRoute"
+        }
+      },
+      "required": [
+        "route"
+      ],
+      "type": "object"
+    },
+    "PrepareChannelMediaInput": {
+      "description": "`prepare_channel_media`: the connector downloads the provider file and\nstores it in the universe's CAS.",
+      "properties": {
+        "media": {
+          "$ref": "#/definitions/ChannelInboundMedia"
+        },
+        "route": {
+          "$ref": "#/definitions/ChannelRoute"
+        },
+        "universeId": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "universeId",
+        "route",
+        "media"
+      ],
+      "type": "object"
+    },
+    "PrepareChannelMediaResult": {
+      "properties": {
+        "item": {
+          "$ref": "#/definitions/PreparedMediaItem"
+        }
+      },
+      "required": [
+        "item"
+      ],
+      "type": "object"
+    },
+    "PreparedMediaItem": {
+      "description": "A prepared attachment: a CAS reference, never bytes.",
+      "properties": {
+        "blobRef": {
+          "type": "string"
+        },
+        "kind": {
+          "$ref": "#/definitions/ChannelMediaKind"
+        },
+        "mime": {
+          "type": "string"
+        },
+        "name": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      },
+      "required": [
+        "blobRef",
+        "kind",
+        "mime"
+      ],
+      "type": "object"
+    },
+    "PromiseId": {
+      "description": "Stable identifier for a promise: a session-scoped counter rendered as\n`promise_<n>`, the same convention as `run_<n>`, so the model copies a\nshort handle rather than a digest. The engine hands every tool batch a\nbase one past the session cursor (`ToolInvocationBatchRequest::\npromise_id_base`); the executor numbers the promises it creates from\nthat base, and the reducer accepts a creation only at or above the\nbatch's base and never twice. Producer correlation lives on\n`PromiseSource`, not in the id.",
+      "type": "string"
+    },
+    "PromiseResolution": {
+      "description": "How a promise reached a terminal state. Used by `ResolvePromise`\nadmission; all transports (push notifications, poll results, timers,\ncancellation) converge on this one funnel.",
+      "oneOf": [
+        {
+          "properties": {
+            "kind": {
+              "const": "resolved",
+              "type": "string"
+            },
+            "payload_ref": {
+              "type": [
+                "string",
+                "null"
+              ]
+            }
+          },
+          "required": [
+            "kind"
+          ],
+          "type": "object"
+        },
+        {
+          "properties": {
+            "error_ref": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "kind": {
+              "const": "failed",
+              "type": "string"
+            }
+          },
+          "required": [
+            "kind"
+          ],
+          "type": "object"
+        },
+        {
+          "properties": {
+            "kind": {
+              "const": "cancelled",
+              "type": "string"
+            }
+          },
+          "required": [
+            "kind"
+          ],
+          "type": "object"
+        }
+      ]
+    },
+    "ReplyContext": {
+      "description": "The message a send replies to, for providers that quote it themselves.",
+      "properties": {
+        "senderId": {
+          "type": "string"
+        },
+        "text": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "senderId",
+        "text"
+      ],
+      "type": "object"
+    },
+    "RunStatus": {
+      "enum": [
+        "active",
+        "parked",
+        "cancelling",
+        "completed",
+        "failed",
+        "cancelled"
+      ],
+      "type": "string"
+    },
+    "SessionId": {
+      "type": "string"
+    },
+    "ToolCallId": {
+      "type": "string"
+    },
+    "WorkflowToolId": {
+      "type": "string"
+    },
+    "WorkflowToolInvocation": {
+      "description": "Bounded durable record of one successful workflow-tool tool call.\n\nThe model arguments remain in CAS and are referenced by `arguments_ref`.\nReceiver-specific interpretation belongs to the receiving workflow.",
+      "properties": {
+        "arguments_ref": {
+          "type": "string"
+        },
+        "binding_fingerprint": {
+          "type": "string"
+        },
+        "completion_promises": {
+          "additionalProperties": {
+            "$ref": "#/definitions/PromiseId"
+          },
+          "description": "Keyed promise set created atomically with this invocation; `None`\nfor notify (`Accepted`) completion. Request/reply is the single\nreserved key `reply`.",
+          "type": [
+            "object",
+            "null"
+          ]
+        },
+        "execution_context_ref": {
+          "description": "Opaque, runtime-supplied context for the receiving workflow. This is\nseparate from model-authored arguments so runtime state can be pinned\nwithout changing the tool's declared argument schema.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "invocation_id": {
+          "$ref": "#/definitions/WorkflowToolInvocationId"
+        },
+        "run_id": {
+          "format": "uint64",
+          "minimum": 0,
+          "type": "integer"
+        },
+        "schema_revision": {
+          "format": "uint32",
+          "minimum": 0,
+          "type": "integer"
+        },
+        "semantic_type": {
+          "type": "string"
+        },
+        "session_id": {
+          "$ref": "#/definitions/SessionId"
+        },
+        "session_universe_id": {
+          "format": "uuid",
+          "type": "string"
+        },
+        "tool_batch_id": {
+          "format": "uint64",
+          "minimum": 0,
+          "type": "integer"
+        },
+        "tool_call_id": {
+          "$ref": "#/definitions/ToolCallId"
+        },
+        "tool_id": {
+          "$ref": "#/definitions/WorkflowToolId"
+        },
+        "turn_id": {
+          "format": "uint64",
+          "minimum": 0,
+          "type": "integer"
+        }
+      },
+      "required": [
+        "invocation_id",
+        "tool_id",
+        "semantic_type",
+        "schema_revision",
+        "binding_fingerprint",
+        "session_universe_id",
+        "session_id",
+        "run_id",
+        "turn_id",
+        "tool_batch_id",
+        "tool_call_id",
+        "arguments_ref"
+      ],
+      "type": "object"
+    },
+    "WorkflowToolInvocationId": {
+      "type": "string"
+    },
+    "WorkflowToolRecipeV1": {
+      "properties": {
+        "taskQueue": {
+          "type": "string"
+        },
+        "workflowType": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "workflowType",
+        "taskQueue"
+      ],
+      "type": "object"
+    },
+    "WorkflowToolRecoveryResult": {
+      "description": "Result shape of [`WORKFLOW_TOOL_RECOVERY_QUERY`].",
+      "properties": {
+        "resolutions": {
+          "additionalProperties": {
+            "$ref": "#/definitions/PromiseResolution"
+          },
+          "default": {},
+          "type": "object"
+        }
+      },
+      "type": "object"
+    },
+    "WorkflowToolStartArgs": {
+      "description": "Start arguments every start-on-call plugin workflow receives. The plugin\nresolves each keyed completion promise by emitting `SourceResolution`\nbodies to the holder workflow through the fixed `deliver_emission`\nsignal, using its own execution id as the producer workflow id.",
+      "properties": {
+        "execution_id": {
+          "type": "string"
+        },
+        "holder_workflow_id": {
+          "type": "string"
+        },
+        "invocation": {
+          "$ref": "#/definitions/WorkflowToolInvocation"
+        },
+        "universe_id": {
+          "format": "uuid",
+          "type": "string"
+        }
+      },
+      "required": [
+        "universe_id",
+        "holder_workflow_id",
+        "execution_id",
+        "invocation"
+      ],
+      "type": "object"
+    }
+  },
+  "description": "Envelope and start-on-call types of the fixed deliver_emission transport between sessions and receiver workflows.",
+  "title": "Lightspeed Workflow Contract"
+}