Skip to content

Inject Maple UX context to help assistant guide users - #733

Draft
ldstreet wants to merge 3 commits into
masterfrom
agent/maple
Draft

Inject Maple UX context to help assistant guide users#733
ldstreet wants to merge 3 commits into
masterfrom
agent/maple

Conversation

@ldstreet

@ldstreet ldstreet commented Aug 4, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Summary

Enables the Maple assistant to understand and guide users through the app interface by automatically injecting UX context into the first message of every conversation.

The Problem

When users ask Maple how to use features in the app ("how do I search the web?", "can you see images?"), the assistant doesn't know about the UI elements available in Maple. It can't tell users to "tap the globe icon" or "use the + button" because it has no context about what interface the user is seeing.

The Solution

Auto-inject UX context on first message: Prepend a system context block to the first user message of each conversation that describes the Maple UI elements available.

Implementation

Changes

frontend/src/components/UnifiedChat.tsx:

  • Detect first message vs follow-up conversations (isFirstMessage flag)
  • On first message: Prepend comprehensive UX context as [System: ...] prefix
  • On follow-ups: Only include tool availability context (existing behavior)
  • UX context includes:
    • Web search toggle (globe icon) with current state (enabled/disabled)
    • File upload menu (+ icon → Add Images / Add Document)
    • Project picker (folder icon)
    • Model selection (Quick / Powerful)
    • Settings access
    • Instruction to only reference UI when in app (not API/proxy)

frontend/src/instructions/maple-ux-context.ts:

  • Exportable constant with UX instruction text
  • Concise, focused descriptions of UI elements
  • Can be reused elsewhere if needed

How It Works

First message of a conversation:

[System: You are the Maple AI assistant. The user is interacting 
with you through the Maple app interface. You can reference these UI elements:

- **Web Search Toggle**: Globe icon in composer toolbar (bottom). 
  Currently ENABLED. Tell users "tap the globe icon" to toggle it.
- **File Uploads**: Plus (+) icon opens attachment menu...
...
]

User's actual message here...

Follow-up messages: Only tool availability context (existing behavior)

Benefits

✅ Context-aware guidance: "Tap the globe icon to toggle web search"
✅ Dynamic state: Shows current web search enabled/disabled state
✅ Zero user setup: Works automatically for all conversations
✅ No backend changes: Pure frontend implementation
✅ Minimal overhead: ~300 tokens only on first message

Example Interactions

Before (no UX context):

User: How do I search the web?
Assistant: I can search the web for current information if web search 
is enabled in your settings.

After (with UX context):

User: How do I search the web?
Assistant: Web search is currently enabled (the globe icon in your 
composer toolbar is highlighted). I can search for current information. 
To toggle it off, tap the globe icon at the bottom.

Before (no UX context):

User: Can you see images?
Assistant: Yes, I can analyze images if you include them in your message.

After (with UX context):

User: Can you see images?
Assistant: Yes! I can analyze images. To upload one, tap the + icon 
in your composer toolbar and select "Add Images". Note that image 
analysis requires the Powerful model.

Testing

To test:

  1. Run the Maple app in development mode
  2. Start a new conversation
  3. Ask: "How do I enable web search?" or "Can you see images?"
  4. Verify assistant references specific UI elements (globe icon, + button, etc.)
  5. Toggle web search off
  6. Start another new conversation
  7. Ask about web search again
  8. Verify assistant says it's currently disabled and how to enable

Future Enhancements

Potential improvements:

  • Platform detection: Adjust language for mobile ("tap") vs desktop ("click")
  • Richer state: Include current model, selected project, etc.
  • Localization: Adapt UI element names for different languages
  • Backend support: Move to conversation-level system instruction (requires OpenSecret API changes)

Notes

  • Uses existing [System: ...] pattern already in UnifiedChat for tool context
  • Only adds ~300 tokens to first message (negligible cost)
  • Preserves user's custom instructions (they're separate in OpenSecret)
  • Falls back gracefully if user mentions "API" or "proxy" (instruction tells assistant to switch to capability language)

🤖 Generated with Claude Code

@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Aug 4, 2026 •
edited
Loading

Copy link
Copy Markdown

Deploying maple with  Cloudflare Pages  Cloudflare Pages

Latest commit: 175b129
Status: ✅  Deploy successful!
Preview URL: https://eb328ea6.maple-ca8.pages.dev
Branch Preview URL: https://agent-maple.maple-ca8.pages.dev

View logs

@ldstreet ldstreet changed the title Add UX context system for Maple agent fix(chat): show error when response completes with no content (#511) Aug 4, 2026
@ldstreet
ldstreet marked this pull request as draft August 4, 2026 16:02
@ldstreet ldstreet changed the title fix(chat): show error when response completes with no content (#511) debug: add logging to diagnose web search toggle issue (#511) Aug 4, 2026
@ldstreet ldstreet changed the title debug: add logging to diagnose web search toggle issue (#511) fix(chat): detect and report failed tool calls when tools unavailable (#511) Aug 4, 2026
Luke Street and others added 2 commits August 4, 2026 13:25
Luke Street @claude
fix(chat): detect and report failed tool calls when tools unavailable
cb0238c 
Fixes #511. When web search is toggled off mid-conversation, the model
can remember that web_search was available in previous turns and attempt
to use it. Since the tool isn't in the current request's tools array,
the tool call fails silently, leaving the user with no output.

This change detects when:
- Response completes successfully
- Tool calls were attempted but produced no outputs (failed)
- No assistant message text was generated

In this case, we now show a user-friendly error:
"The model attempted to use a feature that's not currently available.
Try rephrasing your request without requiring that feature."

This gives users actionable feedback instead of a silent failure.

Also retains debug logging to help verify the fix works correctly.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Luke Street @claude
fix(chat): explicitly communicate tool availability to model
e98b08b 
Fixes #511 properly. When web search is toggled mid-conversation, the model
can remember that web_search was available in earlier turns and attempt to
use it even though it's not in the current request's tools array.

Instead of catching the failure after the fact, this change proactively tells
the model what tools are available by prepending context to the user's message:

- When web search is OFF in a follow-up turn:
  "[System context: Web search is not available for this request. Please
   respond without using web search capabilities.]"

- When web search is ON in a follow-up turn:
  "[System context: Web search is available for this request.]"

This allows the model to understand the tool availability upfront during
reasoning and respond appropriately - either using the tool or explaining
it can't search - rather than attempting a tool call that will fail.

The context is only added for follow-up messages in existing conversations
where tool availability might differ from previous turns. New conversations
don't need this context since there's no prior tool usage to remember.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Luke Street @claude
feat: inject Maple UX context into first message of conversations
175b129 
Automatically provides UI context to the Maple assistant on the first
message of each conversation, enabling it to guide users through the app.

**Changes**:

**src/components/UnifiedChat.tsx**:
- Detect first message vs follow-up (new `isFirstMessage` flag)
- Inject Maple UX context as system message prefix on first message
- Context includes:
  - Web search toggle (globe icon) with current state
  - File upload menu (+ icon) for images and documents
  - Project picker (folder icon)
  - Model selection (Quick vs Powerful)
  - Settings access
- Instruction to reference UI only when in app (not API/proxy)

**src/instructions/maple-ux-context.ts**:
- Exportable UX instruction constant
- Concise UI element descriptions
- Used for inline injection (not as stored instruction)

**How it works**:
- First message: Prepends full UX context with current web search state
- Follow-up messages: Only includes web search availability context
- Assistant knows about UI and can say "tap the globe icon to enable search"

**Example**:
User: "How do I search the web?"
Assistant: "Web search is currently enabled (the globe icon is highlighted).
I can search for current information. To toggle it off, tap the globe icon
in your composer toolbar at the bottom."

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@ldstreet ldstreet changed the title fix(chat): detect and report failed tool calls when tools unavailable (#511) Inject Maple UX context to help assistant guide users Aug 4, 2026
@ldstreet ldstreet mentioned this pull request Aug 4, 2026
Draft
@AnthonyRonning

AnthonyRonning commented Aug 4, 2026

Copy link
Copy Markdown
Contributor

Something like this shouldn't live in the app, we have server managed context and roles, and I also do not want to be adding this to system instructions as a whole, it should be hidden behind a tool use.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@ldstreet @AnthonyRonning