@parall/agent-core 1.25.0 → 1.26.0

package/dist/skills/parall-schedules.d.ts

@@ -0,0 +1,2 @@
+export declare const PARALL_SCHEDULES_SKILL = "# Parall Schedules\n\nA **Schedule** is a platform time trigger. At fire time the platform delivers the schedule's `description` to a target \u2014 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.\n\nThree spec types \u2014 pick exactly one:\n\n- `cron` \u2014 5-field expression (min granularity: 1 minute)\n- `interval` \u2014 every N seconds (minimum 60)\n- `one_shot` \u2014 fire once at a specific time\n\n## Creating schedules\n\n```bash\n# Recurring cron (weekdays 10am New York)\nparall schedules create \\\n  --name \"Daily standup\" \\\n  --description \"Ask the team for their plan today; see prll://wik_xxx for the standup template\" \\\n  --target-ids prll://usr_xxx \\\n  --cron-expr \"0 10 * * 1-5\" \\\n  --timezone America/New_York \\\n  --attached-to-uri prll://cht_xxx\n\n# Every 30 minutes\nparall schedules create \\\n  --name \"CI watch\" \\\n  --description \"Check the deploy status and flag failures\" \\\n  --target-ids prll://usr_xxx \\\n  --interval-seconds 1800\n\n# One-shot at a future RFC3339 time\nparall schedules create \\\n  --name \"Followup\" \\\n  --description \"Remind the user about the PR review if still pending\" \\\n  --target-ids prll://usr_xxx \\\n  --run-at <FUTURE_RFC3339_TIME>\n```\n\n`--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 \u2014 when that resource is archived or deleted, the schedule auto-cancels (`cancel_reason=attached_gone`).\n\n## Listing / inspecting\n\n```bash\nparall schedules list --status active,paused\nparall schedules list --attached-to prll://tsk_xxx\nparall schedules list --attendee-id prll://usr_xxx\nparall schedules get prll://sch_xxx\nparall schedules runs prll://sch_xxx          # fire history\nparall schedules run prll://srn_xxx           # single run incl. fire-time snapshot\n```\n\n## Lifecycle\n\n```bash\nparall schedules update prll://sch_xxx --description \"New prompt\"\nparall schedules pause  prll://sch_xxx        # reversible\nparall schedules resume prll://sch_xxx        # does NOT catch up missed slots\nparall schedules cancel prll://sch_xxx        # terminal; row + runs preserved, prll://sch_ ref stays valid\nparall 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) \u2014 cancel it and leave the audit trail. Delete is for never-fired test/accidental schedules only.\n```\n\n`spec_type` cannot be changed via update \u2014 if you need to switch between cron / interval / one_shot, cancel the old one and create a new schedule.\n\n## Responding to schedule fires\n\nWhen you receive `[Event: schedule.fired]`, the platform has fired a schedule targeting you.\n\nThe runtime (agent-core) has already done the heavy lifting: it fetched the schedule run and inlined the fire-time `description` (a frozen snapshot \u2014 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 \u2014 the description is already in the prompt body.\n\nYour job is to interpret the description and act:\n\n1. Read the description and any `prll://` refs it contains\n2. Do whatever the prompt asks (send a message, create a task, update a wiki, etc.) \u2014 there is no canonical response format\n3. 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\n\nDo not treat schedule fires as \"tasks assigned to you\" \u2014 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.\n\n**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 \u2014 don't retry.\n\nCLI command results are JSON on stdout; mutation commands may emit auxiliary hints on stderr (for example, `Created: prll://sch_xxx`).\n";
+//# sourceMappingURL=parall-schedules.d.ts.map

package/dist/skills/parall-schedules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parall-schedules.d.ts","sourceRoot":"","sources":["../../src/skills/parall-schedules.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,sBAAsB,ugJA+ElC,CAAC"}

package/dist/skills/parall-schedules.js

@@ -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/dist/skills/parall-tasks.d.ts

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

package/dist/skills/parall-tasks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parall-tasks.d.ts","sourceRoot":"","sources":["../../src/skills/parall-tasks.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,kBAAkB,0wDAgE9B,CAAC"}

package/dist/skills/parall-tasks.js

@@ -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/dist/skills/parall-wiki.d.ts

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

package/dist/skills/parall-wiki.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parall-wiki.d.ts","sourceRoot":"","sources":["../../src/skills/parall-wiki.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,iBAAiB,gyHAkI7B,CAAC"}

package/dist/skills/parall-wiki.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parall/agent-core",
-  "version": "1.25.0",
+  "version": "1.26.0",
   "description": "Shared agent runtime orchestration helpers for Parall",
   "license": "MIT",
   "repository": {
@@ -26,7 +26,7 @@
     "src"
   ],
   "dependencies": {
-    "@parall/sdk": "1.25.0"
+    "@parall/sdk": "1.26.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/src/bridge-workspace.ts

@@ -29,7 +29,7 @@ All outbound interactions go through the \`parall\` CLI. Credentials are pre-inj
 - \`parall tasks update prll://tsk_xxx --status in_progress\` — task state
 - \`parall no-reply [--reason "..."]\` — explicitly declare this turn silent (audit signal; not required for silence, just clarifies intent)
 
-The bridge injects Parall context via environment variables. The static credentials \`PRLL_API_URL\`, \`PRLL_API_KEY\`, and \`PRLL_ORG_ID\` are always set. Per-dispatch context — \`PRLL_SESSION_ID\`, \`PRLL_CHAT_ID\`, \`PRLL_TRIGGER_MESSAGE_ID\`, \`PRLL_STEP_ID_FILE\` — is set in subprocess-per-dispatch runtimes (Claude Code); in long-running runtimes (Codex) those may be absent and the CLI will fall back to whatever defaults you supply on the command line.
+The bridge injects Parall context via environment variables. The static credentials \`PRLL_API_URL\`, \`PRLL_API_KEY\`, and \`PRLL_ORG_ID\` are always set. \`PRLL_CONTEXT_FILE\` points to a per-session JSON file that the gateway updates each dispatch with \`session_id\`, \`chat_id\`, \`trigger_message_id\`, \`no_reply\`, and \`step_id\` (updated per tool call). The CLI reads this file automatically — you do not need to pass \`--chat\` or \`--session\` explicitly when the context file is present.
 
 ## Attachments
 

package/src/dispatch-adapter.ts

@@ -19,6 +19,8 @@ export type DispatchContext = {
   chatId?: string;
   triggerMessageId?: string;
   noReply: boolean;
+  contextFilePath?: string;
+  /** @deprecated Use contextFilePath. Kept for runtimes that haven't migrated. */
   stepIdFilePath?: string;
   client: ParallClient;
   log?: GatewayLogger;

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;
@@ -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) {
@@ -780,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);

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;
+    },
+  };
+}