Per-User Scheduler Isolation

Isolate each gateway user's scheduled automations and suggestions with an optional principal owner key

Pass a principal when creating a scheduled automation or a suggestion, and every list / accept / dismiss / remove call is automatically scoped to that owner — one gateway user’s jobs are invisible to another’s.

Quick Start

1. Create a job for a specific user

   Set principal on a ScheduleJob. store.list(principal="alice") returns only Alice’s job, while store.list() returns everything.

   from praisonaiagents.scheduler import ScheduleJob, Schedule
   from praisonaiagents.scheduler.config_store import ConfigYamlScheduleStore
   
   store = ConfigYamlScheduleStore()
   
   store.add(ScheduleJob(
       name="morning-brief",
       schedule=Schedule(kind="cron", cron_expr="0 8 * * *"),
       message="Send Alice her morning brief",
       principal="alice",
   ))
   
   alice_jobs = store.list(principal="alice")   # → just Alice's job
   everything = store.list()                     # → every job, all owners

2. Scope a suggestion to a user

   Set principal on a Suggestion. Each owner sees only their own pending queue.

   from praisonaiagents.scheduler.suggestion_store import SuggestionStore, Suggestion
   
   store = SuggestionStore()
   
   store.add(Suggestion(
       id="sug_abc",
       blueprint_name="morning-brief",
       slots={"hour": 8},
       principal="alice",
   ))
   
   alice_pending = store.list_pending(principal="alice")   # → Alice's suggestion
   bob_pending = store.list_pending(principal="bob")        # → empty

3. Backward compatible (single-user)

   Omit principal everywhere. Behaviour is unchanged — the store is one shared pool.

   from praisonaiagents.scheduler import ScheduleJob, Schedule
   from praisonaiagents.scheduler.config_store import ConfigYamlScheduleStore
   
   store = ConfigYamlScheduleStore()
   
   store.add(ScheduleJob(
       name="daily-report",
       schedule=Schedule(kind="cron", cron_expr="0 9 * * *"),
       message="Send the daily report",
   ))
   
   store.list()   # → every job in one shared pool

How It Works

The gateway resolves the caller to a stable identity, then threads that string into every store call as principal. The store filters reads and refuses cross-owner mutations.

Auto-scoping from the session context

On a bot gateway (Telegram, Discord, Slack, or WhatsApp adapter) every turn installs a SessionContext carrying a unified_user_id. The agent tools and the gateway bridge read that value automatically, so isolation is on by default — you never thread identity by hand.

These surfaces now default principal from SessionContext.unified_user_id:

• schedule_add, schedule_list, schedule_remove — the agent-callable tools
• SuggestionEngine.propose / pending / accept / dismiss — the wrapper engine
• _automations.py inline-keyboard callbacks and create_from_blueprint

Configuration Options

Every method below gained an optional principal filter. principal=None is the default and preserves global / single-tenant behaviour.

Suggestion field

SuggestionStore methods

ScheduleJob field

FileScheduleStore / ConfigYamlScheduleStore methods

On FileScheduleStore, add, update, remove, and remove_by_name raise OSError on persistence failure (full disk, EIO, permission denied) and leave in-memory state matching disk. Callers that mutate the store should expect this exception — see Store write durability.

Agent-tool signatures

The agent-callable tools and the wrapper engine gained an optional principal. On a gateway it defaults from the session; passing it by hand only matters on the CLI / bridge path.

Semantics Reference

Choosing When to Scope

Common Patterns

On a bot gateway the tools read the session for you — no principal= needed. Once the gateway installs a SessionContext, an agent turn gets per-user isolation for free.

# Called from inside an agent turn on a bot gateway.
# No `principal=` needed — the tool reads SessionContext.unified_user_id.
from praisonaiagents.tools.schedule_tools import schedule_add, schedule_list

schedule_add("morning-brief", "daily", message="Send my morning brief")
schedule_list()   # → only this user's jobs

For advanced callers (custom stores, non-gateway wiring) thread the resolved identity down yourself; the core carries the string and enforces the filter but never resolves identity itself.

from praisonaiagents.scheduler import ScheduleJob, Schedule
from praisonaiagents.scheduler.config_store import ConfigYamlScheduleStore

store = ConfigYamlScheduleStore()

def create_for_caller(principal: str, name: str, cron: str, message: str) -> None:
    store.add(ScheduleJob(
        name=name,
        schedule=Schedule(kind="cron", cron_expr=cron),
        message=message,
        principal=principal,
    ))

def list_for_caller(principal: str):
    return store.list(principal=principal)

Backward Compatibility

Existing on-disk jobs.json, config.yaml, and suggestions.json files load unchanged. principal is omitted from to_dict() output when None, and every store method defaults principal to None — the pre-scoping global behaviour.

from praisonaiagents.scheduler import ScheduleJob, Schedule

job = ScheduleJob(
    name="daily-report",
    schedule=Schedule(kind="cron", cron_expr="0 9 * * *"),
    message="Send the daily report",
)

assert "principal" not in job.to_dict()   # key absent when None

Best Practices

Related