Skip to content

Configuration Package

paglets.config owns startup and launch configuration.

Responsibilities

  • Parse ~/.paglets/launch.toml.
  • Sync the bundled launch configuration on first start or when requested.
  • Resolve startup agent classes, initial state, singleton settings, and IDs.
  • Resolve resident service declarations and lifecycle settings.

Main Modules

paglets.config.startup
Defines launch-config dataclasses, bundled config loading, config sync, and startup/resident-service resolution helpers.
paglets.config.defaults
Contains package data for the bundled launch.toml configuration.

Implementation Notes

Startup config references classes by importable qualified name or by class-level startup metadata. The resolver materializes initial state through the serialization layer.

Sync behavior is controlled by LaunchConfigSyncAction and the CLI flags for interactive confirmation, forced sync, or disabling launch-config sync.

API Reference

paglets.config.startup

AutoStartSpec dataclass

Class-level marker for agents that can be started from launch config.

Source code in src/paglets/config/startup.py 
29
30
31
32
33
34
35
36
@dataclass(frozen=True, slots=True)
class AutoStartSpec:
    """Class-level marker for agents that can be started from launch config."""

    alias: str
    agent_id: str | None = None
    singleton: bool = True
    state: dict[str, Any] = field(default_factory=dict)

LaunchConfig dataclass

Parsed paglets launch config.

Source code in src/paglets/config/startup.py 
75
76
77
78
79
80
81
82
83
84
@dataclass(frozen=True, slots=True)
class LaunchConfig:
    """Parsed paglets launch config."""

    path: Path | None = None
    demo_config_id: str | None = None
    demo_config_version: str | None = None
    sync_demo_config: bool = True
    startup_agents: tuple[StartupAgentConfig, ...] = ()
    resident_services: tuple[ResidentServiceConfig, ...] = ()

LaunchConfigSyncResult dataclass

Result of syncing the bundled demo launch config to the user path.

Source code in src/paglets/config/startup.py 
87
88
89
90
91
92
93
94
95
96
97
@dataclass(frozen=True, slots=True)
class LaunchConfigSyncResult:
    """Result of syncing the bundled demo launch config to the user path."""

    action: LaunchConfigSyncAction
    path: Path
    message: str
    backup_path: Path | None = None

    def __post_init__(self) -> None:
        require_enum(self.action, LaunchConfigSyncAction, "action")

ResidentServiceConfig dataclass

One launch-config entry describing a managed resident service.

Source code in src/paglets/config/startup.py 
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
@dataclass(frozen=True, slots=True)
class ResidentServiceConfig:
    """One launch-config entry describing a managed resident service."""

    use: str | None = None
    class_name: str | None = None
    service_name: str | None = None
    enabled: bool = True
    agent_id: str | None = None
    singleton: bool = True
    lifecycle: ResidentLifecycle | None = None
    scope: ServiceScope | None = None
    idle_timeout: float | None = None
    state: dict[str, Any] = field(default_factory=dict)
    init: Any = None

    def __post_init__(self) -> None:
        if self.lifecycle is not None:
            require_enum(self.lifecycle, ResidentLifecycle, "lifecycle")
        if self.scope is not None:
            require_enum(self.scope, ServiceScope, "scope")

StartupAgentConfig dataclass

One launch-config entry describing an agent to start.

Source code in src/paglets/config/startup.py 
39
40
41
42
43
44
45
46
47
48
49
@dataclass(frozen=True, slots=True)
class StartupAgentConfig:
    """One launch-config entry describing an agent to start."""

    use: str | None = None
    class_name: str | None = None
    enabled: bool = True
    agent_id: str | None = None
    singleton: bool = True
    state: dict[str, Any] = field(default_factory=dict)
    init: Any = None
  • Services covers resident service contracts and leases.
  • Tooling covers the host CLI that loads launch configuration.