code0-hercules 1.5.0__tar.gz → 1.7.0__tar.gz

{code0_hercules-1.5.0 → code0_hercules-1.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code0-hercules
-Version: 1.5.0
+Version: 1.7.0
 Summary: Python SDK for the hercules action runner
 License-Expression: MIT
 Project-URL: Repository, https://github.com/code0-tech/hercules
@@ -8,7 +8,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 Requires-Dist: grpcio>=1.64
 Requires-Dist: protobuf>=5.0
-Requires-Dist: tucana>=0.0.82
+Requires-Dist: tucana>=0.0.83
 Requires-Dist: pydantic>=2
 Provides-Extra: codegen
 Requires-Dist: datamodel-code-generator>=0.25; extra == "codegen"
@@ -51,7 +51,7 @@ The built-in data types / functions in `hercules/definitions/` are **generated**
 release:
 
 ```bash
-uv run python scripts/build_definitions.py --version def-0.0.36
+uv run python scripts/build_definitions.py --version def-0.0.38
 ```
 
 ## Build & release
@@ -70,7 +70,7 @@ git tag 0.1.0 && git push origin 0.1.0
 ```
 
 The `code0-definition` release used for the built-in definitions is controlled by
-the `HERCULES_DEFINITIONS_VERSION` repository variable (default `def-0.0.36`).
+the `HERCULES_DEFINITIONS_VERSION` repository variable (default `def-0.0.38`).
 
 Build locally:
 

{code0_hercules-1.5.0 → code0_hercules-1.7.0}/README.md

@@ -36,7 +36,7 @@ The built-in data types / functions in `hercules/definitions/` are **generated**
 release:
 
 ```bash
-uv run python scripts/build_definitions.py --version def-0.0.36
+uv run python scripts/build_definitions.py --version def-0.0.38
 ```
 
 ## Build & release
@@ -55,7 +55,7 @@ git tag 0.1.0 && git push origin 0.1.0
 ```
 
 The `code0-definition` release used for the built-in definitions is controlled by
-the `HERCULES_DEFINITIONS_VERSION` repository variable (default `def-0.0.36`).
+the `HERCULES_DEFINITIONS_VERSION` repository variable (default `def-0.0.38`).
 
 Build locally:
 

{code0_hercules-1.5.0 → code0_hercules-1.7.0}/code0_hercules.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code0-hercules
-Version: 1.5.0
+Version: 1.7.0
 Summary: Python SDK for the hercules action runner
 License-Expression: MIT
 Project-URL: Repository, https://github.com/code0-tech/hercules
@@ -8,7 +8,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 Requires-Dist: grpcio>=1.64
 Requires-Dist: protobuf>=5.0
-Requires-Dist: tucana>=0.0.82
+Requires-Dist: tucana>=0.0.83
 Requires-Dist: pydantic>=2
 Provides-Extra: codegen
 Requires-Dist: datamodel-code-generator>=0.25; extra == "codegen"
@@ -51,7 +51,7 @@ The built-in data types / functions in `hercules/definitions/` are **generated**
 release:
 
 ```bash
-uv run python scripts/build_definitions.py --version def-0.0.36
+uv run python scripts/build_definitions.py --version def-0.0.38
 ```
 
 ## Build & release
@@ -70,7 +70,7 @@ git tag 0.1.0 && git push origin 0.1.0
 ```
 
 The `code0-definition` release used for the built-in definitions is controlled by
-the `HERCULES_DEFINITIONS_VERSION` repository variable (default `def-0.0.36`).
+the `HERCULES_DEFINITIONS_VERSION` repository variable (default `def-0.0.38`).
 
 Build locally:
 

{code0_hercules-1.5.0 → code0_hercules-1.7.0}/code0_hercules.egg-info/SOURCES.txt

@@ -238,6 +238,7 @@ hercules/internal/literal.py
 hercules/internal/module_builder.py
 hercules/internal/pydantic_codegen.py
 hercules/internal/schema.py
+hercules/internal/sub_flow_function.py
 hercules/internal/tsgen.py
 hercules/manager/__init__.py
 hercules/manager/base.py
@@ -248,6 +249,7 @@ hercules/manager/flow.py
 hercules/manager/function.py
 hercules/manager/runtime_event.py
 hercules/manager/runtime_function.py
+hercules/manager/sub_flow_function.py
 hercules/map/__init__.py
 hercules/map/datatype.py
 hercules/map/event.py
@@ -261,6 +263,7 @@ hercules/models/function.py
 hercules/models/runtime_event.py
 hercules/models/runtime_function.py
 tests/test_datatype.py
+tests/test_execution.py
 tests/test_export.py
 tests/test_index.py
 tests/test_literal.py

{code0_hercules-1.5.0 → code0_hercules-1.7.0}/code0_hercules.egg-info/requires.txt

@@ -1,6 +1,6 @@
 grpcio>=1.64
 protobuf>=5.0
-tucana>=0.0.82
+tucana>=0.0.83
 pydantic>=2
 
 [codegen]

{code0_hercules-1.5.0 → code0_hercules-1.7.0}/hercules/__init__.py

@@ -18,6 +18,8 @@ from hercules.types import (
     RuntimeError,
     RuntimeFlowTypeSetting_UniquenessScope,
     SubFlow,
+    SubFlowFunctionDefinition,
+    SubFlowFunctionSchema,
     Translation,
 )
 from hercules.events import CodeZeroEvent
@@ -55,6 +57,10 @@ from hercules.manager.flow import FlowManager
 from hercules.manager.function import FunctionManager
 from hercules.manager.runtime_event import RuntimeEventManager
 from hercules.manager.runtime_function import RuntimeFunctionManager
+from hercules.manager.sub_flow_function import (
+    SUB_FLOW_FUNCTION_TTL_SECONDS,
+    SubFlowFunctionManager,
+)
 from hercules.models.datatype import DataTypeProps, DataTypeRunnable
 from hercules.models.event import EventModel, EventSettingProps
 from hercules.models.function import FunctionParameterProps, FunctionProps
@@ -63,7 +69,8 @@ from hercules.models.runtime_function import RuntimeFunctionProps, RuntimeFuncti
 from hercules.action import Action, is_export_mode, registered_actions
 
 __all__ = [
-    "Translation", "PlainValue", "SubFlow", "FunctionContext",
+    "Translation", "PlainValue", "SubFlow", "SubFlowFunctionDefinition",
+    "SubFlowFunctionSchema", "FunctionContext",
     "ProjectConfiguration", "ConfigurationDefinition", "RuntimeError",
     "FlowTypeSetting_UniquenessScope", "RuntimeFlowTypeSetting_UniquenessScope",
     "CodeZeroEvent", "SchemaType",
@@ -73,7 +80,9 @@ __all__ = [
     "OmitFunction", "Design", "ThrowsError", "Parameter", "Schema", "TypeString",
     "EventSetting", "OmitEvent", "OmitRuntimeFunction",
     "BaseManager", "ConfigManager", "FlowManager", "FunctionManager",
-    "RuntimeFunctionManager", "DataTypeManager", "EventManager", "RuntimeEventManager",
+    "RuntimeFunctionManager", "SubFlowFunctionManager",
+    "SUB_FLOW_FUNCTION_TTL_SECONDS", "DataTypeManager",
+    "EventManager", "RuntimeEventManager",
     "FunctionProps", "FunctionParameterProps", "RuntimeFunctionProps",
     "RuntimeFunctionRunnable", "DataTypeProps", "DataTypeRunnable", "EventModel",
     "EventSettingProps", "RuntimeEventProps", "RuntimeEventRunnable",

{code0_hercules-1.5.0 → code0_hercules-1.7.0}/hercules/action.py

@@ -22,6 +22,7 @@ from hercules.manager.flow import FlowManager
 from hercules.manager.function import FunctionManager
 from hercules.manager.runtime_event import RuntimeEventManager
 from hercules.manager.runtime_function import RuntimeFunctionManager
+from hercules.manager.sub_flow_function import SubFlowFunctionManager
 from hercules.map.datatype import data_type_map
 from hercules.map.event import event_map
 from hercules.map.function import function_map
@@ -29,7 +30,12 @@ from hercules.map.runtime_event import runtime_event_map
 from hercules.map.runtime_function import runtime_function_map
 from hercules.models.event import EventModel
 from hercules.models.function import FunctionProps
-from hercules.types import ConfigurationDefinition, RuntimeError, Translation
+from hercules.types import (
+    ConfigurationDefinition,
+    RuntimeError,
+    SubFlowFunctionDefinition,
+    Translation,
+)
 
 # Registry of actions constructed while exporting, so the CLI can find them.
 _REGISTERED_ACTIONS: List["Action"] = []
@@ -114,6 +120,7 @@ class Action(EventEmitter):
         self.flows = FlowManager()
         self.functions = FunctionManager()
         self.runtime_functions = RuntimeFunctionManager()
+        self.sub_flow_functions = SubFlowFunctionManager()
         self.data_types = DataTypeManager()
         self.events = EventManager()
         self.runtime_events = RuntimeEventManager()
@@ -165,6 +172,35 @@ class Action(EventEmitter):
                 ),
             )
 
+    def register_sub_flow_function(self, definition: SubFlowFunctionDefinition) -> str:
+        """Register a sub flow function returned from a ``run`` block.
+
+        Returns the identifier Aquila invokes it by. Each returned function gets its
+        own identifier, so repeatedly returning one (e.g. once per execution) never
+        overwrites a function a running flow still holds.
+
+        Aquila gives no signal that a flow is done with a function, so a registration
+        expires on its own 30 minutes after it was registered and can no longer be
+        invoked (see :class:`~hercules.manager.sub_flow_function.SubFlowFunctionManager`).
+        Call ``sub_flow_functions.delete(identifier)`` to drop one earlier.
+        """
+        identifier = f"{self._sub_flow_function_prefix}{definition.name}::{uuid.uuid4()}"
+        self.sub_flow_functions.set(identifier, definition)
+        return identifier
+
+    def is_sub_flow_function_identifier(self, identifier: str) -> bool:
+        """True for an identifier this action minted for a sub flow function.
+
+        Holds whether or not it is still registered. An execution request naming one
+        that is gone addresses a function that expired (or was deleted) rather than an
+        unknown one, which lets the execution handler report it as such.
+        """
+        return identifier.startswith(self._sub_flow_function_prefix)
+
+    @property
+    def _sub_flow_function_prefix(self) -> str:
+        return f"{self._identifier}::"
+
     def register_data_type_class(self, klass: type) -> None:
         definition = data_type_map(klass)
         self.data_types.set(definition.identifier, definition)

code0_hercules-1.7.0/hercules/actions/execution.py

@@ -0,0 +1,194 @@
+"""Execution request handler (port of ``src/actions/Execution.ts``)."""
+from __future__ import annotations
+
+import asyncio
+import inspect
+import time
+from dataclasses import dataclass
+from typing import Callable, Optional
+
+from hercules._tucana.helpers import construct_value
+from tucana.generated.aquila import action_pb2
+from tucana.generated.shared import errors_pb2, execution_result_pb2
+from hercules.events import CodeZeroEvent
+from hercules.internal.literal import resolve_node_value
+from hercules.internal.sub_flow_function import (
+    as_sub_flow_function_definition,
+    build_sub_flow_function_result,
+)
+from hercules.types import ProjectConfiguration, RuntimeError
+
+packet_type = "execution"
+
+
+@dataclass
+class _ExecutionTarget:
+    """A function an execution request may address.
+
+    Either a registered runtime function or a sub flow function returned by one.
+    ``parameter_count`` is ``None`` for a sub flow function, which has no definition
+    declaring its parameters, so every parameter of the request is passed through.
+    """
+
+    handler: Callable[..., object]
+    parameter_count: Optional[int] = None
+
+
+def _now_micros() -> int:
+    return time.time_ns() // 1000
+
+
+def _resolve_target(action, identifier: str) -> Optional[_ExecutionTarget]:
+    func = action.runtime_functions.get(identifier)
+    if func is not None:
+        return _ExecutionTarget(func.handler, len(func.parameters or []))
+
+    sub_flow_function = action.sub_flow_functions.get(identifier)
+    if sub_flow_function is not None:
+        return _ExecutionTarget(sub_flow_function.run)
+
+    return None
+
+
+def _build_params(action, execution, target: _ExecutionTarget):
+    count = (
+        target.parameter_count
+        if target.parameter_count is not None
+        else len(execution.parameters)
+    )
+    params = []
+    for index in range(count):
+        field = execution.parameters[index] if index < len(execution.parameters) else None
+        params.append(resolve_node_value(action, field))
+    return params
+
+
+def _wants_context(handler, param_count: int) -> bool:
+    try:
+        sig = inspect.signature(handler)
+    except (TypeError, ValueError):
+        return False
+    positional = [
+        p
+        for p in sig.parameters.values()
+        if p.kind in (p.POSITIONAL_ONLY, p.POSITIONAL_OR_KEYWORD)
+    ]
+    # A `*args` handler has no fixed positionals and never gets a context.
+    return len(positional) == param_count + 1
+
+
+def _to_node_value(action, value) -> execution_result_pb2.NodeValueExecutionResult:
+    """Wrap a handler's return value in a ``NodeValueExecutionResult``.
+
+    Raw data goes out as a value; a returned sub flow function is registered on the
+    action and reported as a ``SubFlowFunctionResult`` so the flow can invoke it later.
+    """
+    definition = as_sub_flow_function_definition(value)
+    if definition is not None:
+        return execution_result_pb2.NodeValueExecutionResult(
+            sub_flow_function_result=build_sub_flow_function_result(action, definition)
+        )
+    return execution_result_pb2.NodeValueExecutionResult(
+        raw_value=construct_value(value if value is not None else None)
+    )
+
+
+def handle(action, execution) -> None:
+    action.emit(CodeZeroEvent.execution_request_received, execution)
+
+    target = _resolve_target(action, execution.function_identifier)
+    if target is None:
+        if action.is_sub_flow_function_identifier(execution.function_identifier):
+            # A sub flow function this action returned earlier, whose maximum
+            # lifetime has passed (or which was deleted). Fail the node rather than
+            # staying silent, so the flow does not wait for a result that cannot come.
+            asyncio.ensure_future(
+                _send_error(
+                    action,
+                    execution,
+                    RuntimeError(
+                        "SUB_FLOW_FUNCTION_EXPIRED",
+                        f"Sub flow function {execution.function_identifier} is no "
+                        f"longer registered: its maximum lifetime has passed",
+                    ),
+                    _now_micros(),
+                )
+            )
+            return
+        print("Received execution request for unknown function:", execution.function_identifier)
+        return
+
+    params = _build_params(action, execution, target)
+
+    conf = action.configs.get(execution.project_id) or ProjectConfiguration(
+        project_id=0,
+        config_values=[],
+        find_config=lambda identifier: None,
+    )
+
+    from hercules.types import FunctionContext
+
+    context = FunctionContext(
+        project_id=execution.project_id,
+        execution_id=execution.execution_identifier,
+        matched_config=conf,
+        execute_flow=lambda flow_id, payload=None: action.execute_flow(flow_id, payload),
+    )
+
+    started_at = _now_micros()
+    handler = target.handler
+    all_params = (
+        [context, *params] if _wants_context(handler, len(params)) else params
+    )
+
+    asyncio.ensure_future(_run(action, execution, handler, all_params, started_at))
+
+
+async def _run(action, execution, handler, all_params, started_at) -> None:
+    try:
+        value = handler(*all_params)
+        if inspect.isawaitable(value):
+            value = await value
+        finished_at = _now_micros()
+        request = action_pb2.ActionTransferRequest(
+            result=action_pb2.ActionExecutionResponse(
+                execution_identifier=execution.execution_identifier,
+                node_result=execution_result_pb2.NodeExecutionResult(
+                    started_at=started_at,
+                    finished_at=finished_at,
+                    parameter_results=[],
+                    success=_to_node_value(action, value),
+                ),
+            )
+        )
+        await action.send(request)
+    except Exception as error:  # noqa: BLE001
+        await _send_error(action, execution, error, started_at)
+
+
+async def _send_error(action, execution, error, started_at) -> None:
+    """Report a failed execution back to Aquila."""
+    finished_at = _now_micros()
+    is_runtime_error = isinstance(error, RuntimeError)
+    proto_error = errors_pb2.Error(
+        code=error.code if is_runtime_error else "UNKNOWN_ERROR",
+        category="RUNTIME",
+        message=(error.description or str(error)) if is_runtime_error else str(error),
+        timestamp=finished_at,
+        version=action.version,
+    )
+    request = action_pb2.ActionTransferRequest(
+        result=action_pb2.ActionExecutionResponse(
+            execution_identifier=execution.execution_identifier,
+            node_result=execution_result_pb2.NodeExecutionResult(
+                started_at=started_at,
+                finished_at=finished_at,
+                parameter_results=[],
+                error=proto_error,
+            ),
+        )
+    )
+    try:
+        await action.send(request)
+    except Exception as err:  # noqa: BLE001
+        print("Failed to send execution error:", err)

{code0_hercules-1.5.0 → code0_hercules-1.7.0}/hercules/definitions/rest_action/runtime_flow_types/rest.py

@@ -4,7 +4,7 @@ from hercules.decorators.event import EventSetting
 
 
 @Identifier("REST")
-@Signature("<A extends REST_AUTH_TYPE, T>(http_schema: HTTP_SCHEMA, http_url: HTTP_URL, http_method: HTTP_METHOD, http_auth: A, http_auth_value: REST_AUTH_VALUE<A>, input_schema: TYPE<T>): REST_ADAPTER_INPUT<T>")
+@Signature("<A extends REST_AUTH_TYPE, T extends TYPE>(http_schema: HTTP_SCHEMA, http_url: HTTP_URL, http_method: HTTP_METHOD, http_auth: A, http_auth_value: REST_AUTH_VALUE<A>, input_schema: T): REST_ADAPTER_INPUT<T>")
 @Name({"code": "en-US", "content": "Webhook"})
 @Description({"code": "en-US", "content": "A Webhook is an HTTP endpoint that listens for incoming requests from external services or clients, allowing you to react to events in real time using standard HTTP methods like GET, POST, PUT, and DELETE."})
 @DisplayMessage({"code": "en-US", "content": "Webhook on ${http_method} at ${http_url}"})

{code0_hercules-1.5.0 → code0_hercules-1.7.0}/hercules/definitions/taurus_control/runtime_functions/std_control_if_else.py

@@ -10,7 +10,7 @@ from hercules.decorators.function import Parameter
 @Name({"code": "en-US", "content": "If-Else"})
 @Description({"code": "en-US", "content": "Evaluates a condition and executes either the Then Runnable or the Else Runnable."})
 @Documentation({"code": "en-US", "content": "Evaluates a boolean condition. If true, executes the Runnable. Otherwise executes the Else Runnable."})
-@DisplayMessage({"code": "en-US", "content": "If ${condition} is True do ${then_runnable} else ${else_runnable}"})
+@DisplayMessage({"code": "en-US", "content": "If ${condition} is True do ${runnable} else ${else_runnable}"})
 @Alias({"code": "en-US", "content": "if_else;control;std;if;else"})
 @DisplayIcon("tabler:arrow-ramp-right")
 @Parameter({"runtime_name": "condition", "name": [{"code": "en-US", "content": "Condition"}], "description": [{"code": "en-US", "content": "Boolean that determines which branch to execute. If true the Runnable runs otherwise the Else Runnable runs."}]})

{code0_hercules-1.5.0 → code0_hercules-1.7.0}/hercules/definitions/taurus_http/runtime_functions/http_request_send.py

@@ -6,7 +6,7 @@ from hercules.decorators.function import ThrowsError, Parameter
 
 @OmitRuntimeFunction()
 @Identifier("http::request::send")
-@Signature("<A extends HTTP_AUTH_TYPE, S extends HTTP_SCHEMA>(http_method: HTTP_METHOD, url: HTTP_URL, http_auth: A, http_auth_value: HTTP_AUTH_VALUE<A>, http_auth_place: HTTP_AUTH_PLACE<A>, http_schema: S, payload: HTTP_PAYLOAD<S>, headers?: OBJECT<{}>): HTTP_RESPONSE<any>")
+@Signature("<A extends HTTP_AUTH_TYPE, S extends HTTP_SCHEMA>(http_method: HTTP_METHOD, url: HTTP_URL, http_auth: A, http_auth_value: HTTP_AUTH_VALUE<A>, http_auth_place: HTTP_AUTH_PLACE<A>, http_schema: S, payload: HTTP_PAYLOAD<S>, headers?: OBJECT<{ [key: TEXT]: TEXT }>): HTTP_RESPONSE<any>")
 @Name({"code": "en-US", "content": "Send HTTP request"})
 @Description({"code": "en-US", "content": "Sends a request to the specified url with the given method, headers and payload, and returns the response as an HTTP_RESPONSE object. This function initiates an HTTP request to a specified endpoint, allowing you to interact with web services or APIs by sending data and receiving responses."})
 @DisplayMessage({"code": "en-US", "content": "Send request to ${url} with ${payload}"})

{code0_hercules-1.5.0 → code0_hercules-1.7.0}/hercules/internal/schema.py

@@ -133,6 +133,16 @@ def pydantic_to_type_string(model: SchemaModel) -> str:
     return json_schema_to_ts(resolved, name)
 
 
+def pydantic_to_json_schema(model: SchemaModel, mode: str) -> Dict[str, Any]:
+    """Convert a Pydantic model into a plain JSON schema dict.
+
+    ``mode`` picks which side of the model is described: ``"validation"`` for the
+    input it accepts, ``"serialization"`` for the output it produces (the Python
+    counterpart of the TypeScript SDK's zod ``io`` option).
+    """
+    return model.model_json_schema(mode=mode)
+
+
 def pydantic_to_rules(model: SchemaModel) -> List[data_type_pb2.DefinitionDataTypeRule]:
     schema = model.model_json_schema()
     rules: List[data_type_pb2.DefinitionDataTypeRule] = []

code0_hercules-1.7.0/hercules/internal/sub_flow_function.py

@@ -0,0 +1,86 @@
+"""Sub flow function support (port of ``src/internal/sub-flow-function.ts``).
+
+A runtime function's ``run`` may return a sub flow function instead of raw data.
+Hercules registers it on the action and reports it to Aquila as a
+``shared.SubFlowFunctionResult``, which the flow can then invoke like any sub flow.
+"""
+from __future__ import annotations
+
+from typing import Mapping, Optional
+
+from pydantic import BaseModel
+
+from hercules._tucana.helpers import construct_value
+from hercules.internal.schema import pydantic_to_json_schema
+from hercules.types import (
+    RuntimeError,
+    SubFlowFunctionDefinition,
+    SubFlowFunctionSchema,
+)
+from tucana.generated.shared import execution_result_pb2, flow_pb2, struct_pb2
+
+__all__ = ["as_sub_flow_function_definition", "build_sub_flow_function_result", "to_struct"]
+
+
+def as_sub_flow_function_definition(value) -> Optional[SubFlowFunctionDefinition]:
+    """Return ``value`` as a definition if ``run`` returned a sub flow function.
+
+    A sub flow function is told apart from raw data by its callable ``run``, which a
+    plain value never carries. Both a :class:`SubFlowFunctionDefinition` and a plain
+    mapping with the same keys are accepted.
+    """
+    if isinstance(value, SubFlowFunctionDefinition):
+        return value
+    if isinstance(value, Mapping) and callable(value.get("run")):
+        return SubFlowFunctionDefinition(
+            name=value.get("name"),
+            description=value.get("description") or "",
+            input_schema=value.get("input_schema") or {},
+            output_schema=value.get("output_schema") or {},
+            run=value["run"],
+        )
+    return None
+
+
+def _is_model(schema) -> bool:
+    return isinstance(schema, type) and issubclass(schema, BaseModel)
+
+
+def to_struct(schema: Optional[SubFlowFunctionSchema], mode: str) -> struct_pb2.Struct:
+    """Convert a declared schema into the ``shared.Struct`` the protobuf field expects.
+
+    A Pydantic model becomes a JSON schema first: ``mode`` is ``"validation"`` for a
+    function's input schema (what it accepts) and ``"serialization"`` for its output
+    schema (what it produces).
+    """
+    if isinstance(schema, struct_pb2.Struct):
+        return schema
+    if _is_model(schema):
+        return construct_value(pydantic_to_json_schema(schema, mode)).struct_value
+    return construct_value(schema or {}).struct_value
+
+
+def build_sub_flow_function_result(
+    action, definition: SubFlowFunctionDefinition
+) -> execution_result_pb2.SubFlowFunctionResult:
+    """Register the sub flow function and build the result reported back to Aquila.
+
+    The identifier in the result is the one Aquila sends back on an execution request
+    when the flow invokes the function.
+    """
+    if not definition.name:
+        raise RuntimeError(
+            "SUB_FLOW_FUNCTION_MISSING_NAME",
+            "A sub flow function returned from a run block must declare a name",
+        )
+    function_identifier = action.register_sub_flow_function(definition)
+    return execution_result_pb2.SubFlowFunctionResult(
+        function=flow_pb2.SubFlowFunction(
+            function_identifier=function_identifier,
+            definition_source="action",
+        ),
+        name=definition.name,
+        description=definition.description or "",
+        input_schema=to_struct(definition.input_schema, "validation"),
+        output_schema=to_struct(definition.output_schema, "serialization"),
+    )

code0_hercules-1.7.0/hercules/manager/sub_flow_function.py

@@ -0,0 +1,93 @@
+"""Sub flow function manager (port of ``src/manager/SubFlowFunctionManager.ts``)."""
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Dict, Optional
+
+from hercules.manager.base import BaseManager
+
+#: How long a returned sub flow function stays in memory and invocable: 30 minutes.
+SUB_FLOW_FUNCTION_TTL_SECONDS = 30 * 60
+
+
+class SubFlowFunctionManager(BaseManager):
+    """Sub flow functions a runtime function returned at execution time.
+
+    Keyed by the identifier reported to Aquila. Unlike the other managers this one is
+    not filled by registering classes up front: entries appear while the action runs
+    (see :meth:`hercules.action.Action.register_sub_flow_function`).
+
+    Each entry has a maximum lifetime of :data:`SUB_FLOW_FUNCTION_TTL_SECONDS`,
+    counted from when it was registered and never extended by an invocation, so a flow
+    that holds a function forever cannot grow the registry without bound. Expired
+    entries are dropped by a sweep scheduled for the next expiry, and on any read or
+    write, so an expired function is never invoked even if the sweep could not run
+    (there is no running event loop to schedule it on, for instance).
+    """
+
+    def __init__(self, ttl_seconds: float = SUB_FLOW_FUNCTION_TTL_SECONDS) -> None:
+        super().__init__()
+        self._ttl_seconds = ttl_seconds
+        # Expiry per key. Insertion order is expiry order, since the TTL is fixed.
+        self._expiries: Dict[str, float] = {}
+        self._sweep_handle: Optional[asyncio.TimerHandle] = None
+
+    @staticmethod
+    def _now() -> float:
+        # Monotonic, so a system clock change cannot postpone or trigger an expiry.
+        return time.monotonic()
+
+    def set(self, key, value):
+        # Re-insert the expiry so a replaced key moves to the back and the dict stays
+        # ordered by expiry.
+        self._expiries.pop(key, None)
+        super().set(key, value)
+        self._expiries[key] = self._now() + self._ttl_seconds
+        self.prune()
+        return self
+
+    def get(self, key):
+        self.prune()
+        return super().get(key)
+
+    def has(self, key) -> bool:
+        self.prune()
+        return super().has(key)
+
+    def delete(self, key) -> bool:
+        self._expiries.pop(key, None)
+        deleted = super().delete(key)
+        self._schedule_sweep(self._now())
+        return deleted
+
+    def clear(self) -> None:
+        self._expiries.clear()
+        super().clear()
+        self._schedule_sweep(self._now())
+
+    def prune(self, now: Optional[float] = None) -> None:
+        """Drop every entry whose lifetime has passed, then schedule the next sweep."""
+        if now is None:
+            now = self._now()
+        for key, expires_at in list(self._expiries.items()):
+            # Ordered by expiry, so the first entry still alive ends the sweep.
+            if expires_at > now:
+                break
+            del self._expiries[key]
+            super().delete(key)
+        self._schedule_sweep(now)
+
+    def _schedule_sweep(self, now: float) -> None:
+        if self._sweep_handle is not None:
+            self._sweep_handle.cancel()
+            self._sweep_handle = None
+        next_expiry = next(iter(self._expiries.values()), None)
+        if next_expiry is None:
+            return
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            # No loop to schedule on; pruning on the next read or write still applies.
+            return
+        self._sweep_handle = loop.call_later(max(0.0, next_expiry - now), self.prune)