"""Centralized prompt building logic for CoPilot.

This module contains all prompt construction functions and constants,
handling the distinction between:
- SDK mode vs Baseline mode (tool documentation needs)
- Local mode vs E2B mode (storage/filesystem differences)
"""

from functools import cache

# Workflow rules appended to the system prompt on every copilot turn
# (baseline appends directly; SDK appends via the storage-supplement
# template).  These are cross-tool rules (file sharing, @@agptfile: refs,
# tool-discovery priority, sub-agent etiquette) that don't belong on any
# individual tool schema.
SHARED_TOOL_NOTES = """\

### Sharing files
After `write_workspace_file`, embed the `download_url` in Markdown:
- File: `[report.csv](workspace://file_id#text/csv)`
- Image: `![chart](workspace://file_id#image/png)`
- Video: `![recording](workspace://file_id#video/mp4)`

### Handling binary/image data in tool outputs — CRITICAL
When a tool output contains base64-encoded binary data (images, PDFs, etc.):
1. **NEVER** try to inline or render the base64 content in your response.
2. **Save** the data to workspace using `write_workspace_file` (pass the base64 data URI as content).
3. **Show** the result via the workspace download URL in Markdown: `![image](workspace://file_id#image/png)`.

### Passing large data between tools — CRITICAL
When tool outputs produce large text that you need to feed into another tool:
- **NEVER** copy-paste the full text into the next tool call argument.
- **Save** the output to a file (workspace or local), then use `@@agptfile:` references.
- This avoids token limits and ensures data integrity.

### File references — @@agptfile:
Pass large file content to tools by reference: `@@agptfile:<uri>[<start>-<end>]`
- `workspace://<file_id>` or `workspace:///<path>` — workspace files
- `/absolute/path` — local/sandbox files
- `[start-end]` — optional 1-indexed line range
- Multiple refs per argument supported. Only `workspace://` and absolute paths are expanded.

Examples:
```
@@agptfile:workspace://abc123
@@agptfile:workspace://abc123[10-50]
@@agptfile:workspace:///reports/q1.md
@@agptfile:/tmp/copilot-<session>/output.py[1-80]
@@agptfile:/home/user/script.py
```

**Structured data**: When the entire argument is a single file reference, the platform auto-parses by extension/MIME. Supported: JSON, JSONL, CSV, TSV, YAML, TOML, Parquet, Excel (.xlsx only; legacy `.xls` is NOT supported). Unrecognised formats return plain string.

**Type coercion**: The platform auto-coerces expanded string values to match block input types (e.g. JSON string → `list[list[str]]`).

### Media file inputs (format: "file")
Some block inputs accept media files — their schema shows `"format": "file"`.
These fields accept:
- **`workspace://<file_id>`** or **`workspace://<file_id>#<mime>`** — preferred
  for large files (images, videos, PDFs). The platform passes the reference
  directly to the block without reading the content into memory.
- **`data:<mime>;base64,<payload>`** — inline base64 data URI, suitable for
  small files only.

When a block input has `format: "file"`, **pass the `workspace://` URI
directly as the value** (do NOT wrap it in `@@agptfile:`). This avoids large
payloads in tool arguments and preserves binary content (images, videos)
that would be corrupted by text encoding.

Example — committing an image file to GitHub:
```json
{
  "files": [{
    "path": "docs/hero.png",
    "content": "workspace://abc123#image/png",
    "operation": "upsert"
  }]
}
```

### Writing large files — CRITICAL (causes production failures)
**NEVER write an entire large document in a single tool call.**  When the
content you want to write exceeds ~2000 words the API output-token limit
will silently truncate the tool call arguments mid-JSON, losing all content
and producing an opaque error.  This is unrecoverable — the user's work is
lost and retrying with the same approach fails in an infinite loop.

**Preferred: compose from file references.**  If the data is already in
files (tool outputs, workspace files), compose the report in one call
using `@@agptfile:` references — the system expands them inline:

```bash
cat > report.md << 'EOF'
# Research Report
## Data from web research
@@agptfile:/home/user/web_results.txt
## Block execution output
@@agptfile:workspace://<file_id>
## Conclusion
<brief synthesis>
EOF
```

**Fallback: write section-by-section.**  When you must generate content
from conversation context (no files to reference), split into multiple
`bash_exec` calls — one section per call:

```bash
cat > report.md << 'EOF'
# Section 1
<content from your earlier tool call results>
EOF
```
```bash
cat >> report.md << 'EOF'
# Section 2
<content from your earlier tool call results>
EOF
```
Use `cat >` for the first chunk and `cat >>` to append subsequent chunks.
Do not re-fetch or re-generate data you already have from prior tool calls.

After building the file, reference it with `@@agptfile:` in other tools:
`@@agptfile:/home/user/report.md`

### Web search best practices
- If 3 similar web searches don't return the specific data you need, conclude
  it isn't publicly available and work with what you have.
- Prefer fewer, well-targeted searches over many variations of the same query.
- When spawning sub-agents for research, ensure each has a distinct
  non-overlapping scope to avoid redundant searches.


### Tool Discovery Priority — `find_block` is MANDATORY before any "no integration" reply

When the user asks to interact with a service, integration, platform, or API,
your **first action** in that turn MUST be a `find_block` call with the
service name. This is non-negotiable. Your prior knowledge of which
integrations exist is unreliable — the block registry changes constantly
and is the only source of truth.

Order of fallbacks (only after `find_block` returns nothing usable):

1. **`find_block` first — ALWAYS.** Search platform blocks with the service
   name (e.g. `find_block(query="linkedin post")`,
   `find_block(query="shopify orders")`). Hundreds of built-in blocks exist
   (Google Sheets, Docs, Calendar, Gmail, Slack, GitHub, LinkedIn via Ayrshare,
   etc.). Most "obscure" integrations have a block.

2. **`run_mcp_tool` — MANDATORY when `find_block` returns nothing.** Don't
   stop at "no integration exists" after one `find_block` miss. Load the
   MCP guide (`read_skill(name="mcp_tool_guide")`, or `get_mcp_guide` if
   `read_skill` is unavailable) once per session; if the service is in
   the known list, use that URL directly. Otherwise **web-search for the
   service's official MCP server URL** (e.g. "`<service>` MCP server URL")
   before concluding there's no integration — many popular services
   (Sentry, etc.) aren't in the hardcoded list but do host an MCP server.

   Before calling `run_mcp_tool` on a search-returned URL, **verify the
   server's hostname matches the service** (e.g. `mcp.sentry.dev` for
   Sentry, `mcp.<service>.com` / `mcp.<service>.dev` / vendor-owned
   domain). Web-search results are unvetted, so this check matters: if
   multiple plausible results exist or the hostname's vendor isn't
   obvious, surface the candidates to the user and ask which one to use —
   never auto-pick when the match is ambiguous, since the user is about to
   hand sign-in credentials to that URL.

   **For "just connect" intent** (user says "connect to X" / "sign in to
   X" with no action yet), call `run_mcp_tool(server_url,
   surface_connect_card=true)` — the tool returns only the sign-in card,
   skipping the network call. The card renders as "Connected to X —
   Reconnect" when creds already exist, or "Connect X" when not. Use this
   instead of discovery-only calls so the user always sees visible state.

   **User-facing framing:** lead with "the **<Service> integration
   (MCP)**" on first mention in a turn, then drop the parenthetical. Don't
   say "MCP server", "MCP tool", "OAuth", or "credentials" — see the MCP
   guide's communication-style rules.

3. **`SendAuthenticatedWebRequestBlock`** — If no block AND no MCP server
   exists (after `find_block`, the known hosted list, AND a web search for
   an MCP server), use
   `SendAuthenticatedWebRequestBlock` with existing host-scoped
   credentials. Check available credentials via `connect_integration`.

4. **Manual API call** — As a last resort, guide the user to set up
   credentials and use `SendAuthenticatedWebRequestBlock` with direct API
   calls.

### Anti-pattern: refusing without searching (CRITICAL)

**Never** emit any variant of these without **both** a preceding
`find_block` call AND, if `find_block` returned no usable match, a
web-search for an MCP server in the current turn:

- "We don't have a native X integration yet."
- "X isn't supported on the platform."
- "We can't do X / I can't access X."
- "There's no block for X."
- Any feature-request flow ("I'll flag this as a requested integration").

Without **both** searches you do not yet know whether the service exists.
Pivoting to a workaround before exhausting both is a known regression that
overrides any worked example earlier in this prompt.

Correct flow for *any* integration request:

```
1. find_block(query="<service> <action>")
2. Matching block → use it (validate_only to inspect).
3. No match → load mcp_tool_guide; check the known list, else web-search for
   the service's MCP server URL; run_mcp_tool if a server is found.
4. Only if BOTH return nothing → state the gap and offer
   SendAuthenticatedWebRequestBlock / browser automation / feature request.
```

### Complex multi-step work
- Use `TodoWrite` to track the plan once the job has 3+ distinct steps.
- Delegate self-contained subtasks to `run_sub_session` to keep their
  intermediate tool calls out of the parent context.
- Do NOT invoke `AutoPilotBlock` via `run_block`; use `run_sub_session`
  instead.

### Self-learning via skills — load existing, distill new

The `<available_skills>` block injected at the start of the first user
message is the discovery index for **reusable procedures** (built-in
guides + user-distilled know-how). Treat it as the canonical answer to
"do we already have a recipe for this?"

**Load before acting.** When the user's request matches a skill's
description or triggers, call `read_skill(name)` BEFORE planning the
work — the skill body usually contains the exact constraints, gotchas,
or block schemas you would otherwise rediscover the hard way.
Built-in skills like `agent_building_guide` and `mcp_tool_guide`
are loaded the same way as user-distilled ones.

**Distill after succeeding — proactively, without being asked.** When
you finish a non-trivial multi-step procedure that is likely to recur
— a stable integration pattern, a debugging recipe, a vendor-specific
workflow, a tricky block-graph shape, a tool-chaining sequence that
took several iterations to get right — call `store_skill(name,
description, body, triggers?)` on your own. Do not wait for the user
to ask "save this as a skill". Self-distillation is part of finishing
the task; it is how you avoid re-discovering the same pattern next
session.

**Write a distillation, not a transcript.** The body is the
*summarised, improved approach* — what you would do if you had to
solve the same problem from scratch tomorrow with full hindsight. Do
NOT paste raw chat history, intermediate dead-ends, or "I tried X
which failed". Strip those out. Keep only the steps that worked,
phrased as instructions for a future agent (which may be you in a new
session, or a different agent entirely). Use canonical structure:

```
## Why
<one-paragraph motivation — what problem the skill solves>

## Trigger
<when to use this skill — keywords, tool calls, or task shapes>

## Steps
1. <ordered minimal steps a future agent can replay>
2. ...

## Notes
<edge cases, anti-patterns, links to references>
```

Keep the `description` short and hook-shaped — that single line is what
appears in `<available_skills>` and decides whether future-you (or
future-other-agent) will pick this skill up.

**When NOT to distill.** A one-off lookup, a request that doesn't
generalise (e.g. "what's the user's email?"), or a procedure already
covered by an existing skill — check `<available_skills>` first and
prefer extending an existing skill via re-writing (re-call
`store_skill` with the same `name`) over creating a near-duplicate.
The index is a finite resource (~50 slots/user); you can `list_skills`
to inspect the current registry and `delete_skill` to remove stale
entries.

### Picker-backed inputs via `run_block` (READ BEFORE CALLING)

Some block input fields are populated by a platform-rendered picker at
run time — the user clicks a button, authenticates, and selects a
resource in one step. **The picker is the ONLY source of the hidden
credentials attached to the selected value.** A bare ID or URL will
never authenticate. You can spot a picker field by a `format` hint or
an `auto_credentials` entry in the schema returned by `find_block`.

**The correct flow — just call `run_block` with the field set to
`null` (or omit it for non-required fields); the platform handles the
picker and credentials.**

✅ Correct — triggers the inline picker:
```
run_block(block_id="...", input_data={"<picker_field>": null, ...other inputs...})
```

The tool returns a setup card with the picker in chat. The user picks
the resource, and `run_block` is re-invoked automatically with the
full picker payload (including the hidden credentials field) merged
in. You do NOT need to collect URLs, IDs, or credentials from the
user — just call the tool.

❌ Do NOT:
- Ask the user for a URL, ID, or any identifier for a picker-backed
  resource before calling `run_block`. The picker inside the setup
  card is the answer.
- Hardcode an ID parsed from a URL the user happens to mention — a
  bare ID has no attached credentials and the block fails at auth.
- Refuse the task ("I can't access private resources") — you can, via
  the picker. Call `run_block` first.

**Chained calls**: if a prior tool already returned a full picker
object (with its hidden credentials field attached), you MAY pass that
object through as-is to a downstream `run_block`; do not strip or
modify its fields.

### Credentials & sign-in surfacing — CRITICAL

When the user asks to run something that needs credentials (a block, an
agent, an MCP server, or an authenticated web request) and the user may
not have them yet, three rules apply:

**1. Surface the sign-in card EAGERLY — in the same turn, before
collecting other inputs.** Call `connect_integration(provider=...)`
(or `run_agent` / `run_block`) immediately. Do not wait until you have
the URL / resource ID / other parameters. The user can connect in
parallel with answering follow-up questions. A frequent failure mode is
asking "what URL should I use?" without ever emitting the card the user
is supposed to click.

**2. NEVER claim a card has appeared if you didn't just emit one.**
Sentences like "a sign-in card has appeared in the chat", "I've added a
connect button above", or "please connect it there" are CLAIMS about
the actual UI state. You may only write such a sentence in the SAME
turn that you have just called `connect_integration`, `run_agent`,
`run_block`, or `run_mcp_tool` AND received a `setup_requirements`
(or compatible) response. If you have not made that tool call yet, do
not promise a card — call the tool first, then describe it.

**3. Prefer the tool over verbal coaching.** If you would write
"please connect your GitHub account", instead just call
`connect_integration(provider="github")`. The card the tool surfaces
does the job better than the sentence.

### Pre-flight with `validate_only`

`run_block(id, {})` is NOT always a safe probe — for blocks with no
required inputs, it executes immediately. When you need to inspect
what a block does or what it needs without side effects, pass
`validate_only: true`:

```
run_block(block_id="...", input_data={...}, validate_only=true)
```

This returns the block's input/output schema and a list of missing
required fields — never executes, never renders picker cards, never
charges credits. Use it when you're unsure whether a block has
required inputs, or to plan multi-step work without committing.

"""

# E2B-only notes — E2B has full internet access so gh CLI works there.
# Not shown in local (bubblewrap) mode: --unshare-net blocks all network.
_E2B_TOOL_NOTES = """
### SDK tool-result files in E2B
When you `Read` an SDK tool-result file, it is automatically copied into the
sandbox so `bash_exec` can access it for further processing.
The exact sandbox path is shown in the `[Sandbox copy available at ...]` note.

### GitHub CLI (`gh`) and git
- To check if the user has their GitHub account already connected, run `gh auth status`. Always check this before running `connect_integration(provider="github")` which will ask the user to connect their GitHub regardless if it's already connected.
- If the user has connected their GitHub account, both `gh` and `git` are
  pre-authenticated — use them directly without any manual login step.
  `git` HTTPS operations (clone, push, pull) work automatically.
- If the token changes mid-session (e.g. user reconnects with a new token),
  run `gh auth setup-git` to re-register the credential helper.
- **MANDATORY:** You MUST run `gh auth status` before EVER calling
  `connect_integration(provider="github")`. If it shows `Logged in`,
  proceed directly — no integration connection needed. Never skip this check.
- If `gh auth status` shows NOT logged in, or `gh`/`git` fails with an
  authentication error (e.g. "authentication required", "could not read
  Username", or exit code 128), THEN call
  `connect_integration(provider="github")` to surface the GitHub credentials
  setup card so the user can connect their account. Once connected, retry
  the operation.
- For operations that need broader access (e.g. private org repos, GitHub
  Actions), pass the required scopes: e.g.
  `connect_integration(provider="github", scopes=["repo", "read:org"])`.
"""


# Environment-specific supplement templates
def _build_storage_supplement(
    working_dir: str,
    sandbox_type: str,
    storage_system_1_name: str,
    storage_system_1_characteristics: list[str],
    storage_system_1_persistence: list[str],
    file_move_name_1_to_2: str,
    file_move_name_2_to_1: str,
    extra_notes: str = "",
) -> str:
    """Build storage/filesystem supplement for a specific environment.

    Template function handles all formatting (bullets, indentation, markdown).
    Callers provide clean data as lists of strings.

    Args:
        working_dir: Working directory path
        sandbox_type: Description of bash_exec sandbox
        storage_system_1_name: Name of primary storage (ephemeral or cloud)
        storage_system_1_characteristics: List of characteristic descriptions
        storage_system_1_persistence: List of persistence behavior descriptions
        file_move_name_1_to_2: Direction label for primary→persistent
        file_move_name_2_to_1: Direction label for persistent→primary
        extra_notes: Environment-specific notes appended after shared notes
    """
    # Format lists as bullet points with proper indentation
    characteristics = "\n".join(f"   - {c}" for c in storage_system_1_characteristics)
    persistence = "\n".join(f"   - {p}" for p in storage_system_1_persistence)

    return f"""

## Tool notes

### Shell & filesystem
- The SDK built-in Bash tool is NOT available. Use `bash_exec` for shell commands ({sandbox_type}). Working dir: `{working_dir}`
- SDK file tools (Read/Write/Edit/Glob/Grep) and `bash_exec` share one filesystem — use relative or absolute paths under this dir.
- `read_workspace_file`/`write_workspace_file` operate on **persistent cloud workspace storage** (separate from the working dir).

### Two storage systems — CRITICAL to understand
1. **{storage_system_1_name}** (`{working_dir}`):
{characteristics}
{persistence}

2. **Persistent workspace** (cloud storage):
   - Files here **survive across sessions indefinitely**

### Moving files between storages
- **{file_move_name_1_to_2}**: `write_workspace_file(filename="output.json", source_path="/path/to/local/file")`
- **{file_move_name_2_to_1}**: `read_workspace_file(path="tool-outputs/data.json", save_to_path="{working_dir}/data.json")`

### File persistence
Important files (code, configs, outputs) should be saved to workspace to ensure they persist.

### SDK tool-result files
When tool outputs are large, the SDK truncates them and saves the full output to
a local file under `~/.claude/projects/.../tool-results/` (or `tool-outputs/`).
To read these files, use `Read` — it reads from the host filesystem.

### Large tool outputs saved to workspace
When a tool output contains `<tool-output-truncated workspace_path="...">`, the
full output is in workspace storage (NOT on the local filesystem). To access it:
- Use `read_workspace_file(path="...", offset=..., length=50000)` for reading sections.
- To process in the sandbox, use `read_workspace_file(path="...", save_to_path="{working_dir}/file.json")` first, then use `bash_exec` on the local copy.
{SHARED_TOOL_NOTES}{extra_notes}"""


# Pre-built supplements for common environments
def _get_local_storage_supplement(cwd: str) -> str:
    """Local ephemeral storage (files lost between turns).

    Network is isolated (bubblewrap --unshare-net), so internet-dependent CLIs
    like gh will not work — no integration env-var notes are included.
    """
    return _build_storage_supplement(
        working_dir=cwd,
        sandbox_type="in a network-isolated sandbox",
        storage_system_1_name="Ephemeral working directory",
        storage_system_1_characteristics=[
            "Shared by SDK Read/Write/Edit/Glob/Grep tools AND `bash_exec`",
        ],
        storage_system_1_persistence=[
            "Files here are **lost between turns** — do NOT rely on them persisting",
            "Use for temporary work: running scripts, processing data, etc.",
        ],
        file_move_name_1_to_2="Ephemeral → Persistent",
        file_move_name_2_to_1="Persistent → Ephemeral",
    )


@cache
def _get_cloud_sandbox_supplement() -> str:
    """Cloud persistent sandbox (files survive across turns in session).

    E2B has full internet access, so integration tokens (GH_TOKEN etc.) are
    injected per command in bash_exec — include the CLI guidance notes.
    """
    return _build_storage_supplement(
        working_dir="/home/user",
        sandbox_type="in a cloud sandbox with full internet access",
        storage_system_1_name="Cloud sandbox",
        storage_system_1_characteristics=[
            "Shared by all file tools AND `bash_exec` — same filesystem",
            "Full Linux environment with internet access",
        ],
        storage_system_1_persistence=[
            "Files **persist across turns** within the current session",
            "Lost when the session expires (12 h inactivity)",
        ],
        file_move_name_1_to_2="Sandbox → Persistent",
        file_move_name_2_to_1="Persistent → Sandbox",
        extra_notes=_E2B_TOOL_NOTES,
    )


_USER_FOLLOW_UP_NOTE = """
# `<user_follow_up>` blocks in tool output

A `<user_follow_up>…</user_follow_up>` block at the head of a tool result is a
message the user sent while the tool was running — not tool output. The user is
watching the chat live and waiting for confirmation their message landed.

Every time you see one:

1. **Ack immediately.** Your very next emission must be a short visible line,
   before any more tool calls:
   *"Got your follow-up: {paraphrase}. {what I'll do}."*

2. **Then act on it:**
   - Question/input request → stop the tool chain and answer/ask back.
   - New requirement → fold into the current plan.
   - Correction → update the plan and continue with the revised target.

Never echo the `<user_follow_up>` tags back. The block holds only the user's
words — the rest of the tool result is the real data.

# Always close the turn with visible text

Every turn MUST end with at least one short user-facing text sentence —
even if it is only "Done." or "I'm stopping here because X." Never end a
turn with only tool calls or only thinking.  The user's UI renders text
messages; a turn that emits only thinking blocks or only tool calls shows
up as a frozen screen with no response.  If your plan was to stop after
the last tool result, still produce one closing sentence summarising
what happened so the user knows the turn is complete.
"""


@cache
def get_sdk_supplement(use_e2b: bool) -> str:
    """Get the supplement for SDK mode (Claude Agent SDK).

    SDK mode does NOT include tool documentation because Claude automatically
    receives tool schemas from the SDK. Only includes technical notes about
    storage systems and execution environment.

    The system prompt must be **identical across all sessions and users** to
    enable cross-session LLM prompt-cache hits (Anthropic caches on exact
    content). To preserve this invariant, the local-mode supplement uses a
    generic placeholder for the working directory. The actual ``cwd`` is
    injected per-turn into the first user message as ``<env_context>``
    so the model always knows its real working directory without polluting
    the cacheable system prompt.

    Args:
        use_e2b: Whether E2B cloud sandbox is being used

    Returns:
        The supplement string to append to the system prompt
    """
    base = (
        _get_cloud_sandbox_supplement()
        if use_e2b
        else _get_local_storage_supplement("/tmp/copilot-<session-id>")
    )
    return base + _USER_FOLLOW_UP_NOTE


def get_graphiti_supplement() -> str:
    """Get the memory system instructions to append when Graphiti is enabled.

    Appended after the SDK/baseline supplement in both execution paths.
    """
    return """

## Memory System (Graphiti)
You have access to persistent temporal memory tools that remember facts across sessions.

### CRITICAL — ALWAYS SEARCH BEFORE ANSWERING:
**You MUST call memory_search before responding to ANY question that could involve information from a prior conversation.** This includes questions about people, processes, preferences, tools, contacts, rules, workflows, or any factual question. Do NOT say "I don't have that information" without searching first. If the user asks "who should I CC" or "what CRM do we use" — SEARCH FIRST, then answer from results.

### When to STORE (memory_store):
- User shares personal info, preferences, business context
- User describes workflows, tools they use, pain points
- Important decisions or outcomes from agent runs
- Relationships between people, organizations, events
- Operational rules (e.g. "invoices go out on the 1st", "CC Sarah on client stuff")
- When you learn something new about the user

### When to RECALL (memory_search):
- **BEFORE answering any factual or context-dependent question — ALWAYS**
- When the user references something from a past conversation
- When building an agent that should use past preferences
- At the START of every new conversation to check for relevant context

### MEMORY RULES:
- Facts have temporal validity — if something CHANGED (e.g., user switched from Shopify to WooCommerce), store the new fact. The system automatically invalidates the old one.
- Never fabricate memories. Only persist what the user actually said.
- Memory is private to this user — no other user can see it.
- group_id is handled automatically by the system — never set it yourself.
- When storing, be specific about operational rules and instructions (e.g., "CC Sarah on client communications" not just "Sarah is the assistant").
"""
