@parall/agent-core 1.25.0 → 1.26.1

package/src/gateway-base.ts

@@ -17,7 +17,7 @@ import type {
   TaskAssignedData,
   TextContent,
 } from "@parall/sdk";
-import { buildEventBody, buildForkResultPrefix } from "./event-format.js";
+import { buildEventBody, buildForkResultPrefix, buildForkScopePrefix } from "./event-format.js";
 import type {
   CleanupForkOpts,
   DispatchAdapter,
@@ -98,6 +98,8 @@ export type ParallGatewayOptions = {
   // abort before forcing WS disconnect. Pod termination grace period should
   // be at least this + a few seconds for the remaining cleanup work.
   shutdownDeadlineMs?: number;
+  contextFilePathForSession?: (sessionKey: string) => string | undefined;
+  /** @deprecated Use contextFilePathForSession. Kept for runtimes that haven't migrated. */
   stepIdFilePathForSession?: (sessionKey: string) => string | undefined;
   onConfigUpdate?: (data: AgentConfigUpdateData) => Promise<void> | void;
   onSessionReady?: (state: { activeSessionId?: string; ws: ParallWs; runtimeKey: string }) => Promise<void> | void;
@@ -366,6 +368,7 @@ export class ParallAgentGateway {
       chatId: event.type === "message" ? event.targetId : undefined,
       triggerMessageId: event.messageId,
       noReply: event.noReply ?? false,
+      contextFilePath: this.opts.contextFilePathForSession?.(sessionKey),
       stepIdFilePath: this.opts.stepIdFilePathForSession?.(sessionKey),
       client: this.opts.client,
       log: this.opts.log,
@@ -401,7 +404,7 @@ export class ParallAgentGateway {
     }
   }
 
-  private async createRuntimeStep(event: ParallEvent, runtimeEvent: RuntimeEvent, stepIdFilePath?: string) {
+  private async createRuntimeStep(event: ParallEvent, runtimeEvent: RuntimeEvent, stepIdFilePath?: string, contextFilePath?: string) {
     if (!this.activeSessionId) return;
 
     const target = resolveStepTarget(event);
@@ -446,7 +449,9 @@ export class ParallAgentGateway {
             group_key: runtimeEvent.groupKey,
             runtime_key: runtimeEvent.callId,
           });
-          if (stepIdFilePath) {
+          if (contextFilePath) {
+            this.updateContextFileStepId(contextFilePath, step.id);
+          } else if (stepIdFilePath) {
             this.writeStepIdFile(stepIdFilePath, step.id);
           }
           break;
@@ -467,7 +472,9 @@ export class ParallAgentGateway {
             },
             group_key: runtimeEvent.groupKey,
           });
-          if (stepIdFilePath) {
+          if (contextFilePath) {
+            this.updateContextFileStepId(contextFilePath, null);
+          } else if (stepIdFilePath) {
             this.clearStepIdFile(stepIdFilePath);
           }
           break;
@@ -487,6 +494,27 @@ export class ParallAgentGateway {
     }
   }
 
+  private writeContextFile(filePath: string, ctx: Record<string, unknown>) {
+    try {
+      fs.mkdirSync(path.dirname(filePath), { recursive: true });
+      fs.writeFileSync(filePath, JSON.stringify(ctx), "utf8");
+    } catch (err) {
+      this.opts.log?.warn(`parall[${this.opts.accountId}]: failed to write context file ${filePath}: ${String(err)}`);
+    }
+  }
+
+  private updateContextFileStepId(filePath: string, stepId: string | null) {
+    try {
+      const raw = fs.readFileSync(filePath, "utf8");
+      const ctx = JSON.parse(raw);
+      ctx.step_id = stepId;
+      fs.writeFileSync(filePath, JSON.stringify(ctx), "utf8");
+    } catch (err) {
+      this.opts.log?.warn(`parall[${this.opts.accountId}]: failed to update context file step_id ${filePath}: ${String(err)}`);
+    }
+  }
+
+  /** @deprecated Use writeContextFile / updateContextFileStepId. */
   private writeStepIdFile(filePath: string, stepId: string) {
     try {
       fs.mkdirSync(path.dirname(filePath), { recursive: true });
@@ -496,6 +524,7 @@ export class ParallAgentGateway {
     }
   }
 
+  /** @deprecated Use writeContextFile / updateContextFileStepId. */
   private clearStepIdFile(filePath: string) {
     try {
       fs.writeFileSync(filePath, "", "utf8");
@@ -536,8 +565,19 @@ export class ParallAgentGateway {
     setDispatchNoReply(sessionKey, event.noReply ?? false);
 
     const dispatchContext = this.buildDispatchContext(event, sessionKey);
+    const contextFilePath = dispatchContext.contextFilePath;
     const stepIdFilePath = dispatchContext.stepIdFilePath;
 
+    if (contextFilePath) {
+      this.writeContextFile(contextFilePath, {
+        session_id: dispatchContext.sessionId ?? null,
+        chat_id: dispatchContext.chatId ?? null,
+        trigger_message_id: dispatchContext.triggerMessageId ?? null,
+        no_reply: dispatchContext.noReply,
+        step_id: null,
+      });
+    }
+
     // sync: no await between the shuttingDown check above and this increment
     // — JS event loop is single-threaded, so shutdown() cannot interleave
     // here and miss our in-flight count.
@@ -567,19 +607,21 @@ export class ParallAgentGateway {
         sessionKey,
         context: dispatchContext,
       })) {
-        await this.createRuntimeStep(event, runtimeEvent, stepIdFilePath);
+        await this.createRuntimeStep(event, runtimeEvent, stepIdFilePath, contextFilePath);
       }
     } catch (err) {
       await this.createRuntimeStep(event, {
         type: "error",
         message: `Dispatch failed: ${String(err)}`,
-      }, stepIdFilePath);
+      }, stepIdFilePath, contextFilePath);
       throw err;
     } finally {
       clearSessionMessageId(sessionKey);
       clearDispatchMessageId(sessionKey);
       clearDispatchNoReply(sessionKey);
-      if (stepIdFilePath) {
+      if (contextFilePath) {
+        this.updateContextFileStepId(contextFilePath, null);
+      } else if (stepIdFilePath) {
         this.clearStepIdFile(stepIdFilePath);
       }
       if (this.activeSessionId) {
@@ -616,7 +658,7 @@ export class ParallAgentGateway {
         const last = events[events.length - 1];
         const earlier = events.slice(0, -1);
         try {
-          const dispatched = await this.runDispatch(last, fork.fork.sessionKey, buildEventBody(last), earlier);
+          const dispatched = await this.runDispatch(last, fork.fork.sessionKey, buildForkScopePrefix(last) + buildEventBody(last), earlier);
           if (!dispatched) {
             // Shutdown short-circuit — resolve un-acked so the server requeues
             // for the replacement pod and stop draining further items.
@@ -708,6 +750,8 @@ export class ParallAgentGateway {
             body: "[Orchestrator: fork session(s) completed — review results above]",
           };
           this.dispatchState.mainCurrentTargetId = undefined;
+          this.dispatchState.mainPreDispatchBranchPoint =
+            this.opts.dispatchAdapter.getBranchPoint?.(this.opts.runtimeKey);
           const dispatched = await this.runDispatch(syntheticEvent, this.opts.runtimeKey, forkPrefix + buildEventBody(syntheticEvent));
           if (!dispatched) {
             // Shutdown: put the fork results back at the head so the synthetic
@@ -730,8 +774,8 @@ export class ParallAgentGateway {
         const pendingFork = this.dispatchState.pendingForkResults.splice(0);
         const forkPrefix = buildForkResultPrefix(pendingFork);
         this.dispatchState.mainCurrentTargetId = event.targetId;
-        // Earlier-event input steps are persisted inside runDispatch (behind
-        // its shutdown gate) so a shutdown short-circuit cannot leave orphans.
+        this.dispatchState.mainPreDispatchBranchPoint =
+          this.opts.dispatchAdapter.getBranchPoint?.(this.opts.runtimeKey);
         const dispatched = await this.runDispatch(event, this.opts.runtimeKey, forkPrefix + buildEventBody(event), earlier);
         if (!dispatched) {
           // Shutdown: skip the ack so the server redelivers these buffered
@@ -754,6 +798,7 @@ export class ParallAgentGateway {
       this.draining = false;
       this.dispatchState.mainDispatching = false;
       this.dispatchState.mainCurrentTargetId = undefined;
+      this.dispatchState.mainPreDispatchBranchPoint = undefined;
     }
   }
 
@@ -766,6 +811,11 @@ export class ParallAgentGateway {
         const forkPrefix = buildForkResultPrefix(pendingFork);
         this.dispatchState.mainDispatching = true;
         this.dispatchState.mainCurrentTargetId = event.targetId;
+        // Snapshot the on-disk branch point BEFORE runDispatch starts writing
+        // to the session file. Fork sessions created while main is in-flight
+        // use this to branch from the clean pre-dispatch state.
+        this.dispatchState.mainPreDispatchBranchPoint =
+          this.opts.dispatchAdapter.getBranchPoint?.(this.opts.runtimeKey);
         let dispatched = false;
         try {
           dispatched = await this.runDispatch(event, this.opts.runtimeKey, forkPrefix + buildEventBody(event));
@@ -780,9 +830,13 @@ export class ParallAgentGateway {
         return dispatched;
       }
 
-      case "buffer-main":
+      case "buffer-main": {
+        if (this.shuttingDown) {
+          return false;
+        }
         this.dispatchState.mainBuffer.push(event);
         return false;
+      }
 
       case "buffer-fork": {
         const activeFork = this.forkStates.get(event.targetId);
@@ -804,6 +858,7 @@ export class ParallAgentGateway {
         const fork = await this.opts.dispatchAdapter.forkSession({
           sessionKey: this.opts.runtimeKey,
           context: this.buildDispatchContext(event, this.opts.runtimeKey),
+          preDispatchBranchPoint: this.dispatchState.mainPreDispatchBranchPoint,
         });
 
         if (!fork) {

package/src/index.ts

@@ -6,3 +6,6 @@ export * from "./prompt-fragments.js";
 export * from "./bridge-workspace.js";
 export * from "./dispatch-adapter.js";
 export * from "./gateway-base.js";
+export * from "./platform-config.js";
+export { writeSkillFiles, buildSkillReferences, SKILLS } from "./skills/index.js";
+export type { SkillMeta } from "./skills/index.js";

package/src/platform-config.ts

@@ -0,0 +1,159 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ParallClient, PlatformConfigResponse } from "@parall/sdk";
+import type { GatewayLogger } from "./dispatch-adapter.js";
+
+export interface PlatformDefaults {
+  model: string | null;
+  thinkingEffort: string | null;
+}
+
+export interface PlatformConfigManager {
+  fetch(): Promise<PlatformDefaults>;
+  current(): PlatformDefaults;
+  rawConfig(): Record<string, unknown> | null;
+}
+
+export interface PlatformManagementProfile {
+  machine_id?: string | null;
+  model_management?: string | null;
+}
+
+export function isPlatformManagedProfile(profile: PlatformManagementProfile | null | undefined): boolean {
+  return profile?.machine_id != null || profile?.model_management === "platform";
+}
+
+interface PlatformModelDef {
+  id?: unknown;
+  runtime_names?: unknown;
+}
+
+interface CachedPlatformConfig {
+  version: string;
+  config: Record<string, unknown>;
+  fetchedAt: string;
+}
+
+const CACHE_FILENAME = "parall-platform-config.json";
+const SUPPORTED_SCHEMA_VERSION = 1;
+
+function cachePath(stateDir: string): string {
+  return path.join(stateDir, CACHE_FILENAME);
+}
+
+function loadCache(stateDir: string): CachedPlatformConfig | null {
+  try {
+    const raw = fs.readFileSync(cachePath(stateDir), "utf-8");
+    return JSON.parse(raw) as CachedPlatformConfig;
+  } catch {
+    return null;
+  }
+}
+
+function saveCache(stateDir: string, response: PlatformConfigResponse): void {
+  const cached: CachedPlatformConfig = {
+    version: response.version,
+    config: response.config,
+    fetchedAt: new Date().toISOString(),
+  };
+  const filePath = cachePath(stateDir);
+  const tmpPath = `${filePath}.tmp`;
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(tmpPath, JSON.stringify(cached, null, 2), "utf-8");
+  fs.renameSync(tmpPath, filePath);
+}
+
+function runtimeModelName(
+  canonicalModel: string,
+  runtimeType: string | undefined,
+  config: Record<string, unknown>,
+): string | null {
+  const runtime = runtimeType?.trim();
+  if (!runtime || runtime === "openclaw") return canonicalModel;
+
+  const models = (config.models ?? {}) as Record<string, unknown>;
+  const providers = (models.providers ?? {}) as Record<string, unknown>;
+  const parall = (providers.parall ?? {}) as Record<string, unknown>;
+  const catalog = Array.isArray(parall.models) ? (parall.models as PlatformModelDef[]) : [];
+  const match = catalog.find((model) => model.id === canonicalModel);
+  const runtimeNames = (match?.runtime_names ?? {}) as Record<string, unknown>;
+  const runtimeName = runtimeNames[runtime];
+  return typeof runtimeName === "string" && runtimeName ? runtimeName : null;
+}
+
+function extractDefaults(config: Record<string, unknown>, runtimeType?: string): PlatformDefaults {
+  const agents = (config.agents ?? {}) as Record<string, unknown>;
+  const defaults = (agents.defaults ?? {}) as Record<string, unknown>;
+
+  let model: string | null = null;
+  if (typeof defaults.model === "string" && defaults.model) {
+    const canonicalModel = defaults.model.replace(/^parall\//, "");
+    model = runtimeModelName(canonicalModel, runtimeType, config);
+  }
+
+  let thinkingEffort: string | null = null;
+  if (typeof defaults.thinking_effort === "string" && defaults.thinking_effort) {
+    thinkingEffort = defaults.thinking_effort;
+  }
+
+  return { model, thinkingEffort };
+}
+
+export function createPlatformConfigManager(opts: {
+  client: ParallClient;
+  stateDir: string;
+  runtimeType?: string;
+  log?: GatewayLogger;
+}): PlatformConfigManager {
+  const { client, stateDir, runtimeType, log } = opts;
+  let cachedVersion: string | undefined;
+  let currentDefaults: PlatformDefaults = { model: null, thinkingEffort: null };
+  let currentRawConfig: Record<string, unknown> | null = null;
+
+  const cached = loadCache(stateDir);
+  if (cached) {
+    cachedVersion = cached.version;
+    currentRawConfig = cached.config;
+    currentDefaults = extractDefaults(cached.config, runtimeType);
+  }
+
+  return {
+    async fetch(): Promise<PlatformDefaults> {
+      let fresh: PlatformConfigResponse | null = null;
+      try {
+        fresh = await client.getPlatformConfig(cachedVersion);
+      } catch (err) {
+        if (cached) {
+          log?.warn(`platform config fetch failed, using cached version ${cachedVersion}: ${String(err)}`);
+          return currentDefaults;
+        }
+        log?.warn(`platform config fetch failed and no cache available: ${String(err)}`);
+        return currentDefaults;
+      }
+
+      if (fresh === null) {
+        return currentDefaults;
+      }
+
+      if (fresh.schema_version !== undefined && fresh.schema_version > SUPPORTED_SCHEMA_VERSION) {
+        log?.warn(`platform config schema_version ${fresh.schema_version} > supported (${SUPPORTED_SCHEMA_VERSION}), keeping current`);
+        return currentDefaults;
+      }
+
+      log?.info(`platform config updated to version ${fresh.version}`);
+      saveCache(stateDir, fresh);
+      cachedVersion = fresh.version;
+      currentRawConfig = fresh.config;
+      currentDefaults = extractDefaults(fresh.config, runtimeType);
+      return currentDefaults;
+    },
+
+    current(): PlatformDefaults {
+      return currentDefaults;
+    },
+
+    rawConfig(): Record<string, unknown> | null {
+      return currentRawConfig;
+    },
+  };
+}

package/src/skills/index.ts

@@ -0,0 +1,52 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export { PARALL_PLATFORM_SKILL } from "./parall-platform.js";
+export { PARALL_TASKS_SKILL } from "./parall-tasks.js";
+export { PARALL_WIKI_SKILL } from "./parall-wiki.js";
+export { PARALL_SCHEDULES_SKILL } from "./parall-schedules.js";
+
+import { PARALL_PLATFORM_SKILL } from "./parall-platform.js";
+import { PARALL_TASKS_SKILL } from "./parall-tasks.js";
+import { PARALL_WIKI_SKILL } from "./parall-wiki.js";
+import { PARALL_SCHEDULES_SKILL } from "./parall-schedules.js";
+
+export type SkillMeta = { name: string; description: string; content: string };
+
+export const SKILLS: SkillMeta[] = [
+  {
+    name: "parall-platform",
+    description: "Parall platform queries and lightweight agent provisioning: list org members, agents, chats, read message history, check identity, or create another agent. Use when: user asks about org members, who's online, chat history, agent list, creating an agent, or identity/auth questions.",
+    content: PARALL_PLATFORM_SKILL,
+  },
+  {
+    name: "parall-tasks",
+    description: "Parall task operations: create, update, comment on, and query tasks and projects. Use when: user asks to create a task, update task status, add comments, list tasks, or manage projects.",
+    content: PARALL_TASKS_SKILL,
+  },
+  {
+    name: "parall-wiki",
+    description: "Parall wiki operations: read, search, edit, and propose changes to organization knowledge bases. Use when: user asks to read/write docs, edit wiki pages, search knowledge base, propose changes, or review changesets.",
+    content: PARALL_WIKI_SKILL,
+  },
+  {
+    name: "parall-schedules",
+    description: "Parall schedule operations: create / pause / resume / cancel recurring or one-shot time triggers; respond to schedule fire events. Use when: user asks to set up a recurring reminder, schedule a delayed prompt, run cron-like work, or when the agent receives an `[Event: schedule.fired]` dispatch.",
+    content: PARALL_SCHEDULES_SKILL,
+  },
+];
+
+/** Write plain skill markdown files to a target directory (CC/Codex). */
+export function writeSkillFiles(targetDir: string): void {
+  fs.mkdirSync(targetDir, { recursive: true });
+  for (const skill of SKILLS) {
+    fs.writeFileSync(path.join(targetDir, `${skill.name}.md`), skill.content, "utf8");
+  }
+}
+
+
+export function buildSkillReferences(workspaceDir: string): string {
+  const dir = path.join(workspaceDir, ".parall", "skills");
+  const lines = SKILLS.map((s) => `- ${s.description.split(":")[0]}: \`${dir}/${s.name}.md\``);
+  return `## Platform Skills (read on demand)\n\n${lines.join("\n")}\n`;
+}

package/src/skills/parall-platform.ts

@@ -0,0 +1,161 @@
+export const PARALL_PLATFORM_SKILL = `# Parall Platform
+
+Query organization data via the Parall CLI. Auth is pre-configured.
+
+## Identity
+
+\`\`\`bash
+parall whoami
+\`\`\`
+
+## Members & Agents
+
+\`\`\`bash
+parall members list          # All org members (humans + agents)
+parall agents list           # Agents only
+parall users get prll://usr_xxx     # Get user details by ID
+\`\`\`
+
+Create a hosted agent when the user asks for a Parall-managed runtime. Hosted
+provisioning is asynchronous: creation means the agent identity, API key, and
+machine record were accepted, not that the runtime is online yet. Use \`--wait\`
+to wait until the machine reaches \`running\`, and use \`--wait-online\` when the
+task requires the child agent to be connected before you report completion.
+For hosted agents, use \`--discard-api-key\`; the server injects the one-time key
+into the hosted runtime, so the parent agent must not print or persist it.
+
+Create a self-hosted agent only when the runtime will be connected outside
+Parall-managed compute. In that case, write the one-time \`api_key\` to
+\`--api-key-file\` so it is not captured in tool-result logs. Treat \`api_key\` as a
+secret: do not print, read aloud, post it in shared chats, or echo the file
+contents. Include the \`user.id\` in normal responses, and pass the key file only
+through an explicit secure runtime handoff when connection is required. Never
+use \`--show-api-key\` from an agent runtime. Agent callers cannot set provider
+overrides until the dedicated fine-grained permission flow lands.
+
+\`\`\`bash
+# Hosted runtime (Parall-managed compute)
+parall agents create \\
+  --name "Research Agent" \\
+  --runtime-type codex \\
+  --machine-type cloud \\
+  --machine-label standard \\
+  --discard-api-key \\
+  --wait \\
+  --wait-online
+
+# Self-hosted runtime
+parall agents create --name "Research Agent" --runtime-type codex --api-key-file /tmp/research-agent.api-key
+\`\`\`
+
+Inspect hosted provisioning directly when a create command returns before the
+runtime is online, or when you need logs for a failed machine. If \`agents create\`
+exits non-zero after creating a hosted agent, read the printed \`user.id\` and
+\`machine.id\`, then use these commands to decide whether to wait, inspect logs,
+or report the failed machine for retry.
+
+\`\`\`bash
+parall machines status prll://mch_xxx
+parall machines logs prll://mch_xxx --lines 100
+\`\`\`
+
+## Chats & Messages
+
+\`\`\`bash
+parall chats list            # List all chats
+parall messages list prll://cht_xxx # Read chat message history
+\`\`\`
+
+## Sending Messages
+
+Each \`[Event: message.new]\` includes \`[Chat: ... (prll://cht_xxx)]\` — use that chat URI to reply.
+
+\`\`\`bash
+# Reply to a chat (use the chat URI from the event)
+parall messages send prll://cht_xxx --text "Your reply"
+
+# Direct message by user URI or display name
+parall dm prll://usr_xxx --text "Hello"
+parall dm "Alice" --text "Hello"
+
+# Thread reply
+parall messages send prll://cht_xxx --text "Reply" --thread-root-id 01JWC...
+
+# FYI message (no response expected — the recipient sees \`[Hint: no_reply]\`)
+parall messages send prll://cht_xxx --text "FYI: done" --no-reply
+
+# Silence this turn entirely — no chat message produced. Use when you receive
+# \`[Hint: no_reply]\` or otherwise decide the turn needs no visible reply.
+# Run BEFORE any \`messages send\` / \`dm\`; those still deliver real messages.
+parall no-reply --reason "ack only, nothing to add"
+\`\`\`
+
+## Files & Attachments
+
+Attachments appear in events as \`[Attachment: prll://att_xxx | mime | size | name]\`.
+
+\`\`\`bash
+# Download an attachment
+parall files download att_xxx --output /tmp/file.png
+
+# Upload a file (returns attachment_id)
+parall files upload /tmp/report.pdf
+
+# Send a message with a file
+parall messages send prll://cht_xxx --file /tmp/output.png --text "Done"
+
+# Send an existing attachment to another chat
+parall messages send prll://cht_xxx --attachment att_xxx --text "See attached"
+
+# DM with a file
+parall dm "Alice" --file /tmp/report.pdf --text "Report attached"
+\`\`\`
+
+\`--file\` and \`--attachment\` are mutually exclusive. \`--text\` can be combined with either.
+
+## Approvals
+
+When a CLI command returns a \`PERMISSION_DENIED\` error, the output includes a \`Tip:\` line with an approval-request template — copy it and fill in the remaining placeholders (\`--chat\`, \`--title\`, \`--reason\`). The \`Tip:\` only appears for commonly approvable actions (archive, delete, restore); for other actions, use \`parall approvals actions\` to check if it's approvable.
+
+\`\`\`bash
+# Request approval (use action and resource_uri from the error)
+parall approvals request --action chat.archive --resource prll://cht_xxx --chat prll://cht_yyy --title "Archive old channel" --reason "No activity in 6 months"
+
+# Check a specific approval's status
+parall approvals get prll://apr_xxx
+
+# Wait for a decision (blocks until approved/rejected/timeout)
+parall approvals wait prll://apr_xxx --timeout 300
+
+# List all your pending approvals
+parall approvals list
+
+# List available approvable actions
+parall approvals actions
+
+# Cancel a pending request you made
+parall approvals cancel prll://apr_xxx
+\`\`\`
+
+Only request approval after receiving an actual \`PERMISSION_DENIED\` error — never preemptively. The \`--chat\` flag specifies where the approval card appears; use the chat where the conversation is happening.
+
+## Reference URIs
+
+Every entity is addressable with a \`prll://\` URI. Common prefixes you'll see in events, messages, and schedule descriptions:
+
+| Prefix | Entity | Skill |
+|--------|--------|-------|
+| \`prll://usr_\` | User (human or agent) | parall-platform |
+| \`prll://cht_\` | Chat | parall-platform |
+| \`prll://msg_\` | Message | parall-platform |
+| \`prll://tsk_\` | Task | parall-tasks |
+| \`prll://prj_\` | Project | parall-tasks |
+| \`prll://sch_\` | Schedule (time trigger) | parall-schedules |
+| \`prll://srn_\` | Schedule run (single fire audit record; carries fire-time snapshot) | parall-schedules |
+| \`prll://wik_\` | Wiki | parall-wiki |
+| \`prll://att_\` | Attachment | parall-platform (files) |
+
+When a message or event references \`prll://sch_xxx\` or \`prll://srn_xxx\`, or when you receive \`[Event: schedule.fired]\`, switch to the **parall-schedules** skill for the CLI commands (create / list / pause / resume / cancel / runs).
+
+All CLI output is JSON.
+`;

package/src/skills/parall-schedules.ts

@@ -0,0 +1,80 @@
+export const PARALL_SCHEDULES_SKILL = `# Parall Schedules
+
+A **Schedule** is a platform time trigger. At fire time the platform delivers the schedule's \`description\` to a target — that's it. How you respond is up to you: send a message, create a task, update a wiki page, or do nothing. Use schedules for recurring reminders ("standup every weekday 10am"), delayed prompts ("in 1 hour, check CI"), or fire-and-forget cron work.
+
+Three spec types — pick exactly one:
+
+- \`cron\` — 5-field expression (min granularity: 1 minute)
+- \`interval\` — every N seconds (minimum 60)
+- \`one_shot\` — fire once at a specific time
+
+## Creating schedules
+
+\`\`\`bash
+# Recurring cron (weekdays 10am New York)
+parall schedules create \\
+  --name "Daily standup" \\
+  --description "Ask the team for their plan today; see prll://wik_xxx for the standup template" \\
+  --target-ids prll://usr_xxx \\
+  --cron-expr "0 10 * * 1-5" \\
+  --timezone America/New_York \\
+  --attached-to-uri prll://cht_xxx
+
+# Every 30 minutes
+parall schedules create \\
+  --name "CI watch" \\
+  --description "Check the deploy status and flag failures" \\
+  --target-ids prll://usr_xxx \\
+  --interval-seconds 1800
+
+# One-shot at a future RFC3339 time
+parall schedules create \\
+  --name "Followup" \\
+  --description "Remind the user about the PR review if still pending" \\
+  --target-ids prll://usr_xxx \\
+  --run-at <FUTURE_RFC3339_TIME>
+\`\`\`
+
+\`--target-ids\` is who receives the fire (usually yourself when you're self-scheduling; another agent or human when delegating). \`--attached-to-uri\` optionally anchors the schedule to a task / chat / project / wiki page — when that resource is archived or deleted, the schedule auto-cancels (\`cancel_reason=attached_gone\`).
+
+## Listing / inspecting
+
+\`\`\`bash
+parall schedules list --status active,paused
+parall schedules list --attached-to prll://tsk_xxx
+parall schedules list --attendee-id prll://usr_xxx
+parall schedules get prll://sch_xxx
+parall schedules runs prll://sch_xxx          # fire history
+parall schedules run prll://srn_xxx           # single run incl. fire-time snapshot
+\`\`\`
+
+## Lifecycle
+
+\`\`\`bash
+parall schedules update prll://sch_xxx --description "New prompt"
+parall schedules pause  prll://sch_xxx        # reversible
+parall schedules resume prll://sch_xxx        # does NOT catch up missed slots
+parall schedules cancel prll://sch_xxx        # terminal; row + runs preserved, prll://sch_ ref stays valid
+parall schedules delete prll://sch_xxx        # hard-delete; requires status=cancelled AND run_count=0. Once a schedule has fired, it is permanently undeletable (409 SCHEDULE_HAS_RUNS) — cancel it and leave the audit trail. Delete is for never-fired test/accidental schedules only.
+\`\`\`
+
+\`spec_type\` cannot be changed via update — if you need to switch between cron / interval / one_shot, cancel the old one and create a new schedule.
+
+## Responding to schedule fires
+
+When you receive \`[Event: schedule.fired]\`, the platform has fired a schedule targeting you.
+
+The runtime (agent-core) has already done the heavy lifting: it fetched the schedule run and inlined the fire-time \`description\` (a frozen snapshot — later edits to the schedule don't change past fires) into your prompt, alongside \`[Schedule: prll://sch_xxx]\` and \`[Run: prll://srn_xxx]\` headers. You do **not** need to call \`schedules run prll://srn_xxx\` yourself — the description is already in the prompt body.
+
+Your job is to interpret the description and act:
+
+1. Read the description and any \`prll://\` refs it contains
+2. Do whatever the prompt asks (send a message, create a task, update a wiki, etc.) — there is no canonical response format
+3. Optional: if the fire is genuinely a no-op and you don't want to produce any artifact, use \`no-reply\` (from parall-platform skill) to stay silent for this turn
+
+Do not treat schedule fires as "tasks assigned to you" — there's no status to transition, no acknowledgment required. If the work warrants a task (multi-step, needs tracking), create one from within the response.
+
+**Fetching the run explicitly** (optional): \`schedules run prll://srn_xxx\` returns the same snapshot plus delivery records (reverse-lookable via \`source_id=srn_xxx\`) for audit. If you call it and get 404 (because the schedule was cancelled or its target/attachment changed after the fire), drop the request and continue — don't retry.
+
+CLI command results are JSON on stdout; mutation commands may emit auxiliary hints on stderr (for example, \`Created: prll://sch_xxx\`).
+`;