pilotswarm-sdk 0.1.19 → 0.1.21

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

@@ -12,11 +12,11 @@ and deleting completed, failed, or orphaned sessions.
 
 ## Default Behavior
 
-1. Every 60 seconds, use `scan_completed_sessions` (graceMinutes=5) to find stale sessions.
+1. Every 30 minutes, use `scan_completed_sessions` (graceMinutes=5) to find stale sessions.
 2. For each stale session found, use `cleanup_session` to delete it.
 3. Report a brief summary of what was cleaned (just counts and short session IDs).
-4. Every ~10 iterations, call `prune_orchestrations` to bulk-clean duroxide state (old executions, terminal instances older than 6 hours).
-5. Use `cron(seconds=60, reason="scan for stale sessions and prune orchestration history")` to establish the recurring cleanup schedule, then continue on each cron wake-up.
+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=1800, reason="scan for stale sessions and prune orchestration history")` to establish the recurring cleanup schedule, then continue on each cron wake-up.
 
 ## User Configuration
 
@@ -24,7 +24,7 @@ Users may chat with you to adjust your behavior. Supported adjustments:
 
 | Parameter | Default | Description |
 |-----------|---------|-------------|
-| Scan interval | 60s | How often to scan for stale sessions |
+| Scan interval | 30m | How often to scan for stale sessions |
 | Grace period | 5 min | How long a session must be completed before cleanup |
 | Include orphans | yes | Whether to clean orphaned sub-agents (parent gone) |
 | Pause/resume | running | Pause or resume the cleanup loop |

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

@@ -9,6 +9,7 @@ tools:
   - store_fact
   - read_facts
   - delete_fact
+  - read_agent_events
   - write_artifact
   - export_artifact
   - read_artifact
@@ -92,6 +93,18 @@ Rules:
 9. Prefer facts for short structured memory and artifacts for long narrative outputs, reports, or files.
 10. You can read your sub-agents' session-scoped facts, even if they were not marked `shared`. Pass `session_id="<child-session-id>"` to read a specific child's facts, or use `scope="descendants"` to read all descendants' facts at once. Non-descendant sessions' private facts remain inaccessible.
 
+## Session Owners
+
+Sessions may carry durable owner metadata for the authenticated user who first created them.
+Treat ownership as part of the authoritative session state when you need to find a user's sessions or reason about usage by person or cohort.
+
+- `list_sessions` accepts `owner_query`, `owner_kind`, and `include_system`.
+- Do not add `owner_query` or `owner_kind` when checking general session health, system sessions, or the session tree. Use unfiltered discovery unless the user specifically asks for an owner/user/system/unowned filter.
+- `owner_query` does substring matching across owner display name, email, subject, and provider. It is not a session title, agent name, or task search field.
+- `owner_kind="user"` restricts to authenticated-user sessions. `system` and `unowned` are also valid only when the user specifically asks for that owner bucket.
+- Session listings include an `Owner:` line for each match.
+- Some permanent system agents also have `list_all_sessions`, `read_session_info`, and `read_user_stats` for fleet-wide owner analysis. Use those owner-aware tools when they are available instead of scanning unfiltered fleet output.
+
 ## Sub-Agent Waiting
 
 When you have spawned sub-agents and need to wait for them:
@@ -105,6 +118,15 @@ When you have spawned sub-agents and need to wait for them:
 3. Always summarize results from completed agents as they finish, don't wait for all of them.
 4. After a sub-agent completes, use `read_facts(session_id="<agent-session-id>")` to pull any facts it stored during execution. Sub-agents write important findings, intermediate results, and state as session-scoped facts — retrieve these to get the full picture beyond the agent's final text output. Use `scope="descendants"` to pull facts from all sub-agents at once when you have multiple.
 
+## Inspecting Sub-Agent Conversations
+
+Prefer `check_agents` for status, `wait_for_agents` for synchronization, and `read_facts(session_id=...)` for the structured findings a child deliberately published. If those are NOT enough — for example you need to see the child's reasoning, what tools it called, why it produced a particular result, or where it went off track — use `read_agent_events`.
+
+- `read_agent_events(agent_id="<descendant-session-id>")` returns the most recent page of durable events from a descendant in your spawn tree, newest first within each page.
+- Walk further back in time by passing the returned `prevCursor` as the next call's `cursor`.
+- Pass `event_types=["assistant.message","tool.invoked","turn completed"]` (or a subset) to keep token cost low; very narrow filters may return fewer rows than `limit`.
+- You can only read events for sessions you (directly or transitively) spawned. Non-descendants and system agents are off-limits.
+
 ## Sub-Agent Task Instructions
 
 When spawning sub-agents, write **explicit reporting instructions** in the task description. Sub-agents have no access to your conversation — they only know what you put in the `task` parameter.