daycare-cli 0.0.1

package/dist/sandbox/sandboxHomeRedefine.d.ts

@@ -0,0 +1,15 @@
+type SandboxHomeRedefineInput = {
+    env: NodeJS.ProcessEnv;
+    home?: string;
+};
+type SandboxHomeRedefineResult = {
+    env: NodeJS.ProcessEnv;
+    homeDir?: string;
+};
+/**
+ * Redefines home-related environment variables inside the workspace.
+ * Expects: home is absolute and writable when provided.
+ */
+export declare function sandboxHomeRedefine(input: SandboxHomeRedefineInput): Promise<SandboxHomeRedefineResult>;
+export {};
+//# sourceMappingURL=sandboxHomeRedefine.d.ts.map

package/dist/sandbox/sandboxHomeRedefine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandboxHomeRedefine.d.ts","sourceRoot":"","sources":["../../sources/sandbox/sandboxHomeRedefine.ts"],"names":[],"mappings":"AAGA,KAAK,wBAAwB,GAAG;IAC9B,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,KAAK,yBAAyB,GAAG;IAC/B,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,wBAAwB,GAC9B,OAAO,CAAC,yBAAyB,CAAC,CAwDpC"}

package/dist/sandbox/sandboxHomeRedefine.js

@@ -0,0 +1,61 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+/**
+ * Redefines home-related environment variables inside the workspace.
+ * Expects: home is absolute and writable when provided.
+ */
+export async function sandboxHomeRedefine(input) {
+    if (!input.home) {
+        return { env: input.env };
+    }
+    const homeDir = path.resolve(input.home);
+    const xdgConfig = path.join(homeDir, ".config");
+    const xdgCache = path.join(homeDir, ".cache");
+    const xdgData = path.join(homeDir, ".local", "share");
+    const xdgState = path.join(homeDir, ".local", "state");
+    const tempDir = path.join(homeDir, ".tmp");
+    const dirsToEnsure = [
+        homeDir,
+        xdgConfig,
+        xdgCache,
+        xdgData,
+        xdgState,
+        tempDir,
+        path.join(homeDir, ".cargo"),
+        path.join(homeDir, ".rustup"),
+        path.join(homeDir, ".gem"),
+        path.join(homeDir, ".bundle"),
+        path.join(homeDir, ".pub-cache"),
+        path.join(homeDir, ".nuget", "packages"),
+        path.join(homeDir, ".composer"),
+        path.join(homeDir, ".config", "pip")
+    ];
+    await Promise.all(dirsToEnsure.map((target) => fs.mkdir(target, { recursive: true })));
+    return {
+        env: {
+            ...input.env,
+            HOME: homeDir,
+            USERPROFILE: homeDir,
+            XDG_CONFIG_HOME: xdgConfig,
+            XDG_CACHE_HOME: xdgCache,
+            XDG_DATA_HOME: xdgData,
+            XDG_STATE_HOME: xdgState,
+            TMPDIR: tempDir,
+            TMP: tempDir,
+            TEMP: tempDir,
+            CARGO_HOME: path.join(homeDir, ".cargo"),
+            RUSTUP_HOME: path.join(homeDir, ".rustup"),
+            DOTNET_CLI_HOME: homeDir,
+            NUGET_PACKAGES: path.join(homeDir, ".nuget", "packages"),
+            GEM_HOME: path.join(homeDir, ".gem"),
+            BUNDLE_USER_HOME: path.join(homeDir, ".bundle"),
+            PUB_CACHE: path.join(homeDir, ".pub-cache"),
+            COMPOSER_HOME: path.join(homeDir, ".composer"),
+            PIP_CONFIG_FILE: path.join(homeDir, ".config", "pip", "pip.conf"),
+            NPM_CONFIG_USERCONFIG: path.join(homeDir, ".npmrc"),
+            npm_config_userconfig: path.join(homeDir, ".npmrc")
+        },
+        homeDir
+    };
+}
+//# sourceMappingURL=sandboxHomeRedefine.js.map

package/dist/sandbox/sandboxHomeRedefine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandboxHomeRedefine.js","sourceRoot":"","sources":["../../sources/sandbox/sandboxHomeRedefine.ts"],"names":[],"mappings":"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"}

package/dist/sandbox/sandboxHomeRedefine.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=sandboxHomeRedefine.spec.d.ts.map

package/dist/sandbox/sandboxHomeRedefine.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandboxHomeRedefine.spec.d.ts","sourceRoot":"","sources":["../../sources/sandbox/sandboxHomeRedefine.spec.ts"],"names":[],"mappings":""}

package/dist/sandbox/sandboxHomeRedefine.spec.js

@@ -0,0 +1,41 @@
+import { describe, expect, it } from "vitest";
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { sandboxHomeRedefine } from "./sandboxHomeRedefine.js";
+describe("sandboxHomeRedefine", () => {
+    it("keeps environment unchanged when disabled", async () => {
+        const baseEnv = { HOME: "/home/original", FOO: "bar" };
+        const result = await sandboxHomeRedefine({
+            env: baseEnv,
+            home: undefined
+        });
+        expect(result.env).toBe(baseEnv);
+        expect(result.homeDir).toBeUndefined();
+    });
+    it("overrides home-related env vars and ensures directories", async () => {
+        const workspace = await fs.mkdtemp(path.join(os.tmpdir(), "daycare-home-"));
+        try {
+            const homeDir = path.join(workspace, ".sandbox-home");
+            const result = await sandboxHomeRedefine({
+                env: { HOME: "/home/original" },
+                home: homeDir
+            });
+            const expectedHome = homeDir;
+            expect(result.homeDir).toBe(expectedHome);
+            expect(result.env.HOME).toBe(expectedHome);
+            expect(result.env.USERPROFILE).toBe(expectedHome);
+            expect(result.env.XDG_CONFIG_HOME).toBe(path.join(expectedHome, ".config"));
+            expect(result.env.DOTNET_CLI_HOME).toBe(expectedHome);
+            expect(result.env.COMPOSER_HOME).toBe(path.join(expectedHome, ".composer"));
+            await expect(fs.stat(expectedHome)).resolves.toBeTruthy();
+            await expect(fs.stat(path.join(expectedHome, ".cargo"))).resolves.toBeTruthy();
+            await expect(fs.stat(path.join(expectedHome, ".nuget", "packages"))).resolves.toBeTruthy();
+            await expect(fs.stat(path.join(expectedHome, ".composer"))).resolves.toBeTruthy();
+        }
+        finally {
+            await fs.rm(workspace, { recursive: true, force: true });
+        }
+    });
+});
+//# sourceMappingURL=sandboxHomeRedefine.spec.js.map

package/dist/sandbox/sandboxHomeRedefine.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandboxHomeRedefine.spec.js","sourceRoot":"","sources":["../../sources/sandbox/sandboxHomeRedefine.spec.ts"],"names":[],"mappings":"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"}

package/dist/sandbox/sandboxPackageManagers.d.ts

@@ -0,0 +1,4 @@
+export declare const SANDBOX_PACKAGE_MANAGERS: readonly ["dart", "dotnet", "go", "java", "node", "php", "python", "ruby", "rust"];
+export type SandboxPackageManager = (typeof SANDBOX_PACKAGE_MANAGERS)[number];
+export declare const SANDBOX_PACKAGE_MANAGER_DOMAINS: Record<SandboxPackageManager, string[]>;
+//# sourceMappingURL=sandboxPackageManagers.d.ts.map

package/dist/sandbox/sandboxPackageManagers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandboxPackageManagers.d.ts","sourceRoot":"","sources":["../../sources/sandbox/sandboxPackageManagers.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,wBAAwB,oFAU3B,CAAC;AAEX,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9E,eAAO,MAAM,+BAA+B,EAAE,MAAM,CAAC,qBAAqB,EAAE,MAAM,EAAE,CA0BnF,CAAC"}

package/dist/sandbox/sandboxPackageManagers.js

@@ -0,0 +1,39 @@
+export const SANDBOX_PACKAGE_MANAGERS = [
+    "dart",
+    "dotnet",
+    "go",
+    "java",
+    "node",
+    "php",
+    "python",
+    "ruby",
+    "rust"
+];
+export const SANDBOX_PACKAGE_MANAGER_DOMAINS = {
+    dart: ["pub.dev", "storage.googleapis.com"],
+    dotnet: ["nuget.org", "api.nuget.org", "globalcdn.nuget.org"],
+    go: [
+        "proxy.golang.org",
+        "sum.golang.org",
+        "index.golang.org",
+        "golang.org"
+    ],
+    java: [
+        "repo.maven.apache.org",
+        "repo1.maven.org",
+        "plugins.gradle.org",
+        "services.gradle.org"
+    ],
+    // Node preset intentionally covers npm, pnpm, yarn, and bun workflows.
+    node: [
+        "registry.npmjs.org",
+        "registry.yarnpkg.com",
+        "repo.yarnpkg.com",
+        "bun.sh"
+    ],
+    php: ["packagist.org", "repo.packagist.org"],
+    python: ["pypi.org", "files.pythonhosted.org", "pypi.python.org"],
+    ruby: ["rubygems.org"],
+    rust: ["crates.io", "index.crates.io", "static.crates.io"]
+};
+//# sourceMappingURL=sandboxPackageManagers.js.map

package/dist/sandbox/sandboxPackageManagers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandboxPackageManagers.js","sourceRoot":"","sources":["../../sources/sandbox/sandboxPackageManagers.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACtC,MAAM;IACN,QAAQ;IACR,IAAI;IACJ,MAAM;IACN,MAAM;IACN,KAAK;IACL,QAAQ;IACR,MAAM;IACN,MAAM;CACE,CAAC;AAIX,MAAM,CAAC,MAAM,+BAA+B,GAA4C;IACtF,IAAI,EAAE,CAAC,SAAS,EAAE,wBAAwB,CAAC;IAC3C,MAAM,EAAE,CAAC,WAAW,EAAE,eAAe,EAAE,qBAAqB,CAAC;IAC7D,EAAE,EAAE;QACF,kBAAkB;QAClB,gBAAgB;QAChB,kBAAkB;QAClB,YAAY;KACb;IACD,IAAI,EAAE;QACJ,uBAAuB;QACvB,iBAAiB;QACjB,oBAAoB;QACpB,qBAAqB;KACtB;IACD,uEAAuE;IACvE,IAAI,EAAE;QACJ,oBAAoB;QACpB,sBAAsB;QACtB,kBAAkB;QAClB,QAAQ;KACT;IACD,GAAG,EAAE,CAAC,eAAe,EAAE,oBAAoB,CAAC;IAC5C,MAAM,EAAE,CAAC,UAAU,EAAE,wBAAwB,EAAE,iBAAiB,CAAC;IACjE,IAAI,EAAE,CAAC,cAAc,CAAC;IACtB,IAAI,EAAE,CAAC,WAAW,EAAE,iBAAiB,EAAE,kBAAkB,CAAC;CAC3D,CAAC"}

package/dist/settings.d.ts

@@ -0,0 +1,75 @@
+import type { CronTaskDefinition as CronTaskConfig } from "./engine/cron/cronTypes.js";
+export type PluginInstanceSettings = {
+    instanceId: string;
+    pluginId: string;
+    enabled?: boolean;
+    settings?: Record<string, unknown>;
+};
+export type InferenceProviderSettings = {
+    id: string;
+    model?: string;
+    options?: Record<string, unknown>;
+};
+export type ProviderImageSettings = {
+    enabled?: boolean;
+    model?: string;
+    size?: string;
+    quality?: "standard" | "hd";
+    endpoint?: string;
+    apiKeyHeader?: string;
+    apiKeyPrefix?: string;
+};
+export type ProviderSettings = {
+    id: string;
+    enabled?: boolean;
+    model?: string;
+    options?: Record<string, unknown>;
+    image?: ProviderImageSettings;
+};
+export type AgentSettings = {
+    emergencyContextLimit?: number;
+};
+export type ResolvedSettingsConfig = Omit<SettingsConfig, "agents"> & {
+    agents: Required<AgentSettings>;
+};
+export type SettingsConfig = {
+    engine?: {
+        socketPath?: string;
+        dataDir?: string;
+    };
+    assistant?: AssistantSettings;
+    agents?: AgentSettings;
+    plugins?: PluginInstanceSettings[];
+    providers?: ProviderSettings[];
+    inference?: {
+        providers?: InferenceProviderSettings[];
+    };
+    cron?: {
+        tasks?: CronTaskConfig[];
+    };
+    memory?: {
+        enabled?: boolean;
+        maxEntries?: number;
+    };
+};
+export type AssistantSettings = {
+    workspaceDir?: string;
+    systemPrompt?: string;
+};
+export declare const DEFAULT_SETTINGS_PATH: string;
+export declare function readSettingsFile(filePath?: string): Promise<SettingsConfig>;
+export declare function writeSettingsFile(filePath: string, settings: SettingsConfig): Promise<void>;
+export declare function updateSettingsFile(filePath: string, updater: (settings: SettingsConfig) => SettingsConfig): Promise<SettingsConfig>;
+export declare function listPlugins(settings: SettingsConfig): PluginInstanceSettings[];
+export declare function listEnabledPlugins(settings: SettingsConfig): PluginInstanceSettings[];
+export declare function upsertPlugin(plugins: PluginInstanceSettings[] | undefined, entry: PluginInstanceSettings): PluginInstanceSettings[];
+export type NextPluginInstanceIdOptions = {
+    exclusive?: boolean;
+};
+export declare function nextPluginInstanceId(pluginId: string, plugins: PluginInstanceSettings[] | undefined, options?: NextPluginInstanceIdOptions): string;
+export declare function removePlugin(plugins: PluginInstanceSettings[] | undefined, instanceId: string): PluginInstanceSettings[];
+export declare function listProviders(settings: SettingsConfig): ProviderSettings[];
+export declare function listActiveProviders(settings: SettingsConfig): ProviderSettings[];
+export declare function upsertProviderSettings(providers: ProviderSettings[] | undefined, entry: ProviderSettings): ProviderSettings[];
+export declare function removeProviderSettings(providers: ProviderSettings[] | undefined, id: string): ProviderSettings[];
+//# sourceMappingURL=settings.d.ts.map

package/dist/settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../sources/settings.ts"],"names":[],"mappings":"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"}

package/dist/settings.js

@@ -0,0 +1,91 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { resolveDaycarePath } from "./paths.js";
+export const DEFAULT_SETTINGS_PATH = resolveDaycarePath("settings.json");
+export async function readSettingsFile(filePath = DEFAULT_SETTINGS_PATH) {
+    const resolvedPath = path.resolve(filePath);
+    try {
+        const raw = await fs.readFile(resolvedPath, "utf8");
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return {};
+        }
+        throw error;
+    }
+}
+export async function writeSettingsFile(filePath, settings) {
+    const resolvedPath = path.resolve(filePath);
+    const dir = path.dirname(resolvedPath);
+    if (dir && dir !== ".") {
+        await fs.mkdir(dir, { recursive: true });
+    }
+    await fs.writeFile(resolvedPath, `${JSON.stringify(settings, null, 2)}\n`, {
+        mode: 0o600
+    });
+}
+export async function updateSettingsFile(filePath, updater) {
+    const settings = await readSettingsFile(filePath);
+    const updated = updater(settings);
+    await writeSettingsFile(filePath, updated);
+    return updated;
+}
+export function listPlugins(settings) {
+    return normalizePlugins(settings.plugins ?? []);
+}
+export function listEnabledPlugins(settings) {
+    return listPlugins(settings).filter((plugin) => plugin.enabled !== false);
+}
+export function upsertPlugin(plugins, entry) {
+    const list = normalizePlugins(plugins ?? []);
+    const filtered = list.filter((item) => item.instanceId !== entry.instanceId);
+    return [...filtered, entry];
+}
+export function nextPluginInstanceId(pluginId, plugins, options) {
+    // Exclusive plugins can only be installed once - always use bare pluginId
+    if (options?.exclusive) {
+        return pluginId;
+    }
+    const list = normalizePlugins(plugins ?? []);
+    const used = new Set(list.map((plugin) => plugin.instanceId));
+    // First instance uses bare pluginId without suffix
+    if (!used.has(pluginId)) {
+        return pluginId;
+    }
+    // Subsequent instances use -2, -3, etc.
+    let index = 2;
+    while (used.has(`${pluginId}-${index}`)) {
+        index += 1;
+    }
+    return `${pluginId}-${index}`;
+}
+export function removePlugin(plugins, instanceId) {
+    return normalizePlugins(plugins ?? []).filter((item) => item.instanceId !== instanceId);
+}
+export function listProviders(settings) {
+    if (settings.providers && settings.providers.length > 0) {
+        return settings.providers.map((provider) => ({ ...provider }));
+    }
+    return (settings.inference?.providers ?? []).map((provider) => ({
+        id: provider.id,
+        enabled: true,
+        model: provider.model,
+        options: provider.options
+    }));
+}
+export function listActiveProviders(settings) {
+    return listProviders(settings).filter((provider) => provider.enabled !== false);
+}
+export function upsertProviderSettings(providers, entry) {
+    const list = providers ? [...providers] : [];
+    const filtered = list.filter((provider) => provider.id !== entry.id);
+    return [entry, ...filtered];
+}
+export function removeProviderSettings(providers, id) {
+    return (providers ?? []).filter((provider) => provider.id !== id);
+}
+function normalizePlugins(plugins) {
+    return plugins.map((plugin) => ({ ...plugin }));
+}
+//# sourceMappingURL=settings.js.map

package/dist/settings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.js","sourceRoot":"","sources":["../sources/settings.ts"],"names":[],"mappings":"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"}

package/dist/skills/permanent-agent-creator/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: permanent-agent-creator
+description: Guide for creating and updating permanent agents with stable names, dedicated system prompts, and optional workspace folders.
+license: Complete terms in LICENSE.txt
+---
+
+# Permanent Agent Creator
+
+This skill provides guidance for creating and updating permanent agents.
+
+## About Permanent Agents
+
+Permanent agents are background agents with stable identities. They are created once and reused across sessions, with a dedicated system prompt that can be updated over time.
+
+### What Permanent Agents Provide
+
+1. Stable identity - predictable agent ids you can reference later
+2. Dedicated system prompts - durable instructions for specialized roles
+3. Optional workspace folders - focused file scopes inside the main workspace
+4. Reusable collaboration - multiple agents can coordinate through a named helper
+
+## Core Principles
+
+### Keep Prompts Focused
+
+Permanent agents should be narrow and durable. Prefer a short system prompt that captures role, constraints, and communication style.
+Avoid task-specific instructions that should live in the user request instead.
+
+### Stable Names Matter
+
+Names are how humans recognize agents. Pick a short, descriptive name and avoid frequent renames.
+If a name needs to change, update it deliberately alongside the system prompt.
+
+### Scope Workspace When Needed
+
+Only assign a workspace subfolder when the agent needs a dedicated area (e.g., a specific project or dataset).
+Default to the main workspace when no isolation is required.
+
+## Workflow
+
+1. **Gather inputs**
+   - Agent name
+   - Short description
+   - System prompt
+   - Optional workspace subfolder
+
+2. **Create or update**
+   Use `create_permanent_agent` with the collected inputs. Reusing a name updates the existing agent.
+
+3. **Share the agent id**
+   Store the returned agent id and use `send_agent_message` to coordinate with it.
+
+## Example
+
+Create a release helper:
+
+```
+create_permanent_agent({
+  name: "Release Tracker",
+  description: "Tracks release readiness and reports risks.",
+  systemPrompt: "You track release status, summarize risks, and report progress to the main agent.",
+  workspaceDir: "release-notes"
+})
+```
+
+Then delegate work:
+
+```
+send_agent_message({
+  agentId: "<agent-id>",
+  text: "Summarize the latest release checklist status."
+})
+```

package/dist/skills/scheduling/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: scheduling
+description: Schedule recurring or time-based tasks. Use for alarms, reminders, periodic reviews, automated reports, or any task that should run at specific times or intervals.
+---
+
+# Scheduling
+
+Daycare supports two scheduling mechanisms: **cron** for precise timing and **heartbeats** for periodic check-ins.
+
+## When to Use Cron
+
+Use cron when:
+- Exact timing matters (e.g., "every day at 9am")
+- Tasks need their own isolated agent and memory
+- One-off scheduled tasks (with `deleteAfterRun`)
+- Tasks that produce artifacts in a dedicated workspace
+
+**Cron tools:** `cron_add`, `cron_read_task`, `cron_read_memory`, `cron_write_memory`, `cron_delete_task`
+
+### Cron Routing
+
+Cron tasks run in their own dedicated cron agent by default. If you want the cron
+notification to land in an existing agent (e.g. a user chat), include `agentId`
+in `cron_add` to route the prompt to that agent instead.
+
+## When to Use Heartbeats
+
+Use heartbeats when:
+- Approximate timing is acceptable (~30 minute intervals)
+- Tasks need ongoing context from the main agent
+- Prompts evolve over time and need periodic review
+- Lightweight status checks or reminders
+
+**Heartbeat tools:** `heartbeat_add`, `heartbeat_list`, `heartbeat_run`, `heartbeat_remove`
+
+## Optional Exec Gate
+
+Both cron and heartbeat tasks can define an optional `gate` command to decide
+whether to run the LLM. The command runs first; exit code `0` means "run" and
+non-zero means "skip." This keeps checks cheap (ex: HTTP health check before notifying).
+Trimmed gate output is appended to the prompt under `[Gate output]`.
+Gates run within the target agent permissions. If `gate.permissions` are not already
+allowed, a system message is posted and the task still runs (the gate is treated as
+successful).
+
+`gate` supports:
+- `command` (required)
+- `cwd`, `timeoutMs`, `env`
+- `permissions` (required tags; must already be allowed by the target agent)
+- `packageManagers` (`dart` | `dotnet` | `go` | `java` | `node` | `php` | `python` | `ruby` | `rust`; auto-adds language ecosystem hosts; requires `@network`)
+- `allowedDomains` (network allowlist; requires `@network`)
+
+## Examples
+
+**Cron with routing + gate (`TASK.md` frontmatter):**
+
+```yaml
+---
+name: API health
+schedule: "*/10 * * * *"
+agentId: cu3ql2p5q0000x5p3g7q1l8a9
+gate:
+  command: "curl -fsS https://api.example.com/healthz >/dev/null"
+  packageManagers:
+    - node
+  allowedDomains:
+    - api.example.com
+---
+If the API is down, notify me with a short summary.
+```
+
+## Selection Examples
+
+### Choose Cron
+
+| User Input | Why Cron |
+|------------|----------|
+| "Remind me every day at 9am to check my emails" | Specific time (9am daily) |
+| "Run a backup script every Sunday at midnight" | Exact schedule needed |
+| "Send me a weather report every morning at 7:30" | Precise daily timing |
+| "Every hour, check if the server is up" | Strict hourly repetition |
+| "At 5pm on weekdays, summarize my tasks" | Complex schedule (weekdays only) |
+| "Once tomorrow at noon, remind me about the meeting" | One-off scheduled task |
+| "Every 15 minutes, poll the API for updates" | Precise interval timing |
+| "On the 1st of each month, generate a report" | Calendar-based schedule |
+
+### Choose Heartbeats
+
+| User Input | Why Heartbeat |
+|------------|---------------|
+| "Periodically check on my project status" | Ongoing review, flexible timing |
+| "Keep an eye on my git branches" | Continuous monitoring, evolving context |
+| "Remind me about my todos from time to time" | Lightweight, approximate timing |
+| "Check in on code quality occasionally" | Periodic review that needs reasoning |
+| "Monitor my open PRs and update me" | Ongoing task that evolves |
+| "Review my notes and suggest improvements" | Needs main agent context |
+| "Periodically summarize what I've been working on" | Flexible interval, ongoing |
+| "Keep track of my daily progress" | Continuous, evolving check-in |
+
+### Ambiguous Cases
+
+| User Input | Resolution |
+|------------|------------|
+| "Remind me about X regularly" | Ask: need exact times? Cron. Flexible? Heartbeat. |
+| "Check something every day" | Ask: specific time? Cron. Anytime during day? Heartbeat. |
+| "Monitor Y" | Heartbeat (monitoring implies ongoing, evolving context) |
+| "Schedule Z" | Cron (scheduling implies specific timing) |
+
+## Workflow
+
+**For cron tasks:**
+1. Determine the schedule (cron expression: `minute hour day month weekday`)
+2. Use `cron_add` with name, schedule, and prompt (optional `agentId` + `gate`)
+3. Each task gets isolated agent, memory file, and workspace
+
+**For heartbeats:**
+1. Run `heartbeat_list` to see existing tasks
+2. Use `heartbeat_add` with title and prompt (optional `gate`)
+3. Use `heartbeat_run` to trigger immediately
+4. Use `heartbeat_remove` for cleanup
+
+## Key Differences
+
+| Feature | Cron | Heartbeats |
+|---------|------|------------|
+| Timing | Exact (cron expression) | ~30 minute intervals |
+| Agent | Isolated per task | Shared main agent |
+| Memory | Persistent `MEMORY.md` | Main agent context |
+| Workspace | Dedicated `files/` dir | None |
+| One-off | Yes (`deleteAfterRun`) | No |
+| Best for | Time-sensitive tasks | Ongoing reviews |