@parall/agent-core 1.25.0 → 1.26.0

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

package/src/skills/parall-tasks.ts

@@ -0,0 +1,65 @@
+export const PARALL_TASKS_SKILL = `# Parall Tasks
+
+Manage tasks and projects via the Parall CLI. Auth and runtime context are pre-configured.
+
+## Task Commands
+
+\`\`\`bash
+# List tasks (filterable by status)
+parall tasks list
+parall tasks list --status todo
+parall tasks list --status in_progress
+
+# Create a task
+parall tasks create --title "Task title" [--assignee-id prll://usr_xxx] [--project-id prll://prj_xxx]
+
+# Update task status
+parall tasks update prll://tsk_xxx --status in_progress
+parall tasks update prll://tsk_xxx --status done
+
+# Add a comment
+parall tasks comments add prll://tsk_xxx --body "Progress update..."
+\`\`\`
+
+## Project Commands
+
+\`\`\`bash
+parall projects list
+\`\`\`
+
+## Watching Tasks
+
+Subscribe to a task to receive notifications when others comment on it.
+
+\`\`\`bash
+# Watch a task (you'll receive dispatch events for new comments)
+parall tasks watch prll://tsk_xxx
+
+# Unwatch
+parall tasks unwatch prll://tsk_xxx
+
+# List who is watching
+parall tasks watchers prll://tsk_xxx
+\`\`\`
+
+Note: task creators are automatically watching their tasks.
+
+## Responding to Task Assignments
+
+When you receive \`[Event: task.assigned]\`:
+
+1. Acknowledge with a comment: \`tasks comments add prll://tsk_xxx --body "On it"\`
+2. Update status: \`tasks update prll://tsk_xxx --status in_progress\`
+3. Do the work
+4. Report results via comment and update status to \`done\`
+
+## Responding to Task Comments
+
+When you receive \`[Event: task.comment.created]\`, someone commented on a task you are watching. Read the comment body and respond if action is needed:
+
+1. Review the comment content and task context
+2. Reply via comment: \`tasks comments add prll://tsk_xxx --body "Response..."\`
+3. If the comment requests status changes, update accordingly
+
+All CLI output is JSON.
+`;

package/src/skills/parall-wiki.ts

@@ -0,0 +1,131 @@
+export const PARALL_WIKI_SKILL = `# Parall Wiki
+
+Manage organization wikis via the Parall CLI. Auth is pre-configured.
+
+## Browsing (no local state needed)
+
+\`\`\`bash
+parall wiki list                       # List all wikis
+parall wiki tree <slug>                 # List files and directories
+parall wiki tree <slug> --path docs/    # List a subdirectory
+\`\`\`
+
+## Editing
+
+Wiki editing works on a **local workspace** — a directory on disk where wiki
+files are synced. You sync from the server, edit files locally, then propose
+a changeset.
+
+### Step 1: Sync
+
+\`\`\`bash
+parall wiki sync <slug>
+\`\`\`
+
+This downloads wiki files to a local directory. The output includes the
+**absolute mount path** for each wiki (e.g. \`synced → /path/to/workspace/kb\`).
+
+### Step 2: Find the mount path
+
+The sync output JSON contains \`synced[].path\` — the absolute path where files
+live. You can also check it anytime with:
+
+\`\`\`bash
+parall wiki status <slug>
+\`\`\`
+
+The output includes \`Mount: /absolute/path/to/<slug>\`.
+
+Use this path with \`read\`, \`write\`, and \`edit\` tools. For example, if the mount
+is \`/data/.openclaw/workspace/kb\`, then \`README.md\` is at
+\`/data/.openclaw/workspace/kb/README.md\`.
+
+### Step 3: Edit files
+
+Use standard file tools (\`read\`, \`write\`, \`edit\`) on files under the mount path.
+
+### Step 4: Review changes
+
+\`\`\`bash
+parall wiki diff <slug>       # Shows unified diff of all local changes
+parall wiki status <slug>     # Shows which files changed with +/- line counts
+\`\`\`
+
+Always review before proposing.
+
+### Step 5: Propose changeset
+
+\`\`\`bash
+parall wiki changeset create <slug> --title "Description of changes"
+\`\`\`
+
+This uploads your local changes. Unprotected paths auto-merge immediately; the
+CLI prints \`auto_merged: true\` and refreshes the local manifest. Protected
+paths remain as a changeset for review; follow the returned \`next_action\`.
+
+## Changeset Management
+
+\`\`\`bash
+parall wiki changeset list <slug>               # List all changesets
+parall wiki changeset show <changesetId> <slug> # Show detail + feedback
+parall wiki changeset diff <changesetId> <slug> # Show changeset diff
+\`\`\`
+
+If a changeset is rejected, fix the files locally and re-propose:
+
+\`\`\`bash
+parall wiki changeset create <slug> --update <changesetId>
+\`\`\`
+
+The title is inherited from the original changeset — no need to repeat it.
+
+## Handling sync conflicts
+
+\`wiki sync\` runs a three-way merge. When both you and the server changed the
+same file, sync **does not overwrite your work**. It leaves your file intact
+and drops the upstream version under \`.parall-wiki/conflicts/\`:
+
+| Marker | Meaning |
+|--------|---------|
+| \`.parall-wiki/conflicts/<path>.remote\` | Server has different content (concurrent edit, new file collision, or server changed a file you deleted) |
+| \`.parall-wiki/conflicts/<path>.remote-deleted\` | Server deleted the file; you still have edits |
+
+stderr prints one line per conflict. Recovery:
+
+**Accept upstream** (drop your edit):
+\`\`\`bash
+cp .parall-wiki/conflicts/<path>.remote <path>
+parall wiki sync
+\`\`\`
+
+**Keep yours** (or hand-merge, then propose):
+\`\`\`bash
+# edit <path> to final content
+parall wiki diff <slug>
+parall wiki changeset create <slug> --title "Reconcile <path>"
+parall wiki sync   # fast-forwards after server merges
+\`\`\`
+
+**Accept server delete** (\`.remote-deleted\` only):
+\`\`\`bash
+rm <path>
+parall wiki sync
+\`\`\`
+
+Sync failures (\`download\`, \`shape-conflict\`) set exit code 1 and retry on
+next sync. Conflicts exit 0 — they need your decision, not a retry.
+
+## Discarding local changes
+
+\`\`\`bash
+parall wiki reset <slug>      # Restore all files to last synced state
+\`\`\`
+
+## History
+
+\`\`\`bash
+parall wiki log <slug>        # Recent wiki operations
+\`\`\`
+
+All CLI output is JSON. Run \`parall wiki --help\` for full options.
+`;