@amaster.ai/pi-task-scheduler

Scheduled task domain types, execution scheduler, and pi agent extension.

The package owns schedule parsing, task lifecycle state, process-local timers, runner callbacks, scheduler hooks, and LLM-callable tools for autonomous task management.

Storage

The package ships with a built-in file-based storage (default, zero external dependencies):

• JsonScheduledTaskStore — persists tasks to a JSON file with atomic writes
• FileSchedulerLock — PID-based file lock for single-owner execution

For database-backed storage (multi-tenant, Prisma), use @amaster.ai/pi-storage/scheduler which implements the same interfaces with DbScheduledTaskStore and RedisSchedulerLock.

Default (file storage)

import {
  PersistentTaskScheduler,
  JsonScheduledTaskStore,
  FileSchedulerLock,
} from "@amaster.ai/pi-task-scheduler";

const scheduler = new PersistentTaskScheduler({
  store: new JsonScheduledTaskStore("/var/lib/pi/tasks.json"),
  lock: new FileSchedulerLock("/var/lib/pi/tasks.lock"),
  runner: async (task, run) => {
    await runPrompt(task.prompt, { sessionId: run.sessionId });
  },
});

await scheduler.start();

Custom storage

Implement ScheduledTaskStore and SchedulerLock interfaces for any backend (database, Redis, etc.):

import { PersistentTaskScheduler } from "@amaster.ai/pi-task-scheduler";

const scheduler = new PersistentTaskScheduler({
  store: myCustomStore,   // implements ScheduledTaskStore
  lock: myCustomLock,     // implements SchedulerLock
  runner: async (task, run) => {
    await runPrompt(task.prompt, { sessionId: run.sessionId });
  },
});

await scheduler.start();

Integration Modes

The package provides two integration paths depending on who controls the scheduler lifecycle.

Mode 1: Extension auto-discovery (standalone / CLI)

When installed as an npm dependency with the pi.extensions field in package.json, the runtime auto-discovers and loads the extension. The extension creates its own PersistentTaskScheduler with file-based storage (JsonScheduledTaskStore + FileSchedulerLock) — fully self-contained, no external infrastructure needed.

pi.extensions → session_start → creates file-based scheduler → registers tools + commands

• Storage: <agentDir>/data/tasks.json (configurable via dataDir)
• Lifecycle: scheduler starts on session_start, stops on session_shutdown
• Commands: /pi-scheduler-status, /pi-scheduler-list, /pi-scheduler-run-now
• LLM Tools: scheduler_create, scheduler_list, scheduler_get, scheduler_update, scheduler_delete, scheduler_run_now

Configuration via settings key pi-scheduler:

{
  "pi-scheduler": {
    "dataDir": "/custom/path"
  }
}

Mode 2: Dependency import (host-controlled)

When the host process owns the scheduler instance (e.g. backed by a database), it bypasses the extension and registers tools directly using createSchedulerTools:

import { createSchedulerTools } from "@amaster.ai/pi-task-scheduler/tools";
import { PersistentTaskScheduler } from "@amaster.ai/pi-task-scheduler";

const scheduler = new PersistentTaskScheduler({
  store: myStore,
  lock: myLock,
  runner,
});
await scheduler.start();

// Returns ToolDefinition[] — register via your tool injection mechanism
const tools = createSchedulerTools(scheduler);

In this mode the auto-discovered extension should be filtered out to prevent double tool registration. The host manages scheduler start/stop independently.

host creates scheduler → createSchedulerTools(scheduler) → tools injected into runtime
                       → extension filtered from auto-discovery

Choosing a mode

	Extension (Mode 1)	Dependency (Mode 2)
Storage	File-based (JSON)	Host-controlled
Scheduler lifecycle	Extension manages	Host manages
Tool registration	Extension registers	Host registers
Multi-tenant	No	Yes
Use case	CLI / standalone agent	Server / custom host

Scheduling

Tasks support three schedule types:

• interval: duration strings such as 30s, 10m, 1h, or 1d
• once: ISO timestamps or relative values such as +5m
• cron: 5/6-field cron expressions and a small RRULE subset

The scheduler does not catch up missed runs after process downtime. When it starts, it registers future timers for enabled tasks.

Hooks

Hooks are best-effort observability callbacks. If a hook throws, the scheduler swallows the error and keeps task state authoritative.