handler-ai 0.1.0__py3-none-any.whl

handler_contracts/__init__.py

@@ -0,0 +1,642 @@
+"""Reference implementation of the Handler contracts (docs/dev/contracts.md).
+
+Each name is imported from its module on first use (PEP 562): `from handler_contracts import
+SandboxSpec` loads sandbox.py and common.py only, so the sandbox executable (A), started for every
+runtime call, does not load the control plane's models. The imports below say what comes from
+where: for type checkers, and read by `__getattr__`.
+"""
+
+import ast
+import importlib
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .account import ACCOUNT_API_VERSION, Account
+    from .acp_endpoint import (
+        ACP_ENDPOINT_API_VERSION,
+        ACP_SUBPROTOCOL,
+        BEARER_SUBPROTOCOL_PREFIX,
+        BLOCKED_AGENT_METHOD_PREFIXES,
+        CWD_CHECKED_METHODS,
+        DEFAULT_MAX_MESSAGE_BYTES,
+        AcpCloseCode,
+        PolicyErrorCode,
+        PolicyRule,
+        SessionErrorCode,
+        acp_path,
+        session_acp_path,
+    )
+    from .addon import (
+        ADDON_API_VERSION,
+        ADDON_VERSION_FILE,
+        ADDONS_ROOT,
+        BINDING_API_VERSION,
+        AddonManifest,
+        AddonMcp,
+        AddonSecretSlot,
+        AddonSlot,
+        Binding,
+        check_binding,
+    )
+    from .agent_spec import AgentSpec, HarnessName, NeutralConfig
+    from .automation import (
+        AUTOMATION_API_VERSION,
+        AUTOMATION_FILE,
+        DEFAULT_TIMEOUT_SEC,
+        MAX_APPEND,
+        MAX_LLM_INPUT,
+        MAX_LLM_SCHEMA,
+        MIN_EVERY_MINUTES,
+        Automation,
+        AutomationAgentInput,
+        AutomationAgentRun,
+        AutomationAppCall,
+        AutomationAppend,
+        AutomationAppended,
+        AutomationCheck,
+        AutomationDefinitionRequest,
+        AutomationEvent,
+        AutomationExample,
+        AutomationLlmUsage,
+        AutomationName,
+        AutomationOnly,
+        AutomationRun,
+        AutomationServices,
+        AutomationSubject,
+        AutomationView,
+        CreateAutomationRequest,
+        LlmModel,
+        LlmRequest,
+        LlmResponse,
+        LlmUsage,
+        RunState,
+        Schedule,
+        TryAutomationRequest,
+    )
+    from .common import (
+        ANY_CONTEXT,
+        PERMISSION_MODES,
+        AbsolutePath,
+        AccessContext,
+        CacheSharing,
+        CommandSecret,
+        Confinement,
+        ContextColor,
+        ContextName,
+        EgressEntry,
+        Enforcement,
+        EnvMap,
+        EnvSecret,
+        FileContent,
+        FileSecret,
+        FileSource,
+        GeneratedFile,
+        HomePath,
+        HostPath,
+        HttpMcpServer,
+        McpServer,
+        McpTransport,
+        Mount,
+        NetworkMode,
+        PermissionMode,
+        ResourceName,
+        Resources,
+        SecretPath,
+        SecretRef,
+        StdioMcpServer,
+        StoreSecret,
+        egress_target,
+        is_within,
+        mcp_transport,
+    )
+    from .control import (
+        CONTROL_API_VERSION,
+        CONTROL_BASE_PATH,
+        DEFAULT_PORT,
+        MAX_REQUEST,
+        MAX_SCHEMA_BYTES,
+        MAX_SKILL_ARCHIVE_BYTES,
+        MAX_SKILL_BYTES,
+        MAX_SKILL_FILE_BYTES,
+        SUBJECT_ROOT,
+        TOKEN_FILE_NAME,
+        AccountInfo,
+        AccountLoginRequest,
+        AccountRequest,
+        AccountStatus,
+        AddAppRequest,
+        AddonCatalogEntry,
+        AddonInfo,
+        AddonInstalled,
+        AddonInstallRequest,
+        AddonPreview,
+        AddonPreviewRequest,
+        AddonSlotInfo,
+        AdHocAgentRequest,
+        Agent,
+        AgentInterface,
+        AgentModel,
+        AgentRequest,
+        AgentSettings,
+        App,
+        AppDeployment,
+        AppLink,
+        AppLog,
+        AppSecret,
+        AppSource,
+        AppState,
+        BindingInfo,
+        BindingRequest,
+        Build,
+        BuildLog,
+        BuildState,
+        BuiltinAgent,
+        CacheFolders,
+        CacheInfo,
+        CachesInfo,
+        CacheSizes,
+        CachesRequest,
+        Connection,
+        ContextInfo,
+        ContextRequest,
+        CreateDirectoryRequest,
+        CreateKnowledgeFolderRequest,
+        CreateProjectRequest,
+        CreateSessionRequest,
+        CreateSkillRequest,
+        DeviceScope,
+        DirectoryEntry,
+        DirectoryListing,
+        EgressEvent,
+        GlobalCachesInfo,
+        HarnessInfo,
+        Health,
+        ImageUpdates,
+        ImageUpdatesRequest,
+        InboxMessage,
+        InboxStatus,
+        KnowledgeFolder,
+        KnowledgeFolderView,
+        KnowledgeListing,
+        KnowledgeNote,
+        LoginWindow,
+        ModelAccess,
+        NetworkFilterInfo,
+        PairDeviceRequest,
+        PatchAgentRequest,
+        PersonName,
+        Problem,
+        Project,
+        ProjectCachesInfo,
+        ProjectSettingsRequest,
+        ProviderInfo,
+        ProviderRequest,
+        ProviderTemplate,
+        PutSecretRequest,
+        RemoteDevice,
+        RemoteLight,
+        RemotePairing,
+        RemoteStatus,
+        RequiredHost,
+        RevealRequest,
+        ScanHit,
+        SecretInfo,
+        SecretSent,
+        Session,
+        SessionChanges,
+        SessionFile,
+        SessionFileChange,
+        SessionFolder,
+        SessionFolderEntry,
+        SessionFound,
+        SessionInput,
+        SessionLifecycle,
+        SessionMount,
+        SessionMounts,
+        SessionOrigin,
+        SessionOutput,
+        SessionSubject,
+        SetAppPersonsRequest,
+        SetAppSecretRequest,
+        SetAppShortcutRequest,
+        SetKnowledgeRootRequest,
+        SetRemoteGatewayRequest,
+        SetSessionRemoteRequest,
+        SkillFile,
+        SkillFileRequest,
+        SkillInfo,
+        SkillName,
+        SkillRequest,
+        SkillScan,
+        SkillUrlRequest,
+        ToolboxContainerfile,
+        ToolboxContainerfileUpdate,
+        ToolboxInfo,
+        WorkFolderInfo,
+        WorkFolders,
+        WorkFoldersInfo,
+    )
+    from .harness import (
+        HARNESS_API_VERSION,
+        HARNESS_LAUNCH_API_VERSION,
+        IMAGE_VERSION_FILE,
+        CacheDeclaration,
+        CacheName,
+        ConfigFileSlot,
+        HarnessDescriptor,
+        HarnessLaunch,
+        LoginRecipe,
+        PermissionMapping,
+        SessionDefaults,
+        StateSlot,
+        TerminalCommand,
+        ToolboxManifest,
+    )
+    from .miniapp import (
+        API_PREFIX,
+        APP_API_SOCKET,
+        APP_CODE_DIR,
+        APP_HOME,
+        APP_RUN_DIR,
+        APP_SOCKET,
+        HEALTH_PATH,
+        MANIFEST_FILE,
+        MINIAPP_API_VERSION,
+        PERSON_HEADER,
+        RUNTIME_IMAGE,
+        AppName,
+        MiniAppFile,
+        MiniAppManifest,
+        MiniAppNeeds,
+        MiniAppServer,
+        MiniAppUi,
+    )
+    from .provider import PROTOCOLS, PROVIDER_API_VERSION, Protocol, Provider, ProviderModel
+    from .remote import (
+        REMOTE_API_VERSION,
+        AgentList,
+        AppHttpAnswer,
+        AppHttpParams,
+        AppList,
+        AppUi,
+        AppUiParams,
+        ClosedNotice,
+        DetachParams,
+        InboxList,
+        PushKey,
+        PushSubscribeParams,
+        PushSubscription,
+        RemoteAgent,
+        RemoteProject,
+        SessionList,
+        SharedApp,
+        SharedApps,
+        SharedSession,
+        StartedSession,
+        StartSessionParams,
+    )
+    from .sandbox import (
+        CA_BUNDLE,
+        CA_ENV,
+        DISPLAY_ENV,
+        SANDBOX_API_VERSION,
+        FilteredNetwork,
+        ImageInfo,
+        ImageMount,
+        Injection,
+        NetworkPolicy,
+        NoNetwork,
+        OpenNetwork,
+        ProxyImage,
+        RuntimeCheck,
+        RuntimeCheckItem,
+        SandboxExit,
+        SandboxSpec,
+        SandboxUser,
+        WaylandDisplay,
+    )
+    from .terminal import (
+        TerminalStart,
+        TerminalStarted,
+        terminal_path,
+    )
+
+
+__all__ = [
+    "ACCOUNT_API_VERSION",
+    "ACP_ENDPOINT_API_VERSION",
+    "ACP_SUBPROTOCOL",
+    "ADDONS_ROOT",
+    "ADDON_API_VERSION",
+    "ADDON_VERSION_FILE",
+    "ANY_CONTEXT",
+    "API_PREFIX",
+    "APP_API_SOCKET",
+    "APP_CODE_DIR",
+    "APP_HOME",
+    "APP_RUN_DIR",
+    "APP_SOCKET",
+    "AUTOMATION_API_VERSION",
+    "AUTOMATION_FILE",
+    "BEARER_SUBPROTOCOL_PREFIX",
+    "BINDING_API_VERSION",
+    "BLOCKED_AGENT_METHOD_PREFIXES",
+    "CA_BUNDLE",
+    "CA_ENV",
+    "CONTROL_API_VERSION",
+    "CONTROL_BASE_PATH",
+    "CWD_CHECKED_METHODS",
+    "DEFAULT_MAX_MESSAGE_BYTES",
+    "DEFAULT_PORT",
+    "DEFAULT_TIMEOUT_SEC",
+    "DISPLAY_ENV",
+    "HARNESS_API_VERSION",
+    "HARNESS_LAUNCH_API_VERSION",
+    "HEALTH_PATH",
+    "IMAGE_VERSION_FILE",
+    "MANIFEST_FILE",
+    "MAX_APPEND",
+    "MAX_LLM_INPUT",
+    "MAX_LLM_SCHEMA",
+    "MAX_REQUEST",
+    "MAX_SCHEMA_BYTES",
+    "MAX_SKILL_ARCHIVE_BYTES",
+    "MAX_SKILL_BYTES",
+    "MAX_SKILL_FILE_BYTES",
+    "MINIAPP_API_VERSION",
+    "MIN_EVERY_MINUTES",
+    "PERMISSION_MODES",
+    "PERSON_HEADER",
+    "PROTOCOLS",
+    "PROVIDER_API_VERSION",
+    "REMOTE_API_VERSION",
+    "RUNTIME_IMAGE",
+    "SANDBOX_API_VERSION",
+    "SUBJECT_ROOT",
+    "TOKEN_FILE_NAME",
+    "AbsolutePath",
+    "AccessContext",
+    "Account",
+    "AccountInfo",
+    "AccountLoginRequest",
+    "AccountRequest",
+    "AccountStatus",
+    "AcpCloseCode",
+    "AdHocAgentRequest",
+    "AddAppRequest",
+    "AddonCatalogEntry",
+    "AddonInfo",
+    "AddonInstallRequest",
+    "AddonInstalled",
+    "AddonManifest",
+    "AddonMcp",
+    "AddonPreview",
+    "AddonPreviewRequest",
+    "AddonSecretSlot",
+    "AddonSlot",
+    "AddonSlotInfo",
+    "Agent",
+    "AgentInterface",
+    "AgentList",
+    "AgentModel",
+    "AgentRequest",
+    "AgentSettings",
+    "AgentSpec",
+    "App",
+    "AppDeployment",
+    "AppHttpAnswer",
+    "AppHttpParams",
+    "AppLink",
+    "AppList",
+    "AppLog",
+    "AppName",
+    "AppSecret",
+    "AppSource",
+    "AppState",
+    "AppUi",
+    "AppUiParams",
+    "Automation",
+    "AutomationAgentInput",
+    "AutomationAgentRun",
+    "AutomationAppCall",
+    "AutomationAppend",
+    "AutomationAppended",
+    "AutomationCheck",
+    "AutomationDefinitionRequest",
+    "AutomationEvent",
+    "AutomationExample",
+    "AutomationLlmUsage",
+    "AutomationName",
+    "AutomationOnly",
+    "AutomationRun",
+    "AutomationServices",
+    "AutomationSubject",
+    "AutomationView",
+    "Binding",
+    "BindingInfo",
+    "BindingRequest",
+    "Build",
+    "BuildLog",
+    "BuildState",
+    "BuiltinAgent",
+    "CacheDeclaration",
+    "CacheFolders",
+    "CacheInfo",
+    "CacheName",
+    "CacheSharing",
+    "CacheSizes",
+    "CachesInfo",
+    "CachesRequest",
+    "ClosedNotice",
+    "CommandSecret",
+    "ConfigFileSlot",
+    "Confinement",
+    "Connection",
+    "ContextColor",
+    "ContextInfo",
+    "ContextName",
+    "ContextRequest",
+    "CreateAutomationRequest",
+    "CreateDirectoryRequest",
+    "CreateKnowledgeFolderRequest",
+    "CreateProjectRequest",
+    "CreateSessionRequest",
+    "CreateSkillRequest",
+    "DetachParams",
+    "DeviceScope",
+    "DirectoryEntry",
+    "DirectoryListing",
+    "EgressEntry",
+    "EgressEvent",
+    "Enforcement",
+    "EnvMap",
+    "EnvSecret",
+    "FileContent",
+    "FileSecret",
+    "FileSource",
+    "FilteredNetwork",
+    "GeneratedFile",
+    "GlobalCachesInfo",
+    "HarnessDescriptor",
+    "HarnessInfo",
+    "HarnessLaunch",
+    "HarnessName",
+    "Health",
+    "HomePath",
+    "HostPath",
+    "HttpMcpServer",
+    "ImageInfo",
+    "ImageMount",
+    "ImageUpdates",
+    "ImageUpdatesRequest",
+    "InboxList",
+    "InboxMessage",
+    "InboxStatus",
+    "Injection",
+    "KnowledgeFolder",
+    "KnowledgeFolderView",
+    "KnowledgeListing",
+    "KnowledgeNote",
+    "LlmModel",
+    "LlmRequest",
+    "LlmResponse",
+    "LlmUsage",
+    "LoginRecipe",
+    "LoginWindow",
+    "McpServer",
+    "McpTransport",
+    "MiniAppFile",
+    "MiniAppManifest",
+    "MiniAppNeeds",
+    "MiniAppServer",
+    "MiniAppUi",
+    "ModelAccess",
+    "Mount",
+    "NetworkFilterInfo",
+    "NetworkMode",
+    "NetworkPolicy",
+    "NeutralConfig",
+    "NoNetwork",
+    "OpenNetwork",
+    "PairDeviceRequest",
+    "PatchAgentRequest",
+    "PermissionMapping",
+    "PermissionMode",
+    "PersonName",
+    "PolicyErrorCode",
+    "PolicyRule",
+    "Problem",
+    "Project",
+    "ProjectCachesInfo",
+    "ProjectSettingsRequest",
+    "Protocol",
+    "Provider",
+    "ProviderInfo",
+    "ProviderModel",
+    "ProviderRequest",
+    "ProviderTemplate",
+    "ProxyImage",
+    "PushKey",
+    "PushSubscribeParams",
+    "PushSubscription",
+    "PutSecretRequest",
+    "RemoteAgent",
+    "RemoteDevice",
+    "RemoteLight",
+    "RemotePairing",
+    "RemoteProject",
+    "RemoteStatus",
+    "RequiredHost",
+    "ResourceName",
+    "Resources",
+    "RevealRequest",
+    "RunState",
+    "RuntimeCheck",
+    "RuntimeCheckItem",
+    "SandboxExit",
+    "SandboxSpec",
+    "SandboxUser",
+    "ScanHit",
+    "Schedule",
+    "SecretInfo",
+    "SecretPath",
+    "SecretRef",
+    "SecretSent",
+    "Session",
+    "SessionChanges",
+    "SessionDefaults",
+    "SessionErrorCode",
+    "SessionFile",
+    "SessionFileChange",
+    "SessionFolder",
+    "SessionFolderEntry",
+    "SessionFound",
+    "SessionInput",
+    "SessionLifecycle",
+    "SessionList",
+    "SessionMount",
+    "SessionMounts",
+    "SessionOrigin",
+    "SessionOutput",
+    "SessionSubject",
+    "SetAppPersonsRequest",
+    "SetAppSecretRequest",
+    "SetAppShortcutRequest",
+    "SetKnowledgeRootRequest",
+    "SetRemoteGatewayRequest",
+    "SetSessionRemoteRequest",
+    "SharedApp",
+    "SharedApps",
+    "SharedSession",
+    "SkillFile",
+    "SkillFileRequest",
+    "SkillInfo",
+    "SkillName",
+    "SkillRequest",
+    "SkillScan",
+    "SkillUrlRequest",
+    "StartSessionParams",
+    "StartedSession",
+    "StateSlot",
+    "StdioMcpServer",
+    "StoreSecret",
+    "TerminalCommand",
+    "TerminalStart",
+    "TerminalStarted",
+    "ToolboxContainerfile",
+    "ToolboxContainerfileUpdate",
+    "ToolboxInfo",
+    "ToolboxManifest",
+    "TryAutomationRequest",
+    "WaylandDisplay",
+    "WorkFolderInfo",
+    "WorkFolders",
+    "WorkFoldersInfo",
+    "acp_path",
+    "check_binding",
+    "egress_target",
+    "is_within",
+    "mcp_transport",
+    "session_acp_path",
+    "terminal_path",
+]
+
+
+_modules: dict[str, str] = {}  # exported name → its module, from the imports above
+
+
+def __getattr__(name: str) -> object:
+    if not _modules:
+        tree = ast.parse(Path(__file__).read_text())
+        _modules.update(
+            (alias.asname or alias.name, node.module or "")
+            for node in ast.walk(tree)
+            if isinstance(node, ast.ImportFrom) and node.level == 1
+            for alias in node.names
+        )
+    if name not in _modules:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    value = getattr(importlib.import_module(f".{_modules[name]}", __name__), name)
+    globals()[name] = value  # found directly next time
+    return value

handler_contracts/account.py

@@ -0,0 +1,36 @@
+"""Contract E — Account (`handler.account/v1`): a subscription a harness logs in with (Claude Pro, a
+ChatGPT plan). One file per account in `~/.config/handler-ai/accounts/<name>.toml`, written
+through the Control API (D.9) or by hand. Its login (its harness's `[login]`, contract B): a token
+login's `token` is a reference to the token the person gave (handler's secret store, or where they
+keep it); a file login's credential file is kept by handler, not in this file."""
+
+import tomllib
+from typing import Annotated, Literal
+
+from pydantic import Field
+
+from .common import AccessContext, SecretRef, StrictDocument
+
+ACCOUNT_API_VERSION = "handler.account/v1"
+
+
+class Account(StrictDocument):
+    api_version: Literal["handler.account/v1"]
+    harness: Annotated[str, Field(min_length=1)]
+    description: str | None = None
+    # its subscription's plan, one of its harness's `login.plans` (e.g. "pro"): told to the
+    # harness, which cannot learn it from a token login
+    plan: Annotated[str, Field(min_length=1)] | None = None
+    # its harness may use the account's own connectors (claude.ai MCP servers), where it has
+    # some (B.1 accountConnectors): they reach whatever the account connected
+    connectors: bool = False
+    # a token login's token (E2): `{secret = "accounts/<name>/token"}` when pasted through handler,
+    # or where the person keeps it (`env`, `file`, `command`); none until logged in
+    token: SecretRef | None = None
+    # the project contexts it may be used in (D.19): their names, or `any`; none: only in
+    # projects without a context and outside projects
+    contexts: list[AccessContext] = []
+
+    @classmethod
+    def from_toml(cls, text: str) -> "Account":
+        return cls.model_validate(tomllib.loads(text))