@hyperdrive.bot/paseo-server 0.3.40 → 0.3.41

package/dist/server/server/agent/providers/claude/tool-allowlist.js

@@ -0,0 +1,133 @@
+/**
+ * Per-run tool allowlist enforcement for the claude provider.
+ *
+ * WHY A HOOK AND NOT `--allowedTools`
+ * -----------------------------------
+ * `--allowedTools` (CLI) and `options.allowedTools` (SDK) are *permission allow
+ * rules*: they pre-approve a tool so it does not prompt. They do not restrict
+ * anything. Both of paseo's claude transports also run the child with
+ * `--dangerously-skip-permissions` / `allowDangerouslySkipPermissions`, under
+ * which every permission rule is moot, so passing an allowlist there would be
+ * decorative: accepted, parsed, and silently unenforcing.
+ *
+ * A `PreToolUse` hook is the one gate that still fires in that state. The Agent
+ * SDK says so explicitly (sdk.d.ts, PermissionDeniedHookInput): "PreToolUse hook
+ * denies bypass canUseTool". Verified against claude 2.1.239 with
+ * `--permission-mode acceptEdits --dangerously-skip-permissions`: a hook exiting
+ * 2 blocked a Bash call while an allowlisted Read call went through.
+ *
+ * FAIL CLOSED
+ * -----------
+ * When an allowlist is configured, anything this module cannot positively match
+ * is DENIED. A matcher that is too strict fails loudly (the model is told which
+ * rule set rejected it, and the run keeps going), while a matcher that is too
+ * lax fails silently and hands back a guarantee that is not real. Strictness is
+ * the safe direction, so unknown rule shapes and unknown specifier sources deny.
+ *
+ * Note this is *stricter* than `claude-pool launch --allowedTools`, where tools
+ * that never request permission (Read, Grep, TodoWrite, ...) were unaffected by
+ * the allowlist. Here the allowlist means exactly what it says: a tool absent
+ * from it cannot run at all.
+ */
+/** Tools whose specifier (the `Tool(spec)` argument) we know how to read off the input. */
+export const SPECIFIER_SOURCES = {
+    Bash: "command",
+    BashOutput: "bash_id",
+    Read: "file_path",
+    Edit: "file_path",
+    Write: "file_path",
+    NotebookEdit: "notebook_path",
+    WebFetch: "url",
+    Glob: "pattern",
+    Grep: "pattern",
+};
+/**
+ * Parse CSV-or-array allowlist entries into rules. Entries are the same strings
+ * Claude Code permission rules use: `Bash`, `Bash(git:*)`, `Read`,
+ * `mcp__server__tool`. Blank entries are dropped.
+ */
+export function parseToolAllowlist(entries) {
+    const rules = [];
+    for (const raw of entries) {
+        for (const piece of raw.split(",")) {
+            const entry = piece.trim();
+            if (!entry)
+                continue;
+            const match = /^([^()\s]+)\((.*)\)$/.exec(entry);
+            if (match?.[1] !== undefined && match[2] !== undefined) {
+                rules.push({ tool: match[1], specifier: match[2].trim() });
+            }
+            else {
+                rules.push({ tool: entry });
+            }
+        }
+    }
+    return rules;
+}
+/** Escape a literal for use inside a RegExp, leaving `*` to be expanded by the caller. */
+export function escapeLiteral(value) {
+    return value.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Match a Claude-Code-style specifier pattern against a value.
+ *
+ * Supported shapes (anything else denies):
+ *  - `*`          any value
+ *  - `prefix:*`   value starts with `prefix` (Claude Code's command-prefix form)
+ *  - `glob`       `*` wildcards, everything else literal, anchored both ends
+ */
+export function specifierMatches(pattern, value) {
+    if (pattern === "*")
+        return true;
+    const prefixForm = /^(.*):\*$/.exec(pattern);
+    if (prefixForm?.[1] !== undefined) {
+        const prefix = prefixForm[1].trim();
+        if (!prefix)
+            return false;
+        return value === prefix || value.startsWith(`${prefix} `);
+    }
+    const expanded = pattern.split("*").map(escapeLiteral).join(".*");
+    return new RegExp(`^${expanded}$`).test(value);
+}
+/** Read the specifier value a `Tool(spec)` rule compares against, or null when unknown. */
+export function readSpecifierValue(toolName, input) {
+    const key = SPECIFIER_SOURCES[toolName];
+    if (!key)
+        return null;
+    if (typeof input !== "object" || input === null)
+        return null;
+    const value = input[key];
+    return typeof value === "string" ? value : null;
+}
+/**
+ * True when `toolName` (with `input`) is permitted by `rules`.
+ *
+ * An EMPTY rule list means "no allowlist configured" and allows everything; the
+ * caller is responsible for not installing the guard at all in that case.
+ */
+export function isToolAllowed(toolName, input, rules) {
+    if (rules.length === 0)
+        return true;
+    for (const rule of rules) {
+        if (rule.tool !== toolName)
+            continue;
+        if (rule.specifier === undefined)
+            return true;
+        const value = readSpecifierValue(toolName, input);
+        // Unknown specifier source: we cannot verify the rule, so we do not honor it.
+        if (value === null)
+            continue;
+        if (specifierMatches(rule.specifier, value))
+            return true;
+    }
+    return false;
+}
+/** The message handed back to the model when a call is blocked. */
+export function formatDenialMessage(toolName, rules) {
+    const listed = rules
+        .map((rule) => (rule.specifier === undefined ? rule.tool : `${rule.tool}(${rule.specifier})`))
+        .join(", ");
+    return (`Tool "${toolName}" is blocked by this run's tool allowlist and was not executed. ` +
+        `Allowed: ${listed}. Do not retry this tool; achieve the goal with an allowed tool or report that you cannot.`);
+}
+//# sourceMappingURL=tool-allowlist.js.map

package/dist/server/server/agent/tools/paseo-tools.d.ts

@@ -8,6 +8,7 @@ import type { TerminalManager } from "../../../terminal/terminal-manager.js";
 import type { CreatePaseoWorktreeWorkflowFn } from "../../worktree-session.js";
 import type { JudgeRelayGate } from "../judge-relay-gate.js";
 import type { ScheduleService } from "../../schedule/service.js";
+import { type ScheduleCadence } from "@hyperdrive.bot/paseo-protocol/schedule/types";
 import type { ProviderSnapshotManager } from "../provider-snapshot-manager.js";
 import type { GitHubService } from "../../../services/github-service.js";
 import type { WorkspaceGitService } from "../../workspace-git-service.js";
@@ -62,5 +63,23 @@ export interface PaseoToolHostDependencies {
     judgeRelayGate?: JudgeRelayGate;
     logger: Logger;
 }
+export interface ScheduleCreateCadenceArgs {
+    at?: string;
+    every?: string;
+    cron?: string;
+    timezone?: string;
+}
+export interface ResolvedScheduleCreateCadence {
+    cadence: ScheduleCadence;
+    /**
+     * `at` is a one-off. It lowers to an `every` cadence whose interval is the
+     * distance to the instant, pinned to a single run. An `every` schedule stores
+     * the computed `nextRunAt`, so a daemon that was down at that moment fires it
+     * late on the next tick, which is what a reminder wants. A pinned cron would
+     * instead skip silently to the next calendar match a year away.
+     */
+    oneOff: boolean;
+}
+export declare function resolveScheduleCreateCadence(input: ScheduleCreateCadenceArgs, now: Date): ResolvedScheduleCreateCadence;
 export declare function createPaseoToolCatalog(options: PaseoToolHostDependencies): PaseoToolCatalog;
 //# sourceMappingURL=paseo-tools.d.ts.map

package/dist/server/server/agent/tools/paseo-tools.js

@@ -141,6 +141,51 @@ function resolveScheduleUpdateCadence(input) {
     }
     return undefined;
 }
+// A duration ("90m", "2h30m", "45" seconds) rather than a timestamp. Checked
+// first so `at` can accept both without Date parsing guessing at bare numbers.
+const SCHEDULE_DURATION_ONLY_PATTERN = /^(?:\d+|(?:\d+[smhd])+)$/;
+function resolveScheduleAtInstant(at, now) {
+    if (SCHEDULE_DURATION_ONLY_PATTERN.test(at)) {
+        return new Date(now.getTime() + parseDurationString(at));
+    }
+    const parsed = new Date(at);
+    if (Number.isNaN(parsed.getTime())) {
+        throw new Error(`Invalid at value: ${at}. Use an ISO 8601 instant (2026-08-21T21:30:00-03:00) or a duration from now (90m).`);
+    }
+    return parsed;
+}
+export function resolveScheduleCreateCadence(input, now) {
+    const at = normalizeScheduleCadenceArg(input.at);
+    const every = normalizeScheduleCadenceArg(input.every);
+    const cron = normalizeScheduleCadenceArg(input.cron);
+    const timeZone = normalizeScheduleTimeZoneArg(input.timezone);
+    const provided = [at, every, cron].filter((value) => value !== undefined);
+    if (provided.length !== 1) {
+        throw new Error("Specify exactly one of at, every, or cron");
+    }
+    if (timeZone !== undefined && cron === undefined) {
+        throw new Error("timezone can only be used with cron");
+    }
+    if (at !== undefined) {
+        const instant = resolveScheduleAtInstant(at, now);
+        const everyMs = instant.getTime() - now.getTime();
+        if (everyMs <= 0) {
+            throw new Error(`at must be in the future: ${instant.toISOString()} is not after ${now.toISOString()}`);
+        }
+        return { cadence: { type: "every", everyMs }, oneOff: true };
+    }
+    if (every !== undefined) {
+        return { cadence: { type: "every", everyMs: parseDurationString(every) }, oneOff: false };
+    }
+    return {
+        cadence: {
+            type: "cron",
+            expression: cron,
+            ...(timeZone !== undefined ? { timezone: timeZone } : {}),
+        },
+        oneOff: false,
+    };
+}
 function resolveScheduleUpdateExpiresAt(input) {
     if (input.expiresIn !== undefined && input.clearExpires) {
         throw new Error("Specify at most one of expiresIn or clearExpires");
@@ -277,18 +322,6 @@ export function createPaseoToolCatalog(options) {
             return tool.handler(await parseToolInput(tool, input), context);
         },
     });
-    const buildCronScheduleCadence = (input) => {
-        const expression = input.cron?.trim() ?? "";
-        if (!expression) {
-            throw new Error("cron is required");
-        }
-        const timezone = normalizeScheduleTimeZoneArg(input.timezone);
-        return {
-            type: "cron",
-            expression,
-            ...(timezone !== undefined ? { timezone } : {}),
-        };
-    };
     const buildScheduleExpiry = (expiresIn) => {
         return expiresIn === undefined
             ? undefined
@@ -427,6 +460,59 @@ export function createPaseoToolCatalog(options) {
             },
         };
     };
+    // A schedule bound to an agent that is gone can never fire: the startup sweep
+    // completes it on sight. Fail loudly at create time instead of handing back a
+    // schedule that reads active and is already dead.
+    const assertScheduleTargetAgentExists = async (agentId) => {
+        if (agentManager.getAgent(agentId)) {
+            return;
+        }
+        const record = await agentStorage.get(agentId);
+        if (!record || record.internal) {
+            throw new Error(`Agent ${agentId} not found`);
+        }
+        if (record.archivedAt) {
+            throw new Error(`Agent ${agentId} is archived and cannot be a schedule target`);
+        }
+    };
+    const resolveScheduleCreateTarget = async (params) => {
+        const target = params.target?.trim();
+        // Default stays new-agent so callers written against the narrower schema
+        // keep the behaviour they had before target existed.
+        if (!target || target === "new-agent") {
+            return resolveNewAgentScheduleTarget({
+                ...(params.provider !== undefined ? { provider: params.provider } : {}),
+                ...(params.cwd !== undefined ? { cwd: params.cwd } : {}),
+            });
+        }
+        if (params.provider !== undefined || params.cwd !== undefined) {
+            throw new Error("provider and cwd can only be used with target new-agent");
+        }
+        if (target === "self") {
+            if (!callerAgentId) {
+                throw new Error('target "self" requires an agent-scoped session');
+            }
+            resolveCallerAgent();
+            return { type: "agent", agentId: callerAgentId };
+        }
+        await assertScheduleTargetAgentExists(target);
+        return { type: "agent", agentId: target };
+    };
+    // Recurring creates go through createOrReplace so an agent re-registering the
+    // same standing schedule refreshes it instead of minting a twin. A one-off must
+    // NOT: createOrReplace carries the existing schedule's `runs` forward, and
+    // shouldCompleteSchedule counts them against the incoming maxRuns before tick
+    // looks at nextRunAt, so replacing a schedule that has already run with
+    // maxRuns 1 completes it on the next tick without ever firing. There is also
+    // nothing to make idempotent about a one-off: two calls mean two reminders.
+    // Covered by schedule/service.test.ts "replacing a schedule that has run with
+    // maxRuns 1 buries it without firing".
+    const persistNewSchedule = async (input, oneOff) => {
+        if (!scheduleService) {
+            throw new Error("Schedule service is not configured");
+        }
+        return oneOff ? scheduleService.create(input) : scheduleService.createOrReplace(input);
+    };
     const ProviderModelInputSchema = AgentProviderEnum.trim()
         .refine((value) => value.includes("/"), {
         message: "provider must be provider/model, for example codex/gpt-5.4",
@@ -1609,39 +1695,80 @@ export function createPaseoToolCatalog(options) {
     });
     registerTool("create_schedule", {
         title: "Create schedule",
-        description: "Create a recurring schedule that starts a new agent on a cron cadence.",
+        description: "Schedule a prompt for later: once at a specific time (at), on a repeating interval (every), or on a cron cadence (cron). The prompt can start a fresh agent, come back to you (target self), or go to another agent by id. Prefer this over an in-session loop whenever the work must survive this session ending, since schedules are owned by the daemon.",
         inputSchema: {
             prompt: z.string().trim().min(1, "prompt is required"),
-            cron: z.string().trim().min(1, "cron is required"),
+            at: z
+                .string()
+                .trim()
+                .min(1)
+                .optional()
+                .describe('One-off delivery time. An ISO 8601 instant ("2026-08-21T21:30:00-03:00") or a duration from now ("90m", "2h30m"). Runs exactly once. Mutually exclusive with every and cron.'),
+            every: z
+                .string()
+                .trim()
+                .min(1)
+                .optional()
+                .describe('Repeating interval, for example "5m", "1h", "2h30m", "1d". Mutually exclusive with at and cron.'),
+            cron: z
+                .string()
+                .trim()
+                .min(1)
+                .optional()
+                .describe('Repeating cron expression, for example "0 9 * * 1-5". Mutually exclusive with at and every.'),
             timezone: z
                 .string()
                 .trim()
                 .min(1)
                 .optional()
-                .describe("IANA time zone for the cron cadence. For example: America/New_York."),
-            name: z.string().optional(),
-            provider: AgentProviderEnum.optional().describe("Provider, or provider/model (for example: codex or codex/gpt-5.4)."),
-            cwd: z.string().optional(),
+                .describe("IANA time zone for the cron cadence. Requires cron. For example: America/New_York."),
+            name: z
+                .string()
+                .optional()
+                .describe("Reusing a name with the same target refreshes that schedule in place instead of creating a second one."),
+            target: z
+                .string()
+                .trim()
+                .min(1)
+                .optional()
+                .describe('Who receives the prompt: "new-agent" (default) starts a fresh agent each run, "self" delivers to you, or an agent id delivers to that agent.'),
+            provider: AgentProviderEnum.optional().describe("Provider, or provider/model (for example: codex or codex/gpt-5.4). Only valid with target new-agent."),
+            cwd: z.string().optional().describe("Working directory. Only valid with target new-agent."),
             maxRuns: z.number().int().positive().optional(),
             expiresIn: z.string().optional(),
+            runNow: z
+                .boolean()
+                .optional()
+                .describe("Also fire once immediately on create. Defaults to true for every, false for cron. Not allowed with at."),
         },
         outputSchema: ScheduleSummarySchema.shape,
-    }, async ({ prompt, cron, timezone, name, provider, cwd, maxRuns, expiresIn }) => {
+    }, async ({ prompt, at, every, cron, timezone, name, target, provider, cwd, maxRuns, expiresIn, runNow, }) => {
         if (!scheduleService) {
             throw new Error("Schedule service is not configured");
         }
+        const { cadence, oneOff } = resolveScheduleCreateCadence({ at, every, cron, timezone }, new Date());
+        if (oneOff && maxRuns !== undefined && maxRuns !== 1) {
+            throw new Error("maxRuns cannot be combined with at: an at schedule runs exactly once");
+        }
+        if (oneOff && runNow === true) {
+            throw new Error("runNow cannot be combined with at: an at schedule runs only at its time");
+        }
+        const resolvedTarget = await resolveScheduleCreateTarget({ target, provider, cwd });
         const expiresAt = buildScheduleExpiry(expiresIn);
-        const schedule = await scheduleService.createOrReplace({
+        const scheduleInput = {
             prompt: prompt.trim(),
-            cadence: buildCronScheduleCadence({
-                cron,
-                ...(timezone !== undefined ? { timezone } : {}),
-            }),
-            target: resolveNewAgentScheduleTarget({ provider, cwd }),
+            cadence,
+            target: resolvedTarget,
             ...(name?.trim() ? { name: name.trim() } : {}),
-            ...(maxRuns === undefined ? {} : { maxRuns }),
+            ...(oneOff
+                ? { maxRuns: 1, runOnCreate: false }
+                : {
+                    ...(maxRuns === undefined ? {} : { maxRuns }),
+                    ...(runNow === undefined ? {} : { runOnCreate: runNow }),
+                }),
             ...(expiresAt === undefined ? {} : { expiresAt }),
-        });
+        };
+        const schedule = await persistNewSchedule(scheduleInput, oneOff);
         return {
             content: [],
             structuredContent: ensureValidJson(toScheduleSummary(schedule)),
@@ -1649,22 +1776,43 @@ export function createPaseoToolCatalog(options) {
     });
     registerTool("create_heartbeat", {
         title: "Create heartbeat",
-        description: "Create a recurring heartbeat that sends you a prompt on a cron cadence.",
+        description: "Schedule a prompt back to yourself: once at a specific time (at), on a repeating interval (every), or on a cron cadence (cron). Equivalent to create_schedule with target self.",
         inputSchema: {
             prompt: z.string().trim().min(1, "prompt is required"),
-            cron: z.string().trim().min(1, "cron is required"),
+            at: z
+                .string()
+                .trim()
+                .min(1)
+                .optional()
+                .describe('One-off delivery time. An ISO 8601 instant ("2026-08-21T21:30:00-03:00") or a duration from now ("90m"). Runs exactly once. Mutually exclusive with every and cron.'),
+            every: z
+                .string()
+                .trim()
+                .min(1)
+                .optional()
+                .describe('Repeating interval, for example "5m", "1h", "2h30m". Mutually exclusive with at and cron.'),
+            cron: z
+                .string()
+                .trim()
+                .min(1)
+                .optional()
+                .describe('Repeating cron expression, for example "0 9 * * 1-5". Mutually exclusive with at and every.'),
             timezone: z
                 .string()
                 .trim()
                 .min(1)
                 .optional()
-                .describe("IANA time zone for the cron cadence. For example: America/New_York."),
+                .describe("IANA time zone for the cron cadence. Requires cron. For example: America/New_York."),
             name: z.string().optional(),
             maxRuns: z.number().int().positive().optional(),
             expiresIn: z.string().optional(),
+            runNow: z
+                .boolean()
+                .optional()
+                .describe("Also fire once immediately on create. Defaults to true for every, false for cron. Not allowed with at."),
         },
         outputSchema: ScheduleSummarySchema.shape,
-    }, async ({ prompt, cron, timezone, name, maxRuns, expiresIn }) => {
+    }, async ({ prompt, at, every, cron, timezone, name, maxRuns, expiresIn, runNow }) => {
         if (!scheduleService) {
             throw new Error("Schedule service is not configured");
         }
@@ -1672,23 +1820,50 @@ export function createPaseoToolCatalog(options) {
             throw new Error("create_heartbeat requires an agent-scoped session");
         }
         resolveCallerAgent();
+        const { cadence, oneOff } = resolveScheduleCreateCadence({ at, every, cron, timezone }, new Date());
+        if (oneOff && maxRuns !== undefined && maxRuns !== 1) {
+            throw new Error("maxRuns cannot be combined with at: an at schedule runs exactly once");
+        }
+        if (oneOff && runNow === true) {
+            throw new Error("runNow cannot be combined with at: an at schedule runs only at its time");
+        }
         const expiresAt = buildScheduleExpiry(expiresIn);
-        const schedule = await scheduleService.createOrReplace({
+        const scheduleInput = {
             prompt: prompt.trim(),
-            cadence: buildCronScheduleCadence({
-                cron,
-                ...(timezone !== undefined ? { timezone } : {}),
-            }),
+            cadence,
             target: { type: "agent", agentId: callerAgentId },
             ...(name?.trim() ? { name: name.trim() } : {}),
-            ...(maxRuns === undefined ? {} : { maxRuns }),
+            ...(oneOff
+                ? { maxRuns: 1, runOnCreate: false }
+                : {
+                    ...(maxRuns === undefined ? {} : { maxRuns }),
+                    ...(runNow === undefined ? {} : { runOnCreate: runNow }),
+                }),
             ...(expiresAt === undefined ? {} : { expiresAt }),
-        });
+        };
+        const schedule = await persistNewSchedule(scheduleInput, oneOff);
         return {
             content: [],
             structuredContent: ensureValidJson(toScheduleSummary(schedule)),
         };
     });
+    registerTool("run_schedule_once", {
+        title: "Run schedule once",
+        description: "Fire a schedule immediately, out of band. The cadence and the next scheduled run are left untouched, but the run is recorded and counts toward maxRuns.",
+        inputSchema: {
+            id: z.string(),
+        },
+        outputSchema: StoredScheduleSchema.shape,
+    }, async ({ id }) => {
+        if (!scheduleService) {
+            throw new Error("Schedule service is not configured");
+        }
+        const schedule = await scheduleService.runOnce(id);
+        return {
+            content: [],
+            structuredContent: ensureValidJson(schedule),
+        };
+    });
     registerTool("list_schedules", {
         title: "List schedules",
         description: "List all schedules managed by the daemon.",

package/dist/server/server/agent/tools/read-only-surface.d.ts

@@ -42,6 +42,7 @@
  * - `create_terminal`, `kill_terminal`, `send_terminal_keys`       arbitrary command execution.
  * - `create_schedule`, `update_schedule`, `delete_schedule`,
  *   `pause_schedule`, `resume_schedule`, `create_heartbeat`        persistent side effects.
+ * - `run_schedule_once`      fires a schedule now, which starts or prompts an agent.
  * - `rename_workspace`       mutates.
  * - `speak`                  an outward side effect, and voice is out of v1 scope.
  * - `wait_for_agent`         not mutating, but it BLOCKS. An event-woken judge

package/dist/server/server/agent/tools/read-only-surface.js

@@ -42,6 +42,7 @@
  * - `create_terminal`, `kill_terminal`, `send_terminal_keys`       arbitrary command execution.
  * - `create_schedule`, `update_schedule`, `delete_schedule`,
  *   `pause_schedule`, `resume_schedule`, `create_heartbeat`        persistent side effects.
+ * - `run_schedule_once`      fires a schedule now, which starts or prompts an agent.
  * - `rename_workspace`       mutates.
  * - `speak`                  an outward side effect, and voice is out of v1 scope.
  * - `wait_for_agent`         not mutating, but it BLOCKS. An event-woken judge

package/dist/server/server/persistence-hooks.js

@@ -41,6 +41,7 @@ export function buildConfigOverrides(record) {
         extra: record.config?.extra ?? undefined,
         systemPrompt: record.config?.systemPrompt ?? undefined,
         mcpServers: record.config?.mcpServers ?? undefined,
+        allowedTools: record.config?.allowedTools ?? undefined,
     });
 }
 export function buildSessionConfig(record, options) {
@@ -58,6 +59,7 @@ export function buildSessionConfig(record, options) {
         extra: overrides.extra,
         systemPrompt: overrides.systemPrompt,
         mcpServers: overrides.mcpServers,
+        allowedTools: overrides.allowedTools,
     });
 }
 export function isStoredAgentProviderAvailable(record, validProviders) {