dispatch_agents 0.9.0__py3-none-any.whl

agentservice/v1/message_pb2.py

@@ -0,0 +1,41 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: agentservice/v1/message.proto
+# Protobuf Python Version: 6.33.5
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import runtime_version as _runtime_version
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+_runtime_version.ValidateProtobufRuntimeVersion(
+    _runtime_version.Domain.PUBLIC,
+    6,
+    33,
+    5,
+    '',
+    'agentservice/v1/message.proto'
+)
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x1d\x61gentservice/v1/message.proto\x12\x0f\x61gentservice.v1\"\x9e\x01\n\x07Payload\x12\x42\n\x08metadata\x18\x01 \x03(\x0b\x32&.agentservice.v1.Payload.MetadataEntryR\x08metadata\x12\x12\n\x04\x64\x61ta\x18\x02 \x01(\x0cR\x04\x64\x61ta\x1a;\n\rMetadataEntry\x12\x10\n\x03key\x18\x01 \x01(\tR\x03key\x12\x14\n\x05value\x18\x02 \x01(\x0cR\x05value:\x02\x38\x01\x42\x80\x01\n\x13\x63om.agentservice.v1B\x0cMessageProtoP\x01\xa2\x02\x03\x41XX\xaa\x02\x0f\x41gentservice.V1\xca\x02\x0f\x41gentservice\\V1\xe2\x02\x1b\x41gentservice\\V1\\GPBMetadata\xea\x02\x10\x41gentservice::V1b\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'agentservice.v1.message_pb2', _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+  _globals['DESCRIPTOR']._loaded_options = None
+  _globals['DESCRIPTOR']._serialized_options = b'\n\023com.agentservice.v1B\014MessageProtoP\001\242\002\003AXX\252\002\017Agentservice.V1\312\002\017Agentservice\\V1\342\002\033Agentservice\\V1\\GPBMetadata\352\002\020Agentservice::V1'
+  _globals['_PAYLOAD_METADATAENTRY']._loaded_options = None
+  _globals['_PAYLOAD_METADATAENTRY']._serialized_options = b'8\001'
+  _globals['_PAYLOAD']._serialized_start=51
+  _globals['_PAYLOAD']._serialized_end=209
+  _globals['_PAYLOAD_METADATAENTRY']._serialized_start=150
+  _globals['_PAYLOAD_METADATAENTRY']._serialized_end=209
+# @@protoc_insertion_point(module_scope)

agentservice/v1/message_pb2.pyi

@@ -0,0 +1,22 @@
+from google.protobuf.internal import containers as _containers
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import message as _message
+from collections.abc import Mapping as _Mapping
+from typing import ClassVar as _ClassVar, Optional as _Optional
+
+DESCRIPTOR: _descriptor.FileDescriptor
+
+class Payload(_message.Message):
+    __slots__ = ("metadata", "data")
+    class MetadataEntry(_message.Message):
+        __slots__ = ("key", "value")
+        KEY_FIELD_NUMBER: _ClassVar[int]
+        VALUE_FIELD_NUMBER: _ClassVar[int]
+        key: str
+        value: bytes
+        def __init__(self, key: _Optional[str] = ..., value: _Optional[bytes] = ...) -> None: ...
+    METADATA_FIELD_NUMBER: _ClassVar[int]
+    DATA_FIELD_NUMBER: _ClassVar[int]
+    metadata: _containers.ScalarMap[str, bytes]
+    data: bytes
+    def __init__(self, metadata: _Optional[_Mapping[str, bytes]] = ..., data: _Optional[bytes] = ...) -> None: ...

agentservice/v1/message_pb2_grpc.py

@@ -0,0 +1,4 @@
+# Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
+"""Client and server classes corresponding to protobuf-defined services."""
+import grpc
+

agentservice/v1/request_response_pb2.py

@@ -0,0 +1,46 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: agentservice/v1/request_response.proto
+# Protobuf Python Version: 6.33.5
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import runtime_version as _runtime_version
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+_runtime_version.ValidateProtobufRuntimeVersion(
+    _runtime_version.Domain.PUBLIC,
+    6,
+    33,
+    5,
+    '',
+    'agentservice/v1/request_response.proto'
+)
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+from agentservice.v1 import message_pb2 as agentservice_dot_v1_dot_message__pb2
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n&agentservice/v1/request_response.proto\x12\x0f\x61gentservice.v1\x1a\x1d\x61gentservice/v1/message.proto\"\xde\x01\n\rInvokeRequest\x12#\n\rfunction_name\x18\x01 \x01(\tR\x0c\x66unctionName\x12\x32\n\x07payload\x18\x02 \x01(\x0b\x32\x18.agentservice.v1.PayloadR\x07payload\x12\x10\n\x03uid\x18\x03 \x01(\tR\x03uid\x12\x19\n\x08trace_id\x18\x04 \x01(\tR\x07traceId\x12\x0e\n\x02ts\x18\x06 \x01(\tR\x02ts\x12\x14\n\x05topic\x18\x07 \x01(\tR\x05topic\x12!\n\x0cmessage_type\x18\x08 \x01(\tR\x0bmessageType\"]\n\x0eInvokeResponse\x12\x30\n\x06result\x18\x01 \x01(\x0b\x32\x18.agentservice.v1.PayloadR\x06result\x12\x19\n\x08is_error\x18\x02 \x01(\x08R\x07isError\"\x14\n\x12HealthCheckRequest\"\xf3\x01\n\x13HealthCheckResponse\x12J\n\x06status\x18\x01 \x01(\x0e\x32\x32.agentservice.v1.HealthCheckResponse.ServingStatusR\x06status\"\x8f\x01\n\rServingStatus\x12\x1e\n\x1aSERVING_STATUS_UNSPECIFIED\x10\x00\x12\x1a\n\x16SERVING_STATUS_SERVING\x10\x01\x12\x1e\n\x1aSERVING_STATUS_NOT_SERVING\x10\x02\x12\"\n\x1eSERVING_STATUS_SERVICE_UNKNOWN\x10\x03\x42\x88\x01\n\x13\x63om.agentservice.v1B\x14RequestResponseProtoP\x01\xa2\x02\x03\x41XX\xaa\x02\x0f\x41gentservice.V1\xca\x02\x0f\x41gentservice\\V1\xe2\x02\x1b\x41gentservice\\V1\\GPBMetadata\xea\x02\x10\x41gentservice::V1b\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'agentservice.v1.request_response_pb2', _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+  _globals['DESCRIPTOR']._loaded_options = None
+  _globals['DESCRIPTOR']._serialized_options = b'\n\023com.agentservice.v1B\024RequestResponseProtoP\001\242\002\003AXX\252\002\017Agentservice.V1\312\002\017Agentservice\\V1\342\002\033Agentservice\\V1\\GPBMetadata\352\002\020Agentservice::V1'
+  _globals['_INVOKEREQUEST']._serialized_start=91
+  _globals['_INVOKEREQUEST']._serialized_end=313
+  _globals['_INVOKERESPONSE']._serialized_start=315
+  _globals['_INVOKERESPONSE']._serialized_end=408
+  _globals['_HEALTHCHECKREQUEST']._serialized_start=410
+  _globals['_HEALTHCHECKREQUEST']._serialized_end=430
+  _globals['_HEALTHCHECKRESPONSE']._serialized_start=433
+  _globals['_HEALTHCHECKRESPONSE']._serialized_end=676
+  _globals['_HEALTHCHECKRESPONSE_SERVINGSTATUS']._serialized_start=533
+  _globals['_HEALTHCHECKRESPONSE_SERVINGSTATUS']._serialized_end=676
+# @@protoc_insertion_point(module_scope)

agentservice/v1/request_response_pb2.pyi

@@ -0,0 +1,54 @@
+from agentservice.v1 import message_pb2 as _message_pb2
+from google.protobuf.internal import enum_type_wrapper as _enum_type_wrapper
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import message as _message
+from collections.abc import Mapping as _Mapping
+from typing import ClassVar as _ClassVar, Optional as _Optional, Union as _Union
+
+DESCRIPTOR: _descriptor.FileDescriptor
+
+class InvokeRequest(_message.Message):
+    __slots__ = ("function_name", "payload", "uid", "trace_id", "ts", "topic", "message_type")
+    FUNCTION_NAME_FIELD_NUMBER: _ClassVar[int]
+    PAYLOAD_FIELD_NUMBER: _ClassVar[int]
+    UID_FIELD_NUMBER: _ClassVar[int]
+    TRACE_ID_FIELD_NUMBER: _ClassVar[int]
+    TS_FIELD_NUMBER: _ClassVar[int]
+    TOPIC_FIELD_NUMBER: _ClassVar[int]
+    MESSAGE_TYPE_FIELD_NUMBER: _ClassVar[int]
+    function_name: str
+    payload: _message_pb2.Payload
+    uid: str
+    trace_id: str
+    ts: str
+    topic: str
+    message_type: str
+    def __init__(self, function_name: _Optional[str] = ..., payload: _Optional[_Union[_message_pb2.Payload, _Mapping]] = ..., uid: _Optional[str] = ..., trace_id: _Optional[str] = ..., ts: _Optional[str] = ..., topic: _Optional[str] = ..., message_type: _Optional[str] = ...) -> None: ...
+
+class InvokeResponse(_message.Message):
+    __slots__ = ("result", "is_error")
+    RESULT_FIELD_NUMBER: _ClassVar[int]
+    IS_ERROR_FIELD_NUMBER: _ClassVar[int]
+    result: _message_pb2.Payload
+    is_error: bool
+    def __init__(self, result: _Optional[_Union[_message_pb2.Payload, _Mapping]] = ..., is_error: _Optional[bool] = ...) -> None: ...
+
+class HealthCheckRequest(_message.Message):
+    __slots__ = ()
+    def __init__(self) -> None: ...
+
+class HealthCheckResponse(_message.Message):
+    __slots__ = ("status",)
+    class ServingStatus(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
+        __slots__ = ()
+        SERVING_STATUS_UNSPECIFIED: _ClassVar[HealthCheckResponse.ServingStatus]
+        SERVING_STATUS_SERVING: _ClassVar[HealthCheckResponse.ServingStatus]
+        SERVING_STATUS_NOT_SERVING: _ClassVar[HealthCheckResponse.ServingStatus]
+        SERVING_STATUS_SERVICE_UNKNOWN: _ClassVar[HealthCheckResponse.ServingStatus]
+    SERVING_STATUS_UNSPECIFIED: HealthCheckResponse.ServingStatus
+    SERVING_STATUS_SERVING: HealthCheckResponse.ServingStatus
+    SERVING_STATUS_NOT_SERVING: HealthCheckResponse.ServingStatus
+    SERVING_STATUS_SERVICE_UNKNOWN: HealthCheckResponse.ServingStatus
+    STATUS_FIELD_NUMBER: _ClassVar[int]
+    status: HealthCheckResponse.ServingStatus
+    def __init__(self, status: _Optional[_Union[HealthCheckResponse.ServingStatus, str]] = ...) -> None: ...

agentservice/v1/request_response_pb2_grpc.py

@@ -0,0 +1,4 @@
+# Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
+"""Client and server classes corresponding to protobuf-defined services."""
+import grpc
+

agentservice/v1/service_pb2.py

@@ -0,0 +1,43 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: agentservice/v1/service.proto
+# Protobuf Python Version: 6.33.5
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import runtime_version as _runtime_version
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+_runtime_version.ValidateProtobufRuntimeVersion(
+    _runtime_version.Domain.PUBLIC,
+    6,
+    33,
+    5,
+    '',
+    'agentservice/v1/service.proto'
+)
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+from agentservice.v1 import request_response_pb2 as agentservice_dot_v1_dot_request__response__pb2
+from google.api import annotations_pb2 as google_dot_api_dot_annotations__pb2
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x1d\x61gentservice/v1/service.proto\x12\x0f\x61gentservice.v1\x1a&agentservice/v1/request_response.proto\x1a\x1cgoogle/api/annotations.proto2\xf2\x01\n\x0c\x41gentService\x12j\n\x06Invoke\x12\x1e.agentservice.v1.InvokeRequest\x1a\x1f.agentservice.v1.InvokeResponse\"\x1f\x82\xd3\xe4\x93\x02\x19\"\x14/api/v1/agent/invoke:\x01*\x12v\n\x0bHealthCheck\x12#.agentservice.v1.HealthCheckRequest\x1a$.agentservice.v1.HealthCheckResponse\"\x1c\x82\xd3\xe4\x93\x02\x16\x12\x14/api/v1/agent/healthB\x80\x01\n\x13\x63om.agentservice.v1B\x0cServiceProtoP\x01\xa2\x02\x03\x41XX\xaa\x02\x0f\x41gentservice.V1\xca\x02\x0f\x41gentservice\\V1\xe2\x02\x1b\x41gentservice\\V1\\GPBMetadata\xea\x02\x10\x41gentservice::V1b\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'agentservice.v1.service_pb2', _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+  _globals['DESCRIPTOR']._loaded_options = None
+  _globals['DESCRIPTOR']._serialized_options = b'\n\023com.agentservice.v1B\014ServiceProtoP\001\242\002\003AXX\252\002\017Agentservice.V1\312\002\017Agentservice\\V1\342\002\033Agentservice\\V1\\GPBMetadata\352\002\020Agentservice::V1'
+  _globals['_AGENTSERVICE'].methods_by_name['Invoke']._loaded_options = None
+  _globals['_AGENTSERVICE'].methods_by_name['Invoke']._serialized_options = b'\202\323\344\223\002\031\"\024/api/v1/agent/invoke:\001*'
+  _globals['_AGENTSERVICE'].methods_by_name['HealthCheck']._loaded_options = None
+  _globals['_AGENTSERVICE'].methods_by_name['HealthCheck']._serialized_options = b'\202\323\344\223\002\026\022\024/api/v1/agent/health'
+  _globals['_AGENTSERVICE']._serialized_start=121
+  _globals['_AGENTSERVICE']._serialized_end=363
+# @@protoc_insertion_point(module_scope)

agentservice/v1/service_pb2.pyi

@@ -0,0 +1,6 @@
+from agentservice.v1 import request_response_pb2 as _request_response_pb2
+from google.api import annotations_pb2 as _annotations_pb2
+from google.protobuf import descriptor as _descriptor
+from typing import ClassVar as _ClassVar
+
+DESCRIPTOR: _descriptor.FileDescriptor

agentservice/v1/service_pb2_grpc.py

@@ -0,0 +1,129 @@
+# Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
+"""Client and server classes corresponding to protobuf-defined services."""
+import grpc
+
+from agentservice.v1 import request_response_pb2 as agentservice_dot_v1_dot_request__response__pb2
+
+
+class AgentServiceStub(object):
+    """AgentService provides a simple RPC interface that mirrors the agent_sidecar
+    temporal worker's activity API for invoking agents and awaiting results.
+    """
+
+    def __init__(self, channel):
+        """Constructor.
+
+        Args:
+            channel: A grpc.Channel.
+        """
+        self.Invoke = channel.unary_unary(
+                '/agentservice.v1.AgentService/Invoke',
+                request_serializer=agentservice_dot_v1_dot_request__response__pb2.InvokeRequest.SerializeToString,
+                response_deserializer=agentservice_dot_v1_dot_request__response__pb2.InvokeResponse.FromString,
+                _registered_method=True)
+        self.HealthCheck = channel.unary_unary(
+                '/agentservice.v1.AgentService/HealthCheck',
+                request_serializer=agentservice_dot_v1_dot_request__response__pb2.HealthCheckRequest.SerializeToString,
+                response_deserializer=agentservice_dot_v1_dot_request__response__pb2.HealthCheckResponse.FromString,
+                _registered_method=True)
+
+
+class AgentServiceServicer(object):
+    """AgentService provides a simple RPC interface that mirrors the agent_sidecar
+    temporal worker's activity API for invoking agents and awaiting results.
+    """
+
+    def Invoke(self, request, context):
+        """Invoke invokes an agent and waits for the result.
+        This mirrors the temporal activity API used by the agent_sidecar worker.
+        """
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+    def HealthCheck(self, request, context):
+        """Check performs a health check on the agent.
+        """
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+
+def add_AgentServiceServicer_to_server(servicer, server):
+    rpc_method_handlers = {
+            'Invoke': grpc.unary_unary_rpc_method_handler(
+                    servicer.Invoke,
+                    request_deserializer=agentservice_dot_v1_dot_request__response__pb2.InvokeRequest.FromString,
+                    response_serializer=agentservice_dot_v1_dot_request__response__pb2.InvokeResponse.SerializeToString,
+            ),
+            'HealthCheck': grpc.unary_unary_rpc_method_handler(
+                    servicer.HealthCheck,
+                    request_deserializer=agentservice_dot_v1_dot_request__response__pb2.HealthCheckRequest.FromString,
+                    response_serializer=agentservice_dot_v1_dot_request__response__pb2.HealthCheckResponse.SerializeToString,
+            ),
+    }
+    generic_handler = grpc.method_handlers_generic_handler(
+            'agentservice.v1.AgentService', rpc_method_handlers)
+    server.add_generic_rpc_handlers((generic_handler,))
+    server.add_registered_method_handlers('agentservice.v1.AgentService', rpc_method_handlers)
+
+
+ # This class is part of an EXPERIMENTAL API.
+class AgentService(object):
+    """AgentService provides a simple RPC interface that mirrors the agent_sidecar
+    temporal worker's activity API for invoking agents and awaiting results.
+    """
+
+    @staticmethod
+    def Invoke(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_unary(
+            request,
+            target,
+            '/agentservice.v1.AgentService/Invoke',
+            agentservice_dot_v1_dot_request__response__pb2.InvokeRequest.SerializeToString,
+            agentservice_dot_v1_dot_request__response__pb2.InvokeResponse.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)
+
+    @staticmethod
+    def HealthCheck(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_unary(
+            request,
+            target,
+            '/agentservice.v1.AgentService/HealthCheck',
+            agentservice_dot_v1_dot_request__response__pb2.HealthCheckRequest.SerializeToString,
+            agentservice_dot_v1_dot_request__response__pb2.HealthCheckResponse.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)

dispatch_agents/__init__.py

@@ -0,0 +1,281 @@
+import os
+import sys
+import tempfile
+from pathlib import Path
+
+# Add SDK root to Python path so generated protobuf files can import
+# using their package structure (e.g., "from agentservice.v1 import ...")
+_sdk_root = str(Path(__file__).parent.parent)
+if _sdk_root not in sys.path:
+    sys.path.insert(0, _sdk_root)
+
+
+def get_data_dir() -> Path:
+    """Get the data directory for persistent storage.
+
+    In production, this returns /data (EFS mount point).
+    In local dev mode (`dispatch agent dev`), this returns the mock data directory
+    set by DISPATCH_DEV_DATA_DIR environment variable.
+
+    Returns:
+        Path to the data directory
+
+    Example:
+        from dispatch_agents import get_data_dir
+
+        DATA_DIR = get_data_dir()
+        my_file = DATA_DIR / "myfile.txt"
+        my_file.write_text("hello")
+    """
+    dev_data_dir = os.environ.get("DISPATCH_DEV_DATA_DIR")
+    if dev_data_dir:
+        # In dev mode, use the mock data directory
+        return Path(dev_data_dir) / "data"
+    # In production, use the EFS mount at /data
+    return Path("/data")
+
+
+# =============================================================================
+# Dev Mode Audit Hook - Restricts writes to allowed directories
+# =============================================================================
+
+
+class DisallowedWriteError(Exception):
+    """Raised when an agent attempts to write outside allowed directories in dev mode."""
+
+    pass
+
+
+_audit_hook_blocked: set[str] = set()  # Track blocked paths to avoid duplicate errors
+_audit_hook_allowed_prefixes: list[str] = []  # Computed once at startup
+
+
+def _init_allowed_prefixes() -> list[str]:
+    """Compute the list of allowed write prefixes for dev mode.
+
+    Allowed locations:
+    1. get_data_dir() - the mock data directory
+    2. /tmp - temporary files (and system temp directory)
+    3. Agent folder - where the agent code lives (derived from DISPATCH_DEV_DATA_DIR)
+
+    All paths are resolved to their canonical form to handle symlinks
+    (e.g., macOS /var -> /private/var).
+    """
+    allowed = []
+
+    def resolve_path(p: str) -> str:
+        """Resolve path to canonical form, handling symlinks."""
+        try:
+            return str(Path(p).resolve())
+        except (OSError, ValueError):
+            return p
+
+    # 1. The data directory from get_data_dir()
+    allowed.append(resolve_path(str(get_data_dir())))
+
+    # 2. Temp directories - include both standard paths and the system's actual temp
+    # Resolve all paths to handle macOS symlinks (/var -> /private/var)
+    allowed.append(resolve_path("/tmp"))
+    allowed.append(resolve_path("/var/tmp"))
+    # macOS temp dirs (may be redundant after resolution, but included for safety)
+    allowed.append(resolve_path("/private/tmp"))
+    allowed.append(resolve_path("/private/var/tmp"))
+    # System temp directory (handles macOS /var/folders/... and other platforms)
+    allowed.append(resolve_path(tempfile.gettempdir()))
+
+    # 3. Agent folder - DISPATCH_DEV_DATA_DIR is {agent_path}/.dispatch/dev-data
+    dev_data_dir = os.environ.get("DISPATCH_DEV_DATA_DIR", "")
+    if dev_data_dir:
+        # Go up two levels: dev-data -> .dispatch -> agent_folder
+        agent_folder = str(Path(dev_data_dir).parent.parent)
+        allowed.append(resolve_path(agent_folder))
+
+    return allowed
+
+
+def _dev_mode_audit_hook(event: str, args: tuple) -> None:
+    """Block file operations that target paths outside allowed directories.
+
+    In dev mode, agents should only write to:
+    - get_data_dir() (mock persistent storage)
+    - /tmp (temporary files)
+    - The agent's own folder
+
+    This protects the developer's machine from accidental writes to arbitrary locations.
+    Use --allow-arbitrary-writes flag or DISPATCH_ALLOW_ARBITRARY_WRITES=1 to disable.
+    """
+    # Only care about file open operations that could write
+    if event != "open":
+        return
+
+    if not args or len(args) < 2:
+        return
+
+    raw_path = str(args[0])
+    mode = args[1] if len(args) > 1 else ""
+
+    # Only check write operations (mode contains 'w', 'a', 'x', or '+')
+    # Skip read-only operations
+    if isinstance(mode, str):
+        if "w" not in mode and "a" not in mode and "x" not in mode and "+" not in mode:
+            return
+    elif isinstance(mode, int):
+        # For integer flags, check if it's a write mode
+        # os.O_WRONLY = 1, os.O_RDWR = 2, os.O_APPEND = 1024, os.O_CREAT = 512
+        import os as os_module
+
+        write_flags = getattr(os_module, "O_WRONLY", 1) | getattr(
+            os_module, "O_RDWR", 2
+        )
+        if not (mode & write_flags):
+            return
+
+    # Resolve relative paths to absolute (e.g., "../test" -> "/absolute/path/test")
+    # This ensures path traversal attacks like "../../../etc/passwd" are caught
+    try:
+        path = str(Path(raw_path).resolve())
+    except (OSError, ValueError):
+        # If path resolution fails, use the raw path
+        path = raw_path
+
+    # Check if path is within any allowed prefix
+    for prefix in _audit_hook_allowed_prefixes:
+        if path.startswith(prefix):
+            return  # Allowed
+
+    # Track whether we've already shown the detailed error for this path
+    # (to reduce noise), but ALWAYS raise the error to block the write
+    show_details = path not in _audit_hook_blocked
+    _audit_hook_blocked.add(path)
+
+    if show_details:
+        allowed_locations = ", ".join(_audit_hook_allowed_prefixes[:3])  # Show first 3
+        raise DisallowedWriteError(
+            f"Write operation to '{path}' blocked - outside allowed directories.\n"
+            f"In dev mode, writes are only allowed to: {allowed_locations}\n"
+            "Use get_data_dir() for persistent storage.\n"
+            "To disable this check, run with: dispatch agent dev --allow-arbitrary-writes"
+        )
+    else:
+        # Subsequent attempts to the same path: still block, but shorter message
+        raise DisallowedWriteError(f"Write to '{path}' blocked (repeated attempt)")
+
+
+from .agent_service import AgentServiceClient
+from .events import (
+    HANDLER_METADATA,
+    REGISTERED_HANDLERS,
+    TOPIC_HANDLERS,
+    AsyncHandler,
+    BasePayload,
+    HandlerMetadata,
+    dispatch_message,
+    emit_event,
+    fn,
+    get_current_invocation_id,
+    get_current_parent_id,
+    get_current_trace_id,
+    get_handler_metadata,
+    get_handler_schemas,
+    get_invocation_id_for_trace,
+    init,
+    invoke,
+    on,
+    run_init_hook,
+)
+from .invocation import InvocationStatus
+from .llm import LLMFunctionCall, LLMToolCall, extra_headers, get_extra_llm_headers
+from .mcp import McpHttpServerConfig, get_mcp_client, get_mcp_servers_config
+from .memory import MemoryClient, memory
+from .models import (
+    Agent,
+    AgentContainerStatus,
+    BaseMessage,
+    FeedbackSentiment,
+    FeedbackType,
+    FunctionMessage,
+    JsonSchema,
+    KVGetResponse,
+    LLMCallMessage,
+    MemoryWriteResponse,
+    Message,
+    ScheduleMessage,
+    SessionGetResponse,
+    StrictBaseModel,
+    TopicMessage,
+)
+
+__all__ = [
+    # storage and dev mode isolation
+    "get_data_dir",
+    "DisallowedWriteError",
+    # agent service
+    "AgentServiceClient",
+    # events - decorators and client functions
+    "on",
+    "init",
+    "fn",
+    "invoke",
+    "dispatch_message",
+    "emit_event",
+    "run_init_hook",
+    # events - context and metadata
+    "get_current_trace_id",
+    "get_current_invocation_id",
+    "get_current_parent_id",
+    "get_invocation_id_for_trace",
+    "get_handler_schemas",
+    "get_handler_metadata",
+    # events - registries and types
+    "REGISTERED_HANDLERS",  # handler_name -> AsyncHandler
+    "HANDLER_METADATA",  # handler_name -> HandlerMetadata
+    "TOPIC_HANDLERS",  # topic -> list of handler_names
+    "AsyncHandler",  # Type alias for handler functions
+    "HandlerMetadata",  # Pydantic model for handler metadata
+    "BasePayload",
+    # invocation
+    "InvocationStatus",
+    # models - Message types (discriminated union pattern)
+    "BaseMessage",
+    "TopicMessage",
+    "FunctionMessage",
+    "ScheduleMessage",
+    "LLMCallMessage",
+    "Message",  # Union type alias (TopicMessage | FunctionMessage | ScheduleMessage)
+    "Agent",
+    "AgentContainerStatus",
+    "StrictBaseModel",
+    # memory
+    "MemoryClient",
+    "memory",
+    "MemoryWriteResponse",
+    "KVGetResponse",
+    "SessionGetResponse",
+    # type aliases
+    "JsonSchema",
+    # feedback types
+    "FeedbackType",
+    "FeedbackSentiment",
+    # mcp
+    "get_mcp_client",
+    "get_mcp_servers_config",
+    "McpHttpServerConfig",
+    # llm
+    "LLMFunctionCall",
+    "LLMToolCall",
+    "extra_headers",
+    "get_extra_llm_headers",
+]
+
+# =============================================================================
+# Install Dev Mode Audit Hook (MUST be after all imports to avoid blocking .pyc writes)
+# =============================================================================
+
+# Install the audit hook only in dev mode, unless arbitrary writes are explicitly allowed
+if os.environ.get("DISPATCH_DEV_DATA_DIR") and not os.environ.get(
+    "DISPATCH_ALLOW_ARBITRARY_WRITES"
+):
+    # IMPORTANT: Initialize allowed prefixes BEFORE installing the hook.
+    # This avoids recursive calls when tempfile.gettempdir() triggers file operations.
+    _audit_hook_allowed_prefixes = _init_allowed_prefixes()
+    sys.addaudithook(_dev_mode_audit_hook)