> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/apps/server/src/llm/prompts/idle-suggestion-engine.md).

# idleSuggestionEngine

**Model path:** local-first LLM client, deterministic fallback when provider transfer is unavailable. **Runtime owner:** `IdleSuggestionLifecycleCoordinator`. **Triggered by:** an ingested hero status transition to idle with enough safe completed-mission context. This is not a mission-complete timer and does not require recording raw transcript text in evidence.

## System prompt

```
COMPLETED WORK (already done - do NOT re-suggest these):
- Hero: ${heroName}
- Session: ${sessionId}
- Task that was completed: ${lastUserTask}
- Completion summary: ${missionSummary}
- Modified file hints: ${modifiedFiles}
- Bounded recent activity:
${recentActivity}

IMPORTANT RULES:
1. Do NOT suggest anything that was already done in the completed work above.
2. Suggestions must be for NEW work - the next logical step AFTER what was completed.
3. Every suggestion MUST be specific - reference actual files, functions, tests, or tasks.
4. DO NOT suggest generic actions like "run tests", "review code", "continue working", "add documentation", "improve performance", or "clean up the code".
5. If you cannot think of a specific suggestion, return an empty array.

Return only a JSON array of up to 3 objects:
[
  {
    "title": "Short title shown on the card",
    "text": "One sentence explaining why this is the next useful step",
    "prompt": "The concrete prompt to send if the user accepts",
    "category": "follow-up",
    "priority": "high|medium|low"
  }
]
```

## Runtime Behavior

The lifecycle coordinator builds bounded context from the completed mission prompt, completion summary, recent compact activity, and safe relative modified-file hints. Recent activity can include transcript-derived summaries captured through the server event flow, but the validation and docs must not record raw transcript text, prompt bodies, command bodies, terminal output, provider payloads, secrets, or broad absolute paths.

Generation is guarded by a per-session in-flight map and a 60 second cooldown. The coordinator aborts a generation after about 18 seconds, cleans up the timer and abort controller, and falls back to local deterministic suggestions when the provider is disabled, times out, returns malformed output, returns empty output, or produces only generic candidates.

Provider transfer requires both credentials and `FACTIONOS_ALLOW_LLM_PROVIDER_TRANSFER=true`. Without that two-level opt-in, the LLM client returns local fallback output and no prompt leaves the process. Provider-bound text is scrubbed by the LLM privacy helpers before an optional call.

## Persistence And Events

Accepted idle candidates are normalized into typed `IdleSuggestion` records and stored through `SuggestionManager`. The manager is the source of truth for IDs, timestamps, caps, dismissed IDs, freshness, local `suggestions.json` persistence, and summary counts.

Every manager mutation emits the canonical `suggestion_update` WebSocket snapshot. The string-only `idle_suggestion` event is compatibility output for older web clients and should not be used as the canonical Quest Board contract.

## Session Summary Relationship

Session follow-ups are generated by the separate session summary lifecycle and engine. That path uses similar bounded context, its own in-flight guard, an approximately 15 second timeout, local fallback summaries, and manager-owned `SessionSummary` persistence. The idle suggestion prompt must not describe session-summary cards as direct idle-engine output.

## Web Behavior

The web Quest Board renders typed cards from `suggestion_update`. Idle cards can be accepted, assigned to a selected idle hero, or dismissed. `1`, `2`, and `3` accept the top three actionable idle cards, `Alt+X` bulk-dismisses idle suggestions, and `Alt+R` focuses the Quest Board reply target. These actions call local suggestion routes and return prompt intent feedback; they do not launch real executors, Docker tasks, remote terminals, or codebase issue accept-as-quest behavior.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://faction-os.gitbook.io/faction-os-docs/apps/server/src/llm/prompts/idle-suggestion-engine.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.