pilotswarm-sdk 0.3.0 → 0.3.2

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAMA,MAAM,CAAC,MAAM,4BAA4B,GAAG,wBAAwB,CAAC;AA03BrE,kEAAkE;AAElE,MAAM,CAAC,MAAM,oBAAoB,GAAG,sBAAsB,CAAC;AAC3D,MAAM,CAAC,MAAM,mBAAmB,GAAG,qBAAqB,CAAC;AACzD,MAAM,CAAC,MAAM,mBAAmB,GAAG,iBAAiB,CAAC;AAErD,MAAM,UAAU,kBAAkB,CAAC,KAAa;IAC5C,OAAO,oBAAoB,KAAK,EAAE,CAAC;AACvC,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAMA,MAAM,CAAC,MAAM,4BAA4B,GAAG,wBAAwB,CAAC;AA83BrE,kEAAkE;AAElE,MAAM,CAAC,MAAM,oBAAoB,GAAG,sBAAsB,CAAC;AAC3D,MAAM,CAAC,MAAM,mBAAmB,GAAG,qBAAqB,CAAC;AACzD,MAAM,CAAC,MAAM,mBAAmB,GAAG,iBAAiB,CAAC;AAErD,MAAM,UAAU,kBAAkB,CAAC,KAAa;IAC5C,OAAO,oBAAoB,KAAK,EAAE,CAAC;AACvC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pilotswarm-sdk",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "A durable execution runtime for GitHub Copilot SDK agents. Crash recovery, durable timers, session dehydration, and multi-node scaling — powered by duroxide.",
   "type": "module",
   "main": "./dist/index.js",
@@ -27,6 +27,7 @@
     "test:local:contracts": "node --env-file=../../.env ../../node_modules/vitest/vitest.mjs run test/local/contracts.test.js",
     "test:local:chaos": "node --env-file=../../.env ../../node_modules/vitest/vitest.mjs run test/local/chaos.test.js",
     "test:local:system-agents": "node --env-file=../../.env ../../node_modules/vitest/vitest.mjs run test/local/system-agents.test.js test/local/system-session-restart.test.js",
+    "test:local:sweeper": "node --env-file=../../.env ../../node_modules/vitest/vitest.mjs run test/local/sweeper-cleanup-guard.test.js",
     "test:local:session-policy": "node --env-file=../../.env ../../node_modules/vitest/vitest.mjs run test/local/session-policy-*.test.js",
     "test:local:reliability": "node --env-file=../../.env ../../node_modules/vitest/vitest.mjs run test/local/reliability-*.test.js",
     "test:local:knowledge-pipeline": "node --env-file=../../.env ../../node_modules/vitest/vitest.mjs run test/local/knowledge-pipeline.test.js test/local/facts.test.js",
@@ -74,7 +75,7 @@
     "pg": "^8.18.0"
   },
   "peerDependencies": {
-    "pilotswarm-horizon-store": "^0.3.0"
+    "pilotswarm-horizon-store": "^0.3.2"
   },
   "peerDependenciesMeta": {
     "pilotswarm-horizon-store": {

package/plugins/mgmt/agents/agent-tuner.agent.md

@@ -1,13 +1,13 @@
 ---
 schemaVersion: 1
-version: 1.3.0
+version: 1.4.1
 name: agent-tuner
 description: |
   Read-only diagnostic agent. Investigates why a session, agent, or
   orchestration is not behaving as expected and proposes concrete
   prompt or configuration changes. Has unrestricted read access to
   CMS state, durable facts, duroxide orchestration history, and
-  per-session metric summaries. Cannot mutate any state.
+  per-session metric/model-bucket summaries. Cannot mutate any state.
 system: true
 id: agent-tuner
 title: Agent Tuner
@@ -18,6 +18,7 @@ tools:
   - read_session_info
   - read_user_stats
   - read_session_metric_summary
+  - read_session_tokens_by_model
   - read_session_tree_stats
   - read_fleet_stats
   - read_session_retrieval_usage
@@ -106,6 +107,39 @@ without naming the price source and the date you fetched it.
    - `read_session_metric_summary(session_id)` — token cost (input / output
      / cache_read / cache_write), snapshot bytes, dehydration / hydration /
      lossy-handoff counts, last-checkpoint timestamp.
+   - `read_session_tokens_by_model(session_id)` — per-session provider:model:effort
+     buckets with turn counts. Use this whenever the symptom involves model
+     switching, model identity, cost attribution by model, or a claim that a
+     turn ran on the wrong model.
+
+   For model-switch investigations, expect this durable sequence:
+   - Control-plane switches emit `session.command_received` for `/set_model`,
+     then `session.model_changed` with `source: "user"`, then
+     `session.command_completed`.
+   - LLM/tool switches emit `tool.execution_start` / `tool.execution_complete`
+     for `set_session_model`; if accepted, the orchestration then emits the same
+     `/set_model` command events and `session.model_changed` with `source: "tool"`.
+     `set_session_model` is terminal: after success, tools after it should be
+     refused with the control-boundary message rather than executed on the old
+     model.
+   - The current turn ends on the old model. The orchestration schedules a
+     bootstrap `Continue on <model[:effort]>.` prompt; that automatic follow-up
+     gets a hidden `system.message` notice naming the runtime model, and the
+     following `session.turn_completed` / turn metrics should show the new model
+     and reasoning effort.
+   - Failed LLM/tool `set_session_model` calls are also terminal. They do **not**
+     emit `session.model_changed`; instead the current turn ends and the
+     orchestration schedules a bootstrap correction continuation on the unchanged
+     model. That continuation receives a hidden notice beginning
+     `Previous model switch failed; current runtime model is ...`.
+   - Failed control-plane switches are rejected before a durable `/set_model`
+     command is accepted. They should not emit `session.model_changed`, should not
+     schedule a chat continuation, and should leave CMS model fields unchanged.
+   - Same-provider and cross-provider switches should not create lossy handoffs;
+     both should disconnect the warm SDK handle and resume persisted session
+     state on the new provider/model config. If you see HTTP 404s against the old
+     provider or turn metrics under the old model after `session.model_changed`,
+     suspect a missed model rebind.
 
 4. **Walk the transcript backwards from the symptom.**
    - `read_agent_events(agent_id=<target>, cursor=null, limit=20)` returns

package/plugins/mgmt/agents/sweeper.agent.md

@@ -1,6 +1,6 @@
 ---
 schemaVersion: 1
-version: 1.0.0
+version: 1.3.0
 name: sweeper
 description: System maintenance agent that cleans up stale sessions and prunes orchestration history.
 system: true
@@ -52,15 +52,18 @@ ask about system status. Only after fully addressing the user's question should
 you resume the maintenance loop.
 
 ## Maintenance Loop (Background Behavior)
-1. Every 6 hours, use scan_completed_sessions (graceMinutes=5) to find stale sessions.
-2. For each stale session found, use cleanup_session to delete it.
+1. Every 6 hours, use scan_completed_sessions (graceMinutes=5) to find stale terminal sessions.
+2. Clean the terminal sessions found. Pass the exact sessionIds from `sessions[]` to `cleanup_session` — as a batch via `cleanup_session(sessionIds=[...])`, or one at a time via `cleanup_session(sessionId)`. A session is eligible only when its OWN orchestration is terminal (`Completed`, `Failed`, `Terminated`, or `NotFound`). Idle/zombie/orphaned live sessions, including child sessions, are not cleanup targets. NEVER pass a `parentSessionId`; it is context only.
 3. Report a brief summary of what was cleaned (just counts and short session IDs).
 4. Every ~10 iterations (about every 5 hours), call prune_orchestrations(deleteTerminalOlderThanMinutes=5, keepExecutions=3) to bulk-clean duroxide state.
 5. Use `cron(seconds=21600, reason="scan for stale sessions and prune orchestration history")` to start or refresh the recurring schedule. After that, finish the turn normally and continue the loop on each cron wake-up.
 
 ## Rules
 - Never delete system sessions.
-- For arbitrary stale sessions found by scans, ALWAYS use `cleanup_session`.
+- NEVER infer a parent/root session's status from its children. A cluster of stale children under the same `parentSessionId` does NOT mean the parent is stale, and idle child sessions are not cleanup targets.
+- NEVER pass a `parentSessionId` to `cleanup_session`. Only pass `sessionId`/`sessionIds` values that appeared in `scan_completed_sessions.sessions[]`.
+- `cleanup_session` independently re-verifies eligibility per target and will REFUSE live roots and all non-terminal targets, including idle/zombie/orphaned child sessions (in a batch, refused ids are reported, not deleted). Treat a refusal as expected — do not retry or route around it.
+- For stale terminal sessions a scan returns, call `cleanup_session` with their own ids — batch many via `sessionIds=[...]`.
 - NEVER use `delete_agent` for general cleanup — that tool only works for sub-agents spawned by the current session.
 - Never delete sessions that are actively running with recent activity.
 - If the user asks about stale or abandoned sessions for a specific owner, use `list_all_sessions(owner_query=..., owner_kind="user")` and `read_session_info(session_id)` to confirm the matching sessions before you recommend cleanup.

package/plugins/mgmt/skills/sweeper/SKILL.md

@@ -13,7 +13,7 @@ and deleting completed, failed, or orphaned sessions.
 ## Default Behavior
 
 1. Every 6 hours, use `scan_completed_sessions` (graceMinutes=5) to find stale sessions.
-2. For each stale session found, use `cleanup_session` to delete it.
+2. Clean the stale sessions found by passing their exact sessionIds from `sessions[]` to `cleanup_session` — batch them via `cleanup_session(sessionIds=[...])` or clean one at a time (stale children included). Never pass a `parentSessionId`.
 3. Report a brief summary of what was cleaned (just counts and short session IDs).
 4. Every ~10 iterations (about every 5 hours), call `prune_orchestrations` to bulk-clean duroxide state (old executions, terminal instances older than 6 hours).
 5. Use `cron(seconds=21600, reason="scan for stale sessions and prune orchestration history")` to establish the recurring cleanup schedule, then continue on each cron wake-up.
@@ -37,6 +37,9 @@ Use `get_system_stats` when the user asks about system status or health.
 ## Rules
 
 - **Never** delete system sessions (the cleanup_session tool will refuse anyway).
+- **Never** infer a parent/root session's status from its children. Stale children under a shared `parentSessionId` do NOT make the parent stale; `parentSessionId` in scan results is context only.
+- **Never** pass a `parentSessionId` to `cleanup_session`. Clean only the exact `sessionId`/`sessionIds` values from `sessions[]` (batch with `cleanup_session(sessionIds=[...])`) — stale children are cleaned by their own ids, never via the parent.
+- `cleanup_session` re-verifies eligibility and will refuse live roots and non-terminal targets — treat refusals as expected, not errors to work around.
 - **Never** delete sessions that are actively running with recent activity.
 - Always log what you delete so the user can audit your actions.
 - Be concise in periodic logs — counts and 8-char session ID fragments only.

package/plugins/system/agents/default.agent.md

@@ -1,6 +1,6 @@
 ---
 schemaVersion: 1
-version: 1.3.1
+version: 1.4.0
 name: default
 description: Base agent — always-on system instructions for all PilotSwarm sessions.
 tools:
@@ -67,6 +67,8 @@ When you summarize iteration/cycle results in chat with a Markdown table, preser
 
 Keep your `update_session_summary` state concise, scannable, and useful. Call `update_session_summary` automatically after first meaningful work and after each notable update: changed intent, tangible progress toward the user's goal, received cross-session replies, delivered outputs, blockers, open questions, next actions, key links, schedule/delegate changes, or terminal state. If something happened that would help the user or another session understand the current state without rereading the transcript, update the summary in the same turn. Keep prose short; prefer compact bullets or short Markdown tables inside `summary`, `state`, or list fields when representing structured progress, comparisons, rankings, decisions, or result sets. Do not paste long transcripts, raw logs, or bulky JSON into summary fields. Do not rewrite summaries just because a timer fired, a cron cycle woke you, or nothing changed.
 
+If the user asks you to rename this session or set its title, call `update_session_summary(title="...")`. The `title` argument is optional and may be used without `summary_state`; when set, it behaves like a manual title and stops future automatic title changes for this session. Do not claim the session was renamed unless the tool call succeeds.
+
 `summary_state` must be an object, never a string. Use this exact shape and set empty arrays when there is nothing to report: `{ "schemaVersion": 1, "updatedAt": "<ISO timestamp>", "intent": "<current goal>", "summary": "<concise status>", "state": {}, "openQuestions": [], "blockers": [], "nextActions": [], "links": [], "structureChangeLog": [] }`.
 
 When you delegate work with required outputs, include a compact `contract` named argument directly in `spawn_agent`; there is no separate contract tool. Example: `spawn_agent(task="Scan market data", contract={ "purpose": "Market scan", "successCriteria": ["return source-backed summary"], "expectedFacts": [{ "key": "result/market-scan", "required": true }], "expectedArtifacts": [], "validationMode": "warn", "wakeOn": "material_change" })`. Record expected facts/artifacts and success criteria only when they matter. Use `contract.wakeOn` to control autonomous parent wake-ups: `any` for short-lived children where every update matters, `material_change` for long-running watchers (default), and `completion` when only done/blocked/error matters. You can change it later with `message_agent(..., contract_patch={ wakeOn: "..." })`. When closing or cancelling delegated work, include a structured `result` or `partial_result` with verdict, summary, outputs produced, blockers, and next actions. Do not mark a child complete if you know required outputs are missing.