@parall/agent-core 1.24.0 → 1.26.0

package/src/gateway-base.ts

@@ -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;
@@ -272,6 +274,16 @@ export class ParallAgentGateway {
         } catch (err) {
           this.opts.log?.error(`parall[${this.opts.accountId}]: task comment dispatch failed for ${data.source_id}: ${String(err)}`);
         }
+      } else if (data.event_type === "task_update") {
+        if (!data.task_id) return;
+        try {
+          const dispatched = await this.handleTaskDispatch(data.task_id, data.source_id ?? data.task_id, { allowCreator: true });
+          if (dispatched) {
+            this.opts.client.ackDispatchByID(this.opts.config.org_id, data.id).catch(() => {});
+          }
+        } catch (err) {
+          this.opts.log?.error(`parall[${this.opts.accountId}]: task update dispatch failed for ${data.task_id}: ${String(err)}`);
+        }
       } else if (data.event_type === "schedule.fire") {
         if (!data.source_id) return;
         try {
@@ -356,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,
@@ -391,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);
@@ -436,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;
@@ -457,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;
@@ -477,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 });
@@ -486,6 +524,7 @@ export class ParallAgentGateway {
     }
   }
 
+  /** @deprecated Use writeContextFile / updateContextFileStepId. */
   private clearStepIdFile(filePath: string) {
     try {
       fs.writeFileSync(filePath, "", "utf8");
@@ -526,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.
@@ -557,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) {
@@ -770,9 +822,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);
@@ -959,6 +1015,30 @@ export class ParallAgentGateway {
     return dispatched;
   }
 
+  private async handleTaskDispatch(
+    taskId: string,
+    ackSourceId?: string,
+    opts: { allowCreator?: boolean } = {},
+  ): Promise<boolean> {
+    let task: Awaited<ReturnType<typeof this.opts.client.getTask>> | null = null;
+    try {
+      task = await this.opts.client.getTask(this.opts.config.org_id, taskId);
+    } catch (err: unknown) {
+      const status = (err as { status?: number })?.status;
+      if (status === 404) return true;
+      throw err;
+    }
+    const isAssignee = task.assignee_id === this.opts.agentUserId;
+    const isCreatorUpdate = opts.allowCreator === true && task.creator_id === this.opts.agentUserId;
+    if (!isAssignee && !isCreatorUpdate) {
+      this.opts.log?.info(
+        `parall[${this.opts.accountId}]: skipping stale task dispatch ${ackSourceId ?? taskId} — assigned to ${task.assignee_id}, creator ${task.creator_id}`,
+      );
+      return true;
+    }
+    return this.handleTaskAssignment(task, ackSourceId);
+  }
+
   private async handleTaskComment(
     commentId: string,
     taskId: string,
@@ -1134,29 +1214,18 @@ export class ParallAgentGateway {
         try {
           let dispatched = false;
           if (item.event_type === "task_assign" && item.task_id) {
-            let task: Awaited<ReturnType<typeof this.opts.client.getTask>> | null = null;
-            let taskFetchFailed = false;
             try {
-              task = await this.opts.client.getTask(this.opts.config.org_id, item.task_id);
+              dispatched = await this.handleTaskDispatch(item.task_id, item.source_id ?? item.task_id);
             } catch (err: unknown) {
-              const status = (err as { status?: number })?.status;
-              if (status === 404) {
-                task = null;
-              } else {
-                taskFetchFailed = true;
-                this.opts.log?.warn(`parall[${this.opts.accountId}]: catch-up task fetch failed for ${item.task_id}, leaving pending: ${String(err)}`);
-              }
+              this.opts.log?.warn(`parall[${this.opts.accountId}]: catch-up task fetch failed for ${item.task_id}, leaving pending: ${String(err)}`);
+              continue;
             }
-            if (taskFetchFailed) continue;
-            if (task) {
-              if (task.assignee_id !== this.opts.agentUserId) {
-                this.opts.log?.info(`parall[${this.opts.accountId}]: skipping stale task dispatch ${item.id} — reassigned to ${task.assignee_id}`);
-                this.opts.client.ackDispatchByID(this.opts.config.org_id, item.id).catch(() => {});
-                continue;
-              }
-              dispatched = await this.handleTaskAssignment(task);
-            } else {
-              dispatched = true;
+          } else if (item.event_type === "task_update" && item.task_id) {
+            try {
+              dispatched = await this.handleTaskDispatch(item.task_id, item.source_id ?? item.task_id, { allowCreator: true });
+            } catch (err: unknown) {
+              this.opts.log?.warn(`parall[${this.opts.accountId}]: catch-up task fetch failed for ${item.task_id}, leaving pending: ${String(err)}`);
+              continue;
             }
           } else if (item.event_type === "task_comment" && item.source_id && item.task_id) {
             dispatched = await this.handleTaskComment(item.source_id, item.task_id, item.actor_id, item.delivery_reason);

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.
+`;