openwebui-extensions: Instructions file for Kiro

Antigravity Development Mode

High-speed delivery + strict reversibility. Every decision must keep both roll-forward and rollback feasible.

---

Core Principles

1. Small, isolated edits — one logical change per operation; no mixing refactor + feature.
2. Deterministic interfaces — function signatures and return shapes must not change without an explicit contract update.
3. Multi-level fallback — every I/O path has a degraded alternative (e.g., S3 → local → DB).
4. Reversible by default — every file write, API call, or schema change must have an undo path recorded or be idempotent.

---

Mandatory Safety Patterns

1. Timeout Guards on All Frontend Calls

Any __event_call__ or __event_emitter__ JS execution MUST be wrapped:

import asyncio

try:
    result = await asyncio.wait_for(
        __event_call__({"type": "execute", "data": {"code": js_code}}),
        timeout=2.0
    )
except asyncio.TimeoutError:
    logger.warning("Frontend JS execution timed out; falling back.")
    result = fallback_value
except Exception as e:
    logger.error(f"Frontend call failed: {e}", exc_info=True)
    result = fallback_value

JS side must also guard internally:

try {
    return (localStorage.getItem('locale') || navigator.language || 'en-US');
} catch (e) {
    return 'en-US';
}

2. Path Sandbox Validation

Resolve every workspace path and verify it stays inside the repo root:

import os

def _validate_workspace_path(path: str, workspace_root: str) -> str:
    resolved = os.path.realpath(os.path.abspath(path))
    root = os.path.realpath(workspace_root)
    if not resolved.startswith(root + os.sep) and resolved != root:
        raise PermissionError(f"Path escape detected: {resolved} is outside {root}")
    return resolved

3. Dual-Channel Upload Fallback

Always try API first; fall back to DB/local on failure:

async def _upload_file(self, filename: str, content: bytes) -> str:
    # Channel 1: API upload (S3-compatible)
    try:
        url = await self._api_upload(filename, content)
        if url:
            return url
    except Exception as e:
        logger.warning(f"API upload failed: {e}; falling back to local.")

    # Channel 2: Local file + DB registration
    return await self._local_db_upload(filename, content)