Enhanced Agent — User Guide

Product: Jokalala AI Development Chat (/ai/chat)
HTML guide: /ai/chat/docs (rich in-app documentation)
Audience: Developers using the Enhanced Agent for secure coding, audits, and gated fixes
Last updated: 2026-08-03

Open the product: Launch AI Chat →

This guide explains how to use the Enhanced Agent end to end: attach project context, turn on tools, run security remediations, accept patches into VS Code or Cursor, and keep the cloud snapshot in sync—without giving the cloud agent write access to your disk.

Related technical docs: PRODUCT.md · TOOLS.md · REMEDIATION_ENGINE.md · IDE_BRIDGE.md · WEB_SEARCH.md · AI_INNOVATIONS_USER_GUIDE.md

Table of contents

1. What the Enhanced Agent is
2. Access and entry points
3. Safety model (read this once)
4. Quick start (10 minutes)
5. Composer controls
6. Project context and indexing
7. Using Tools (repo-browsing agent)
8. Security audit and remediation
9. Accepting patches (IDE bridge)
10. Keeping the snapshot fresh
11. Web Search and CVE context
12. Innovations UX (intent, branches, more)
13. Providers, BYOK, and racing
14. Shell proposals (opt-in)
15. Keyboard shortcuts
16. Recommended workflows
17. Limits and practical tips
18. Troubleshooting
19. FAQ
20. Glossary

1. What the Enhanced Agent is

The Enhanced Agent is Jokalala’s coding partner in the browser with optional tool calling against an indexed copy of your project. It is designed for:

It is not a full autonomous local IDE agent (like Cursor Agent with unrestricted shell). The cloud side stays a read-only sandbox. Your machine applies changes only after you approve them.

2. Access and entry points

Deep links

• Development assistant: /ai/chat?agent=development_assistant
• Analytics agent: /ai/chat?agent=analytics
• Open with context from the extension/CLI: /ai/chat?context=… (attached as chips)

Sign in on the web, then sign in from the extension (or set Jokalala: Set API Key) so Accept deep links can fetch proposals with the same user identity.

3. Safety model (read this once)

┌─────────────────────┐         ┌──────────────────────────┐
│  Browser Dev Chat   │  read   │  Redis project snapshot   │
│  + Tools agent      │ ──────► │  + proposals / findings  │
└─────────┬───────────┘         └──────────────────────────┘
          │ Accept (proposalId)
          ▼
┌─────────────────────┐         ┌──────────────────────────┐
│  VS Code / Cursor   │ Confirm │  Your local workspace    │
│  Jokalala extension │ ──────► │  (git-friendly edits)    │
└─────────────────────┘         └──────────────────────────┘

Invariant: The server never writes workspace files. Patches are always gated.

4. Quick start (10 minutes)

1. Open /ai/chat and sign in.
2. Install / enable the Jokalala Code Analyzer extension in VS Code or Cursor.
3. Set jokalala.apiEndpoint (production HTTPS, or local http://localhost:3000/api/agents/dev-assistant) and API key.
4. In chat, click Project and upload a .zip of your source (or use GitHub → Index folder when connected).
5. Turn on the composer Tools chip.
6. Ask: “Audit auth for security issues and propose minimal fixes.”
7. Watch tool cards (grep_search, read_file, …). When a patch needs approval, click Accept.
8. In the IDE: review the diff → Apply on the Confirm dialog.
9. Commit with your normal git workflow.

Optional: enable jokalala.ideBridge.deltaSync so local saves refresh the cloud snapshot without re-uploading a zip.

5. Composer controls

Chips above the composer show attached context (files, project snapshot, scan findings). Remove chips when you want a clean turn.

6. Project context and indexing

Why indexing matters

On serverless hosting, the agent cannot see your live disk. It only sees:

1. Files attached to the current turn, merged with
2. Your durable project snapshot (chat-project in Redis), plus an optional code vector index for semantic search

How to index

Caps and exclusions

• Default max full files: 32 (env: CHAT_PROJECT_SNAPSHOT_MAX_FILES / NEXT_PUBLIC_CHAT_PROJECT_MAX_FILES).
• Hard max entries: 64 — overflow paths become signature stubs (stub: true); Hydrate from IDE upgrades them.
• Large files are truncated (on the order of ~100k characters per file).
• Build artifacts and dependency trees should stay out of the zip (node_modules, .next, dist, lockfiles, binaries).
• If the agent needs a path outside the snapshot, click Hydrate from IDE on the tool card (extension pushes that file via delta).

After reload

Snapshots are user-scoped and durable (typically ~7 days TTL). Reloading chat still hydrates the last indexed project when the turn has no fresh attachments.

7. Using Tools (repo-browsing agent)

Turn Tools on

Click the Tools chip until it shows as on, or rely on Scan this (which turns Tools on for remediations).

You will see live tool cards as the agent works (running → done / needs approval).

Browse tools (read-only)

Guidance helpers

• get_security_guidance — OWASP-oriented playbooks
• format_unified_diff_hint — how to shape patches
• Attachment helpers — list / read turn attachments

Write tools (gated)

Approval cards show Accept / Reject. Accept opens the IDE bridge (and copies the patch as clipboard fallback).

Step budget

Default max tool steps: 12 (env CHAT_TOOLS_MAX_STEPS, max 20). When the budget is hit, use Continue to resume with the same context.

8. Security audit and remediation

Structured remediation loop

Scan this / analyzer
    → findings stored (~7 days)
    → amber Scan chips in chat

Ask: “Fix the critical issues”
    → list_findings
    → remediate_finding  → proposalId
    → verify_remediation (in memory) → cleared | regressed
    → Accept → IDE Confirm

MVP finding classes (JS/TS)

Injection, XSS, command injection, path traversal, SSRF, secrets, weak crypto, authz gaps—aligned with what the analyzer already emits. Other languages improve over time; free-hand propose_unified_diff remains available when templates don’t cover a case.

“Fix with Chat”

From analyzer remediations in the product family, Fix with Chat opens Dev Chat with finding context so the agent can jump straight into remediate_finding.

Good prompts

• “Audit the attached auth module for OWASP Top 10 issues; propose minimal diffs.”
• “Fix the critical Scan findings and verify each remediation.”
• “Explain finding X, then propose a production-ready patch only for that path.”

Prefer minimal, validated diffs over large rewrites—the agent is steered that way in the system prompt.

9. Accepting patches (IDE bridge)

Happy path (recommended)

1. Tool card shows Needs approval.
2. Click Accept.
3. Browser opens vscode:// / cursor://…/apply-patch?proposalId=… and also copies the full patch to the clipboard.
4. Extension fetches /api/llm/proposals/:id with your API key.
5. Native diff preview opens for the first file.
6. Confirm Apply → WorkspaceEdit updates your workspace.
7. Review in Source Control and commit.

Fallback (clipboard)

If the deep link doesn’t open the IDE:

1. Accept still copies the patch.
2. Command Palette → Jokalala: Apply Patch from Clipboard.
3. Choose Apply to workspace (WorkspaceEdit) (or open / git apply / insert at cursor).

Requirements

• Extension installed and activated (onUri for deep links).
• Valid API key for the same user who created the proposal in chat.
• Correct jokalala.apiEndpoint (HTTPS in production; localhost HTTP allowed for local Next.js).
• A folder workspace open in the IDE.

Optional local verify

Settings jokalala.ideBridge.localVerify + jokalala.shellTools.enabled offer an allowlisted verify command (e.g. pnpm test / pnpm lint) after a successful apply. On failure, choose Send to Chat — the extension posts stderr to Redis and opens /ai/chat?verifyFeedback=<id> with the revise prompt prefilled (clipboard fallback if the API fails).

10. Keeping the snapshot fresh

After Accept or local edits, the Redis snapshot can go stale.

Delta sync skips node_modules, .git, .next, dist, binaries, and oversized files. New paths can be added until the file cap is reached.

11. Web Search and CVE context

Search fails open: if keys are missing or the provider errors, the model still answers from training data / attached code. Details: WEB_SEARCH.md.

12. Innovations UX (intent, branches, more)

These ship behind EnhancedChatWrapper (on unless NEXT_PUBLIC_ENABLE_CHAT_INNOVATIONS=false):

Full walkthrough: AI_INNOVATIONS_USER_GUIDE.md.

Also available in the sidebar: folders, tags, global search (⌘K), saved / team prompts, share (public or private email ACL).

13. Providers, BYOK, and racing

• Auto routes across configured providers (OpenAI, DeepSeek, Claude, Gemini, …).
• BYOK in chat settings: browser-supplied keys for the request only—not stored server-side.
• Ollama for local models when configured.
• Racing (NEXT_PUBLIC_AI_RACING=true): race providers on Auto; disabled while Tools is on so the tool loop stays coherent.

14. Shell proposals (opt-in)

Cloud run_command never executes on the server. When CHAT_SHELL_TOOLS_ENABLED=true and the extension has jokalala.shellTools.enabled:

1. Agent proposes a command → Needs approval.
2. Accept copies a JSON payload (or use Jokalala: Run Approved Command).
3. Extension validates against allowlist / deny patterns → Confirm → terminal.

Keep this off unless you need it. Prefer local verify after patch apply for most workflows.

15. Keyboard shortcuts

16. Recommended workflows

A. First-time security pass on a small service

1. Zip src/ (exclude node_modules).
2. Project → Tools on.
3. “Map the auth and input boundaries, then list likely OWASP issues with file:line.”
4. “Propose minimal patches for critical and high only.”
5. Accept → IDE Apply → run tests locally → commit.

B. Analyzer → fix loop

1. Attach vulnerable file(s) → Scan this.
2. “Fix the critical Scan findings and verify remediations.”
3. Confirm verify_remediation reports cleared.
4. Accept each proposal; enable delta sync if you continue chatting.

C. Explain-then-patch

1. “Explain how session tokens are validated in the snapshot.” (browse tools)
2. “Propose a diff that enforces constant-time compare on the secret path only.”
3. Review the proposal carefully before Accept.

D. Grounded research

1. Turn on Search.
2. “Summarize current guidance for fixing CWE-89 in Node/pg with citations.”
3. Apply guidance to your files with Tools on and a snapshot attached.

17. Limits and practical tips

18. Troubleshooting

19. FAQ

Does the agent see my whole machine?
No. Only the indexed snapshot, turn attachments, and what you explicitly sync via delta.

Can it delete files?
Cloud: no. Extension apply currently does not support delete hunks in the WorkspaceEdit path.

Is Accept irreversible?
No. Changes land as normal editor/git edits. Revert with undo or git checkout / restore.

Why clipboard and deep link?
Deep link is the fast path; clipboard keeps you unblocked if the OS blocks custom URIs.

Do I need Redis?
Production deployments use Redis for snapshots, proposals, findings, and memory. Without it, features fail open or use short-lived fallbacks—dogfood with a working Redis for reliable multi-turn agency.

Freemium vs /ai/chat?
Full Enhanced Agent workflows (tools + snapshot + gated Accept) are aimed at authenticated /ai/chat. Freemium is a lighter entry path.

20. Glossary

Appendix A — Operator checklist (admins)

CHAT_TOOLS_ENABLED="true"
NEXT_PUBLIC_CHAT_TOOLS="true"
CHAT_TOOLS_MAX_STEPS="12"
CHAT_CODE_RAG_ENABLED="true"
NEXT_PUBLIC_CHAT_CODE_RAG="true"
# CHAT_WRITE_TOOLS_ENABLED="false"   # only to disable gated patches
# CHAT_SHELL_TOOLS_ENABLED="true"    # optional
# REMEDIATION_ENGINE_ENABLED="false" # opt-out structured remediations
WEB_SEARCH_ENABLED="true"            # optional
CVE_ENABLED="true"                   # optional

Extension (user settings):

• jokalala.apiEndpoint
• API key via Jokalala: Set API Key
• jokalala.ideBridge.deltaSync (opt-in)
• jokalala.ideBridge.localVerify (opt-in)
• jokalala.shellTools.enabled (opt-in)

Smoke: pnpm dogfood:ide-bridge (see DOGFOOD.md).

Appendix B — Document map