@parall/agent-core 1.44.0 → 1.46.0

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

@@ -1,2 +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### Reminders for someone else\n\nWhen someone asks you to remind them (or a third person), put that person in\n`--target-ids` \u2014 the fire is delivered to its targets, so a reminder\ntargeting only yourself never reaches them. The schedule record stays yours as\ncreator (there is no owner transfer); add yourself as an additional target\nonly if you also need to act at fire time.\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";
+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 (`status_reason=attached_gone`). A schedule whose agent targets all sit on a terminated machine is auto-paused by the platform (`status_reason=attendee_unreachable`) instead of firing into a void; resuming a recurring schedule while the machine is still terminated just pauses it again on the next slot (a one-shot resumed past its catch-up window instead follows the normal missed semantics and completes).\n\n### Reminders for someone else\n\nWhen someone asks you to remind them (or a third person), put that person in\n`--target-ids` \u2014 the fire is delivered to its targets, so a reminder\ntargeting only yourself never reaches them. The schedule record stays yours as\ncreator (there is no owner transfer); add yourself as an additional target\nonly if you also need to act at fire time.\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

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

package/dist/skills/parall-schedules.js

@@ -35,7 +35,7 @@ parall schedules create \\
   --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\`).
+\`--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 (\`status_reason=attached_gone\`). A schedule whose agent targets all sit on a terminated machine is auto-paused by the platform (\`status_reason=attendee_unreachable\`) instead of firing into a void; resuming a recurring schedule while the machine is still terminated just pauses it again on the next slot (a one-shot resumed past its catch-up window instead follows the normal missed semantics and completes).
 
 ### Reminders for someone else
 

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

@@ -1,2 +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## Finding What's on Someone's Plate (incl. subtasks)\n\nTo answer \"what do I still have to do\", \"what's <person> working on\", or any\n\"open work assigned to X\" question, use `tasks assigned`:\n\n```bash\n# Pending tasks (todo + in_progress) assigned to a member \u2014 INCLUDES subtasks.\nparall tasks assigned prll://usr_xxx   # a specific person (e.g. the human who asked)\nparall tasks assigned                  # yourself (defaults to the authenticated user)\n```\n\nThis is the authoritative \"open work for a person\" query. It returns every\npending task assigned to that member **including subtasks** \u2014 even when the\nsubtask's parent task belongs to someone else. Decomposed work usually lives in\nsubtasks, so do NOT answer this kind of question from `tasks list` alone:\nthat is org-wide, page-capped, and not scoped to a person, so a person's\nsubtasks are easily missed.\n\nResolve a person's `prll://usr_` id from the message context, the members\nlist, or ref search; your own id comes from `parall whoami`.\n\n## Task Commands\n\n```bash\n# List tasks (org-wide; filter by status, assignee, or parent)\nparall tasks list\nparall tasks list --status todo\nparall tasks list --status in_progress\nparall tasks list --assignee-id prll://usr_xxx   # first page only (default 20) \u2014 for a person's FULL backlog use 'tasks assigned' above\nparall tasks subtasks prll://tsk_xxx             # children of a single parent task\n\n# Create a task (add --parent-id to make it a SUBTASK of another task)\nparall tasks create --title \"Task title\" [--assignee-id prll://usr_xxx] [--parent-id prll://tsk_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\nSubtasks are just tasks with a parent: create one with `tasks create --parent-id`,\nre-parent with `tasks update --parent-id`, list a parent's children with\n`tasks subtasks`. `tasks list` without `--parent-id` already returns both\ntop-level tasks and subtasks; per-person open work is best fetched with\n`tasks assigned` (above).\n\n## Project Commands\n\n```bash\nparall projects list\n```\n\n## Watching Tasks\n\nWatchers receive dispatch events for a task's new comments. Acting on a task\nauto-subscribes you \u2014 creating it, being assigned, commenting, being\n@mentioned, or substantively editing it (description / assignee). Handle or\ndismiss those comment events deliberately.\n\n```bash\nparall tasks watch prll://tsk_xxx      # follow a task without acting on it\nparall tasks unwatch prll://tsk_xxx    # opt out of a task's comment events\nparall tasks watchers prll://tsk_xxx   # list who is watching\n```\n\nCreators and assignees are locked subscribers \u2014 `unwatch` returns 409 for\nthem until the role changes (e.g. reassignment); it works for every other\nwatcher.\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 in a comment. If a gate remains \u2014 review, merge, deploy,\n   requester acceptance \u2014 set `in_review` and name the gate; set `done`\n   only once the work has actually landed\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\nCLI success output is JSON; errors print a JSON line plus, on a `PERMISSION_DENIED`, an optional plain-text `Request approval:` line \u2014 read both.\n";
+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## Finding What's on Someone's Plate (incl. subtasks)\n\nTo answer \"what do I still have to do\", \"what's <person> working on\", or any\n\"open work assigned to X\" question, use `tasks assigned`:\n\n```bash\n# Pending tasks (todo + in_progress) assigned to a member \u2014 INCLUDES subtasks.\nparall tasks assigned prll://usr_xxx   # a specific person (e.g. the human who asked)\nparall tasks assigned                  # yourself (defaults to the authenticated user)\n```\n\nThis is the authoritative \"open work for a person\" query. It returns every\npending task assigned to that member **including subtasks** \u2014 even when the\nsubtask's parent task belongs to someone else. Decomposed work usually lives in\nsubtasks, so do NOT answer this kind of question from `tasks list` alone:\nthat is org-wide, page-capped, and not scoped to a person, so a person's\nsubtasks are easily missed.\n\nResolve a person's `prll://usr_` id from the message context, the members\nlist, or ref search; your own id comes from `parall whoami`.\n\n## Task Commands\n\n```bash\n# List tasks (org-wide; filter by status, assignee, or parent)\nparall tasks list\nparall tasks list --status todo\nparall tasks list --status in_progress\nparall tasks list --assignee-id prll://usr_xxx   # first page only (default 20) \u2014 for a person's FULL backlog use 'tasks assigned' above\nparall tasks subtasks prll://tsk_xxx             # children of a single parent task\n\n# Create a task (add --parent-id to make it a SUBTASK of another task)\nparall tasks create --title \"Task title\" [--assignee-id prll://usr_xxx] [--parent-id prll://tsk_xxx] [--project-id prll://prj_xxx] [--due-date 2026-08-01]\n\n# Update task status \u2014 add --placement end so the task lands at the end of\n# its NEW status column (a bare --status keeps the old column's sort_order)\nparall tasks update prll://tsk_xxx --status in_progress --placement end\nparall tasks update prll://tsk_xxx --status done --placement end\n\n# Due date \u2014 a plain YYYY-MM-DD date (no timestamps); \"none\" clears it\nparall tasks update prll://tsk_xxx --due-date 2026-08-01\nparall tasks update prll://tsk_xxx --due-date none\n\n# Move a task to the end of its status column\nparall tasks update prll://tsk_xxx --placement end\n\n# Add a comment\nparall tasks comments add prll://tsk_xxx --body \"Progress update...\"\n```\n\nOrdering: to append a task to the end of a status column, always use\n`--placement end` \u2014 the server resolves the position atomically. This\nincludes status changes: a bare `--status` keeps the task's old\n`sort_order`, which may collide inside the new column. Do NOT compute a\n`sort_order` value yourself from listed tasks (your view may be stale or\npartial). `--sort-order` is only for pinpoint insertion between two cards\nyou just listed, and it cannot be combined with `--placement`.\n\nSubtasks are just tasks with a parent: create one with `tasks create --parent-id`,\nre-parent with `tasks update --parent-id`, list a parent's children with\n`tasks subtasks`. `tasks list` without `--parent-id` already returns both\ntop-level tasks and subtasks; per-person open work is best fetched with\n`tasks assigned` (above).\n\n## Project Commands\n\n```bash\nparall projects list\n```\n\n## Watching Tasks\n\nWatchers receive dispatch events for a task's new comments. Acting on a task\nauto-subscribes you \u2014 creating it, being assigned, commenting, being\n@mentioned, or substantively editing it (description / assignee). Handle or\ndismiss those comment events deliberately.\n\n```bash\nparall tasks watch prll://tsk_xxx      # follow a task without acting on it\nparall tasks unwatch prll://tsk_xxx    # opt out of a task's comment events\nparall tasks watchers prll://tsk_xxx   # list who is watching\n```\n\nCreators and assignees are locked subscribers \u2014 `unwatch` returns 409 for\nthem until the role changes (e.g. reassignment); it works for every other\nwatcher.\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 --placement end`\n3. Do the work\n4. Report results in a comment. If a gate remains \u2014 review, merge, deploy,\n   requester acceptance \u2014 set `in_review` and name the gate; set `done`\n   only once the work has actually landed\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\nCLI success output is JSON; errors print a JSON line plus, on a `PERMISSION_DENIED`, an optional plain-text `Request approval:` line \u2014 read both.\n";
 //# sourceMappingURL=parall-tasks.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"parall-tasks.d.ts","sourceRoot":"","sources":["../../src/skills/parall-tasks.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,kBAAkB,2/HA+F9B,CAAC"}
+{"version":3,"file":"parall-tasks.d.ts","sourceRoot":"","sources":["../../src/skills/parall-tasks.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,kBAAkB,k+JA+G9B,CAAC"}

package/dist/skills/parall-tasks.js

@@ -34,16 +34,32 @@ parall tasks list --assignee-id prll://usr_xxx   # first page only (default 20)
 parall tasks subtasks prll://tsk_xxx             # children of a single parent task
 
 # Create a task (add --parent-id to make it a SUBTASK of another task)
-parall tasks create --title "Task title" [--assignee-id prll://usr_xxx] [--parent-id prll://tsk_xxx] [--project-id prll://prj_xxx]
+parall tasks create --title "Task title" [--assignee-id prll://usr_xxx] [--parent-id prll://tsk_xxx] [--project-id prll://prj_xxx] [--due-date 2026-08-01]
 
-# Update task status
-parall tasks update prll://tsk_xxx --status in_progress
-parall tasks update prll://tsk_xxx --status done
+# Update task status — add --placement end so the task lands at the end of
+# its NEW status column (a bare --status keeps the old column's sort_order)
+parall tasks update prll://tsk_xxx --status in_progress --placement end
+parall tasks update prll://tsk_xxx --status done --placement end
+
+# Due date — a plain YYYY-MM-DD date (no timestamps); "none" clears it
+parall tasks update prll://tsk_xxx --due-date 2026-08-01
+parall tasks update prll://tsk_xxx --due-date none
+
+# Move a task to the end of its status column
+parall tasks update prll://tsk_xxx --placement end
 
 # Add a comment
 parall tasks comments add prll://tsk_xxx --body "Progress update..."
 \`\`\`
 
+Ordering: to append a task to the end of a status column, always use
+\`--placement end\` — the server resolves the position atomically. This
+includes status changes: a bare \`--status\` keeps the task's old
+\`sort_order\`, which may collide inside the new column. Do NOT compute a
+\`sort_order\` value yourself from listed tasks (your view may be stale or
+partial). \`--sort-order\` is only for pinpoint insertion between two cards
+you just listed, and it cannot be combined with \`--placement\`.
+
 Subtasks are just tasks with a parent: create one with \`tasks create --parent-id\`,
 re-parent with \`tasks update --parent-id\`, list a parent's children with
 \`tasks subtasks\`. \`tasks list\` without \`--parent-id\` already returns both
@@ -78,7 +94,7 @@ watcher.
 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\`
+2. Update status: \`tasks update prll://tsk_xxx --status in_progress --placement end\`
 3. Do the work
 4. Report results in a comment. If a gate remains — review, merge, deploy,
    requester acceptance — set \`in_review\` and name the gate; set \`done\`

package/dist/step-persister.d.ts

@@ -0,0 +1,66 @@
+import type { AgentStep, CreateAgentStepRequest, ParallClient } from '@parall/sdk';
+import { type StepDrainOutcome } from './step-retry-queue.js';
+/**
+ * AgentStep write path: one place decides inline-write vs park-for-retry.
+ *
+ * Extracted from the gateway so step persistence is a nameable collaborator
+ * instead of more growth in gateway-base.ts. Behavior contract (see
+ * AGENTS.md § Step write resilience): every request carries an
+ * idempotency_key so retries are replay-safe; transient failures park in the
+ * per-session FIFO StepRetryQueue; while a session has parked writes, new
+ * writes queue behind them to preserve ledger order; session-stale errors
+ * propagate to the caller (the gateway's existing recovery contract).
+ */
+export type StepPersisterOpts = {
+    client: ParallClient;
+    orgId: string;
+    agentUserId: string;
+    log?: {
+        warn: (msg: string) => void;
+    };
+    /** Session is dead (SESSION_NOT_LIVE / INVALID_TRANSITION 409). */
+    isSessionStale: (err: unknown) => boolean;
+    /** Retry backoff override (tests). Default: StepRetryQueue's schedule. */
+    retryDelaysMs?: number[];
+};
+export declare function isRetryableStepError(err: unknown): boolean;
+export declare class StepPersister {
+    private readonly opts;
+    private readonly queue;
+    private readonly sealed;
+    private disposed;
+    constructor(opts: StepPersisterOpts);
+    /**
+     * Write one AgentStep, riding the retry queue on transient failure.
+     * Returns the created step, or null when the write was queued or dropped.
+     */
+    persist(sessionId: string, label: string, req: CreateAgentStepRequest): Promise<AgentStep | null>;
+    /**
+     * Close the producer end for a session (finalization began): subsequent
+     * persist() calls are refused with a warn. Parked/in-flight writes keep
+     * retrying — seal gates NEW writes only.
+     */
+    seal(sessionId: string): void;
+    /**
+     * Reclaim a seal once its finalization released the session (the seal set
+     * must not grow forever on a daemon churning fork sessions). After the
+     * session is closed server-side, any late write is rejected there (409).
+     */
+    unseal(sessionId: string): void;
+    /**
+     * Resolves when the session's step queue reaches quiescence — see
+     * StepRetryQueue.awaitSessionDrained. Non-destructive: parked writes keep
+     * retrying on their normal schedule while awaited.
+     */
+    drainSession(sessionId: string): Promise<StepDrainOutcome>;
+    /** DESTRUCTIVE: discards the session's parked writes (server-terminal only). */
+    dropSession(sessionId: string): void;
+    /** Every session is dead (server closed them all — new_session). */
+    dropAllSessions(): void;
+    /** Best-effort single pass over parked writes; returns items still parked. */
+    flush(deadlineMs: number): Promise<number>;
+    pendingTotal(): number;
+    dispose(): void;
+    private enqueue;
+}
+//# sourceMappingURL=step-persister.d.ts.map

package/dist/step-persister.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"step-persister.d.ts","sourceRoot":"","sources":["../src/step-persister.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,sBAAsB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEnF,OAAO,EAAE,KAAK,gBAAgB,EAAkB,MAAM,uBAAuB,CAAC;AAE9E;;;;;;;;;;GAUG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,MAAM,EAAE,YAAY,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE,CAAC;IACtC,mEAAmE;IACnE,cAAc,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC;IAC1C,0EAA0E;IAC1E,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B,CAAC;AAEF,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAI1D;AAED,qBAAa,aAAa;IAOZ,OAAO,CAAC,QAAQ,CAAC,IAAI;IANjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiB;IAGvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,QAAQ,CAAS;gBAEI,IAAI,EAAE,iBAAiB;IAcpD;;;OAGG;IACG,OAAO,CACX,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,sBAAsB,GAC1B,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IAuC5B;;;;OAIG;IACH,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAI7B;;;;OAIG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAI/B;;;;OAIG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAI1D,gFAAgF;IAChF,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAKpC,oEAAoE;IACpE,eAAe,IAAI,IAAI;IAKvB,8EAA8E;IAC9E,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI1C,YAAY,IAAI,MAAM;IAItB,OAAO,IAAI,IAAI;IAKf,OAAO,CAAC,OAAO;CAOhB"}

package/dist/step-persister.js

@@ -0,0 +1,116 @@
+import { ApiError } from '@parall/sdk';
+import { StepRetryQueue } from './step-retry-queue.js';
+export function isRetryableStepError(err) {
+    // ApiError status 0 = fetch-level failure (timeout / network); 5xx =
+    // server-side transient. 4xx are contract errors a retry cannot fix.
+    return err instanceof ApiError && (err.status === 0 || err.status >= 500);
+}
+export class StepPersister {
+    opts;
+    queue;
+    // Sessions whose producer end is closed (finalization in progress) — new
+    // writes are refused instead of racing the drain/close sequence.
+    sealed = new Set();
+    disposed = false;
+    constructor(opts) {
+        this.opts = opts;
+        this.queue = new StepRetryQueue({
+            log: opts.log,
+            isRetryable: isRetryableStepError,
+            isSessionStale: opts.isSessionStale,
+            retryDelaysMs: opts.retryDelaysMs,
+            // Inline step writes already drive full stale recovery; a background
+            // retry discovering it just drops the dead session's queue — the next
+            // dispatch hits the same 409 inline and heals.
+            onSessionStale: (sessionId, err) => opts.log?.warn(`queued step hit stale session ${sessionId}: ${String(err)}`),
+        });
+    }
+    /**
+     * Write one AgentStep, riding the retry queue on transient failure.
+     * Returns the created step, or null when the write was queued or dropped.
+     */
+    async persist(sessionId, label, req) {
+        if (this.disposed) {
+            // Absorbing, like the queue and the lifecycle coordinator: a dispatch
+            // still draining past the shutdown deadline must not race the exiting
+            // process with fresh inline writes — its WorkItem is un-acked, so the
+            // re-drive on the replacement pod rewrites these steps idempotently.
+            this.opts.log?.warn(`refusing ${label} step after dispose (shutting down)`);
+            return null;
+        }
+        if (this.sealed.has(sessionId)) {
+            this.opts.log?.warn(`refusing ${label} step for sealed session ${sessionId} (finalization in progress)`);
+            return null;
+        }
+        if (this.queue.hasPending(sessionId)) {
+            // Preserve per-session FIFO while degraded.
+            this.enqueue(sessionId, label, req);
+            return null;
+        }
+        try {
+            return await this.opts.client.createAgentStep(this.opts.orgId, this.opts.agentUserId, sessionId, req);
+        }
+        catch (err) {
+            if (this.opts.isSessionStale(err))
+                throw err;
+            if (isRetryableStepError(err)) {
+                this.opts.log?.warn(`failed to create ${label} step (queued for retry): ${String(err)}`);
+                this.enqueue(sessionId, label, req);
+            }
+            else {
+                this.opts.log?.warn(`failed to create ${label} step: ${String(err)}`);
+            }
+            return null;
+        }
+    }
+    /**
+     * Close the producer end for a session (finalization began): subsequent
+     * persist() calls are refused with a warn. Parked/in-flight writes keep
+     * retrying — seal gates NEW writes only.
+     */
+    seal(sessionId) {
+        this.sealed.add(sessionId);
+    }
+    /**
+     * Reclaim a seal once its finalization released the session (the seal set
+     * must not grow forever on a daemon churning fork sessions). After the
+     * session is closed server-side, any late write is rejected there (409).
+     */
+    unseal(sessionId) {
+        this.sealed.delete(sessionId);
+    }
+    /**
+     * Resolves when the session's step queue reaches quiescence — see
+     * StepRetryQueue.awaitSessionDrained. Non-destructive: parked writes keep
+     * retrying on their normal schedule while awaited.
+     */
+    drainSession(sessionId) {
+        return this.queue.awaitSessionDrained(sessionId);
+    }
+    /** DESTRUCTIVE: discards the session's parked writes (server-terminal only). */
+    dropSession(sessionId) {
+        this.sealed.delete(sessionId);
+        this.queue.dropSession(sessionId);
+    }
+    /** Every session is dead (server closed them all — new_session). */
+    dropAllSessions() {
+        this.sealed.clear();
+        this.queue.dropAllSessions();
+    }
+    /** Best-effort single pass over parked writes; returns items still parked. */
+    flush(deadlineMs) {
+        return this.queue.flush(deadlineMs);
+    }
+    pendingTotal() {
+        return this.queue.pendingTotal();
+    }
+    dispose() {
+        this.disposed = true;
+        this.queue.dispose();
+    }
+    enqueue(sessionId, label, req) {
+        this.queue.enqueue(sessionId, label, () => this.opts.client
+            .createAgentStep(this.opts.orgId, this.opts.agentUserId, sessionId, req)
+            .then(() => undefined));
+    }
+}

package/dist/step-retry-queue.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Per-session FIFO retry queue for AgentStep writes.
+ *
+ * Step creation runs serially inside the dispatch drain loop, so a blocking
+ * retry there would stall healthy runtime work behind a degraded api link
+ * (the 2026-07-10 window: model calls fine, every fresh parall HTTPS
+ * handshake timing out). Instead, a failed write is parked here and retried
+ * in the background with backoff; while a session has parked items, new
+ * writes for that session are appended behind them so ledger order is
+ * preserved. All step requests carry an `idempotency_key`, which makes
+ * retries safe even when the original attempt landed server-side but its
+ * response was lost.
+ *
+ * In-memory only — a process restart drops parked items (the ledger hole is
+ * then no worse than the pre-queue behavior). Items are dropped, loudly, when
+ * they exceed `maxAgeMs` or the per-session cap.
+ */
+export type StepRetryQueueOpts = {
+    log?: {
+        warn: (msg: string) => void;
+    };
+    /** Transient failures worth retrying (timeouts, network, 5xx). */
+    isRetryable: (err: unknown) => boolean;
+    /** Session is dead (SESSION_NOT_LIVE / INVALID_TRANSITION) — drop its queue. */
+    isSessionStale: (err: unknown) => boolean;
+    /** Invoked once when a retry discovers a stale session. */
+    onSessionStale?: (sessionId: string, err: unknown) => void;
+    /** Drop an item once it has been parked this long. Default 10 minutes. */
+    maxAgeMs?: number;
+    /** Per-session cap; enqueue beyond it drops the NEW item. Default 200. */
+    maxQueueLength?: number;
+    /** Backoff schedule override (tests). Default 5s→10s→20s→40s→60s. */
+    retryDelaysMs?: number[];
+};
+/**
+ * How a session's queue reached quiescence: `drained` — every parked item
+ * settled (written, or dropped loudly by age/cap/non-retryable policy);
+ * `dropped` — the queue was discarded because the server considers the
+ * session terminal (stale 409, `agent.new_session`); `disposed` — the queue
+ * was shut down mid-wait.
+ */
+export type StepDrainOutcome = 'drained' | 'dropped' | 'disposed';
+export declare class StepRetryQueue {
+    private readonly opts;
+    private readonly queues;
+    private readonly timers;
+    private readonly drains;
+    private readonly drainWaiters;
+    private readonly retryDelays;
+    private disposed;
+    constructor(opts: StepRetryQueueOpts);
+    hasPending(sessionId: string): boolean;
+    pendingCount(sessionId: string): number;
+    enqueue(sessionId: string, label: string, exec: () => Promise<void>): void;
+    dropSession(sessionId: string): void;
+    /**
+     * Resolves when this session's queue reaches quiescence: every parked item
+     * settled (`drained` — including items dropped loudly by the age/cap/
+     * non-retryable policy), the queue was discarded because the server
+     * considers the session terminal (`dropped`), or the queue was disposed
+     * (`disposed`). Retries keep riding the normal backoff schedule while a
+     * caller waits — this only OBSERVES the queue, it never accelerates or
+     * abandons it.
+     */
+    awaitSessionDrained(sessionId: string): Promise<StepDrainOutcome>;
+    pendingTotal(): number;
+    /**
+     * One best-effort pass over every parked item — no backoff waits. Used at
+     * graceful shutdown: parked items are process-local (their WorkItems
+     * already resolved, so restart catch-up will NOT re-drive them), and the
+     * common shutdown (idle-stop, deploy) happens on a healthy network where
+     * the writes just succeed. A session whose head still fails retryably is
+     * skipped (its remaining items would fail the same way). A drain already in
+     * flight when flush arrives is JOINED (drain() returns the shared promise),
+     * so flush waits for its settle within the deadline instead of misreading
+     * "no progress" and giving up early. `deadlineMs` is a HARD cap: a write
+     * still in flight at the deadline is abandoned to the background (it is
+     * idempotent; dispose() right after clears any re-arm) and flush returns.
+     * Returns the number of items still parked.
+     */
+    flush(deadlineMs: number): Promise<number>;
+    /** Every tracked session is dead (server closed them all — new_session). */
+    dropAllSessions(): void;
+    dispose(): void;
+    private schedule;
+    private drain;
+    private drainOnce;
+    private rearm;
+    private resolveDrainWaiters;
+}
+//# sourceMappingURL=step-retry-queue.d.ts.map

package/dist/step-retry-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"step-retry-queue.d.ts","sourceRoot":"","sources":["../src/step-retry-queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,GAAG,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE,CAAC;IACtC,kEAAkE;IAClE,WAAW,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC;IACvC,gFAAgF;IAChF,cAAc,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC;IAC1C,2DAA2D;IAC3D,cAAc,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;IAC3D,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B,CAAC;AASF;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,SAAS,GAAG,UAAU,CAAC;AAgBlE,qBAAa,cAAc;IAgBb,OAAO,CAAC,QAAQ,CAAC,IAAI;IAfjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmC;IAC1D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqC;IAQ5D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoC;IAE3D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAiE;IAC9F,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAW;IACvC,OAAO,CAAC,QAAQ,CAAS;gBAEI,IAAI,EAAE,kBAAkB;IAIrD,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAItC,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAIvC,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAe1E,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAYpC;;;;;;;;OAQG;IACH,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAYjE,YAAY,IAAI,MAAM;IAMtB;;;;;;;;;;;;;OAaG;IACG,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAuBhD,4EAA4E;IAC5E,eAAe,IAAI,IAAI;IAIvB,OAAO,IAAI,IAAI;IAUf,OAAO,CAAC,QAAQ;IAchB,OAAO,CAAC,KAAK;YAeC,SAAS;IA4CvB,OAAO,CAAC,KAAK;IAkBb,OAAO,CAAC,mBAAmB;CAM5B"}