portal-mojo 0.1.0

package/package.json

@@ -0,0 +1,55 @@
+{
+    "name": "portal-mojo",
+    "version": "0.1.0",
+    "description": "React portal toolkit for django-mojo — typed client + params store, mission-control UI, dependency-free SVG charts, admin section bundles.",
+    "type": "module",
+    "license": "Apache-2.0",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/NativeMojo/portal-mojo.git",
+        "directory": "packages/portal-mojo"
+    },
+    "homepage": "https://github.com/NativeMojo/portal-mojo#readme",
+    "bugs": {
+        "url": "https://github.com/NativeMojo/portal-mojo/issues"
+    },
+    "files": [
+        "src",
+        "docs",
+        "README.md",
+        "LICENSE"
+    ],
+    "publishConfig": {
+        "access": "public",
+        "registry": "https://registry.npmjs.org/",
+        "provenance": true
+    },
+    "exports": {
+        "./client": "./src/client/index.ts",
+        "./ui": "./src/ui/index.ts",
+        "./charts": "./src/charts/index.ts",
+        "./admin": "./src/admin/index.ts"
+    },
+    "scripts": {
+        "typecheck": "tsc --noEmit"
+    },
+    "dependencies": {
+        "zod": "^4.4.3"
+    },
+    "peerDependencies": {
+        "@tanstack/react-query": "^5",
+        "react": "^19",
+        "react-dom": "^19",
+        "react-router-dom": "^7"
+    },
+    "devDependencies": {
+        "@tanstack/react-query": "^5.62.0",
+        "@types/react": "^19.2.7",
+        "@types/react-dom": "^19.2.3",
+        "react": "^19.2.0",
+        "react-dom": "^19.2.0",
+        "react-router-dom": "^7.6.1",
+        "typescript": "~5.9.3",
+        "vite": "^7.1.0"
+    }
+}

package/src/admin/assistant/AssistantFeed.tsx

@@ -0,0 +1,29 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import type { FileReference, RecordFeedItem } from '../../client/record-feed';
+import { AttachmentQueue, RecordFeed, fmt, modal, type AttachmentQueueState } from '../../ui';
+import { isSafeCapabilityUrl, openCapabilityUrl } from '../storage/models';
+import type { AssistantBlock, AssistantMessage, AssistantUser } from './types';
+
+function BlockView({ block, onAction, disabled }: { block: AssistantBlock; onAction(value: string): Promise<void>; disabled: boolean }) {
+    if (block.type === 'table') return <section className="assistant-block"><h4>{block.title ?? 'Results'}</h4><div className="assistant-table-scroll"><table><thead><tr>{block.columns.map((column) => <th key={column}>{column}</th>)}</tr></thead><tbody>{block.rows.map((row, index) => <tr key={index}>{row.map((cell, cellIndex) => <td key={cellIndex}>{String(cell ?? '—')}</td>)}</tr>)}</tbody></table></div></section>;
+    if (block.type === 'chart') return <section className="assistant-block"><h4>{block.title ?? 'Chart data'}</h4><div className="assistant-chart" role="img" aria-label={`${block.chart_type} chart: ${block.title ?? 'Assistant chart'}`}>{block.labels.map((label, index) => <div key={`${label}:${index}`}><strong>{label}</strong>{block.series.map((series) => <span key={series.name}>{series.name}: {series.values[index]}</span>)}</div>)}</div></section>;
+    if (block.type === 'stat' || block.type === 'list') return <section className={`assistant-block assistant-${block.type}`}><h4>{block.title ?? (block.type === 'stat' ? 'Summary' : 'Details')}</h4><dl>{block.items.map((item) => <div key={item.label}><dt>{item.label}</dt><dd>{String(item.value ?? '—')}</dd></div>)}</dl></section>;
+    if (block.type === 'alert') return <section className={`assistant-block assistant-alert assistant-alert-${block.level}`} role={block.level === 'error' ? 'alert' : undefined}><strong>{block.title ?? block.level}</strong><p>{block.message}</p></section>;
+    if (block.type === 'file') return <section className="assistant-block assistant-file"><i className="bi bi-file-earmark-arrow-down" aria-hidden="true" /><span><strong>{block.filename}</strong><small>{[block.format, block.size != null ? fmt.filesize(block.size) : null, block.row_count != null ? `${block.row_count} rows` : null, block.expires_in].filter(Boolean).join(' · ')}</small></span>{isSafeCapabilityUrl(block.url) ? <button type="button" className="btn btn-compact" onClick={() => openCapabilityUrl(block.url, true)}>Download</button> : <span className="storage-unsafe">Unsafe URL withheld</span>}</section>;
+    if (block.type === 'attachment') return <section className="assistant-block assistant-attachments" aria-label="Message attachments">{block.files.map((file) => <span className="assistant-attachment-chip" key={file.id}><i className="bi bi-paperclip" aria-hidden="true" /> <strong>{file.filename}</strong><small>{file.content_type}</small></span>)}</section>;
+    if (block.type === 'context') return <section className="assistant-block"><h4>References</h4><ul>{block.references.map((reference) => <li key={`${reference.model}:${reference.pk}`}><code>{reference.model} #{reference.pk}</code>{reference.label ? ` — ${reference.label}` : ''}</li>)}</ul></section>;
+    return <section className="assistant-block assistant-action"><h4>{block.title ?? 'Confirm action'}</h4>{block.description && <p>{block.description}</p>}<div className="assistant-action-row">{block.actions.map((action) => <button key={`${block.action_id ?? block.title}:${action.value}`} type="button" className="btn btn-compact" disabled={disabled} onClick={async () => { const confirmed = await modal.confirm({ title: `${action.label}?`, message: `Send “${action.value}” to the Assistant as your response?`, confirmText: action.label }); if (confirmed) await onAction(action.value); }}>{action.label}</button>)}</div></section>;
+}
+export function AssistantFeed({ messages, user, onSend, responding, disabled = false, attachmentKey = 'new' }: { messages: AssistantMessage[]; user: AssistantUser; onSend(text: string, attachments?: readonly FileReference[]): Promise<void>; responding: boolean; disabled?: boolean; attachmentKey?: number | string }) {
+    const actionFlight = useRef(false);
+    const [actionError, setActionError] = useState('');
+    const [attachmentState, setAttachmentState] = useState<AttachmentQueueState>({ files: [], busy: false });
+    const [attachmentReset, setAttachmentReset] = useState(0);
+    const attachmentChange = useCallback((state: AttachmentQueueState) => setAttachmentState(state), []);
+    useEffect(() => { if (disabled) setAttachmentState({ files: [], busy: false }); }, [disabled]);
+    const items = useMemo<RecordFeedItem[]>(() => messages.map((message) => ({ id: message.id, kind: message.role === 'assistant' ? 'assistant' : 'comment', created: message.created, content: message.content, author: message.role === 'assistant' ? { id: null, name: 'AI Agent' } : { id: user.id, name: user.display_name }, metadata: {}, raw: { blocks: message.blocks } })), [messages, user.id, user.display_name]);
+    const sendAction = async (value: string) => { if (actionFlight.current || responding || disabled) return; actionFlight.current = true; setActionError(''); try { await onSend(value, []); } catch (error) { setActionError(error instanceof Error ? error.message : 'Action response failed'); } finally { actionFlight.current = false; } };
+    const send = async (text: string) => { await onSend(text, attachmentState.files); setAttachmentReset((value) => value + 1); };
+    const composerAddon = disabled ? null : <AttachmentQueue key={`assistant:${user.id}:${attachmentKey}:personal`} consumerKey={`assistant:${user.id}:${attachmentKey}:personal`} capacity={5} destination={{}} expectedGroupId={null} disabled={responding} resetKey={attachmentReset} onChange={attachmentChange} />;
+    return <RecordFeed items={items} onSend={send} isSending={responding} disabled={disabled} submitBlocked={attachmentState.busy} composerAddon={composerAddon} currentUserId={user.id} variant="bubbles" placeholder={disabled ? 'Only the owner can continue this conversation' : 'Message Assistant…'} sendLabel="Send" emptyLabel="Ask the Assistant about this deployment." ariaLabel="Assistant conversation" pending={responding ? <>Responding…</> : null} error={actionError || undefined} renderAddon={(item) => { const blocks = Array.isArray(item.raw.blocks) ? item.raw.blocks as AssistantBlock[] : []; return blocks.length ? <div className="assistant-blocks">{blocks.map((entry, index) => <BlockView key={`${item.id}:${index}`} block={entry} onAction={sendAction} disabled={responding || disabled || actionFlight.current} />)}</div> : null; }} />;
+}

package/src/admin/assistant/AssistantPanel.tsx

@@ -0,0 +1,65 @@
+import { useEffect, useRef, useState } from 'react';
+import { useCan, useMe, useRealtime, useRealtimeStatus } from '../../client';
+import type { RightPanelRenderContext } from '../../ui';
+import { AssistantFeed } from './AssistantFeed';
+import { sendAssistantMessage } from './api';
+import type { AssistantConversation, AssistantMessage } from './types';
+import type { FileReference } from '../../client/record-feed';
+import { AssistantOutcomeUnknownError, chooseAssistantTransport, startAssistantRealtimeTurn, type AssistantRealtimeProgress, type AssistantRealtimeTurn } from './streaming';
+
+export const ASSISTANT_PERMISSIONS = ['sys.view_admin', 'sys.assistant'];
+
+export function AssistantPanel({ context, initialConversation = null }: { context: RightPanelRenderContext; initialConversation?: AssistantConversation | null }) {
+    const { can } = useCan(ASSISTANT_PERMISSIONS);
+    const { can: canViewAdmin } = useCan('sys.view_admin');
+    const { data: me } = useMe();
+    const realtime = useRealtime();
+    const realtimeStatus = useRealtimeStatus();
+    const [conversation, setConversation] = useState(initialConversation);
+    const [messages, setMessages] = useState<AssistantMessage[]>(initialConversation?.messages ?? []);
+    const [responding, setResponding] = useState(false);
+    const [error, setError] = useState('');
+    const [streamProgress, setStreamProgress] = useState<AssistantRealtimeProgress | null>(null);
+    const [streamingActive, setStreamingActive] = useState(false);
+    const flight = useRef(false);
+    const stream = useRef<AssistantRealtimeTurn | null>(null);
+    const seenMessageIds = useRef(new Set<number | string>());
+    useEffect(() => { if (!can) { stream.current?.cancel(); stream.current = null; setStreamProgress(null); setStreamingActive(false); setMessages(conversation?.messages ?? []); context.close(); } }, [can, context, conversation]);
+    useEffect(() => { if (!canViewAdmin && stream.current) { stream.current.cancel(); stream.current = null; setStreamProgress(null); setStreamingActive(false); setMessages(conversation?.messages ?? []); } }, [canViewAdmin, conversation]);
+    useEffect(() => { setConversation(initialConversation); setMessages(initialConversation?.messages ?? []); seenMessageIds.current = new Set(initialConversation?.messages.map((message) => message.id) ?? []); setStreamProgress(null); setError(''); }, [initialConversation?.id]);
+    useEffect(() => () => { stream.current?.cancel(); stream.current = null; }, []);
+    if (!can || !me) return null;
+    const owner = conversation == null || conversation.user.id === me.id;
+    const send = async (text: string, attachments: readonly FileReference[] = []) => {
+        if (flight.current || !owner) return;
+        flight.current = true; setResponding(true); setError('');
+        const temporary: AssistantMessage = { id: `local-${Date.now()}`, role: 'user', content: text, created: Math.floor(Date.now() / 1000), blocks: attachments.length ? [{ type: 'attachment', files: [...attachments] }] : [] };
+        setMessages((current) => [...current, temporary]);
+        try {
+            const transport = chooseAssistantTransport({ owner, textOnly: attachments.length === 0, hasViewAdmin: canViewAdmin, realtimeStatus: realtimeStatus.status });
+            if (transport === 'websocket') {
+                setStreamingActive(true);
+                const turn = startAssistantRealtimeTurn(realtime, { message: text, conversationId: conversation?.id, seenMessageIds: seenMessageIds.current }, {
+                    onConversation: (id) => setConversation((current) => current ?? { id, title: text.slice(0, 80), created: temporary.created, modified: temporary.created, user: { id: me.id, display_name: me.display_name ?? 'You' }, messages: [] }),
+                    onText: (message) => setMessages((current) => [...current, message]),
+                    onProgress: setStreamProgress,
+                    onResponse: (message) => setMessages((current) => current.some((item) => item.id === message.id) ? current : [...current, message]),
+                    onReconcile: (next) => { setConversation(next); setMessages(next.messages); },
+                    onUnknown: () => { window.dispatchEvent(new CustomEvent('portal-mojo:assistant-list-refresh')); },
+                });
+                stream.current = turn;
+                await turn.promise;
+                stream.current = null;
+            } else {
+                const reply = await sendAssistantMessage(text, conversation?.id, attachments);
+                const assistant: AssistantMessage = { id: `local-assistant-${Date.now()}`, role: 'assistant', content: reply.response, created: Math.floor(Date.now() / 1000), blocks: reply.blocks };
+                setMessages((current) => [...current, assistant]);
+                setConversation((current) => current ?? { id: reply.conversation_id, title: text.slice(0, 80), created: temporary.created, modified: assistant.created, user: { id: me.id, display_name: me.display_name ?? 'You' }, messages: [] });
+            }
+        } catch (cause) {
+            if (!(cause instanceof AssistantOutcomeUnknownError)) setMessages((current) => current.filter((message) => message.id !== temporary.id));
+            const message = cause instanceof Error ? cause.message : 'Assistant request failed'; setError(message); throw cause;
+        } finally { stream.current = null; setStreamProgress(null); setStreamingActive(false); flight.current = false; setResponding(false); }
+    };
+    return <div className="assistant-panel"><div className="assistant-panel-meta"><span>{conversation ? conversation.title : 'New conversation'}</span>{conversation && !owner && <span className="chip chip-muted">Inspect only</span>}{responding && <span>{streamingActive ? streamProgress?.tools.length ? `${streamProgress.tools.reduce((sum, tool) => sum + tool.count, 0)} tool call${streamProgress.tools.reduce((sum, tool) => sum + tool.count, 0) === 1 ? '' : 's'}` : realtimeStatus.status === 'ready' ? 'Streaming…' : 'Reconciling…' : 'Responding…'}</span>}</div>{streamProgress?.tools.length ? <div className="assistant-stream-tools" aria-label="Assistant tool progress">{streamProgress.tools.map((tool) => <span className="chip chip-muted" key={tool.name}>{tool.name} · {tool.status}{tool.count > 1 ? ` ×${tool.count}` : ''}</span>)}</div> : null}{error && <div className="form-alert" role="alert">{error}</div>}<AssistantFeed messages={messages} user={{ id: me.id, display_name: me.display_name ?? 'You' }} onSend={send} responding={responding} disabled={!owner} attachmentKey={conversation?.id ?? 'new'} /></div>;
+}

package/src/admin/assistant/api.ts

@@ -0,0 +1,17 @@
+import { mojoCall, mojoDelete, mojoList, type Params } from '../../client';
+import { projectConversation, projectConversationSummary, projectReply, projectSkill } from './data';
+import type { AssistantConversation, AssistantConversationSummary, AssistantReply, AssistantSkill } from './types';
+import type { FileReference } from '../../client/record-feed';
+
+const malformed = (label: string): never => { throw new Error(`${label} returned an invalid response`); };
+export async function sendAssistantMessage(message: string, conversationId?: number, attachments: readonly FileReference[] = []): Promise<AssistantReply> { const ids = attachments.map((file) => file.id); if (ids.length > 5 || new Set(ids).size !== ids.length || ids.some((id) => !Number.isSafeInteger(id) || id <= 0)) throw new Error('Assistant attachments must be 1–5 unique completed File references'); const body = await mojoCall('/api/assistant', { method: 'POST', body: { message, ...(conversationId != null ? { conversation_id: conversationId } : {}), ...(ids.length ? { attachments: ids } : {}) } }); return projectReply(body.data) ?? malformed('Assistant'); }
+export async function createAssistantContext(model: 'incident.Incident' | 'incident.Ticket', pk: number): Promise<AssistantConversation> { const body = await mojoCall('/api/assistant/context', { method: 'POST', body: { model, pk } }); const data = body.data as Record<string, unknown> | undefined; const id = typeof data?.conversation_id === 'number' ? data.conversation_id : null; if (id == null) return malformed('Assistant context'); return getAssistantConversation(id); }
+export async function getAssistantConversation(id: number): Promise<AssistantConversation> { const body = await mojoCall(`/api/assistant/conversation/${id}`, { params: { graph: 'detail' } }); return projectConversation(body.data) ?? malformed('Conversation'); }
+export async function listAssistantConversations(params: Params = {}): Promise<{ rows: AssistantConversationSummary[]; count: number }> { const page = await mojoList<unknown>('/api/assistant/conversation', { start: 0, size: 100, sort: '-modified', ...params }); return { rows: page.rows.map(projectConversationSummary).filter((v): v is AssistantConversationSummary => v != null), count: page.count }; }
+export const deleteAssistantConversation = (id: number): Promise<void> => mojoDelete('/api/assistant/conversation', id);
+export async function getAssistantSkill(id: number): Promise<AssistantSkill> { const body = await mojoCall(`/api/assistant/skill/${id}`, { params: { graph: 'detail' } }); return projectSkill(body.data) ?? malformed('Skill'); }
+export async function listAssistantSkills(params: Params = {}): Promise<{ rows: AssistantSkill[]; count: number }> { const page = await mojoList<unknown>('/api/assistant/skill', { start: 0, size: 100, sort: 'name', ...params }); return { rows: page.rows.map(projectSkill).filter((v): v is AssistantSkill => v != null), count: page.count }; }
+export const deleteAssistantSkill = (id: number): Promise<void> => mojoDelete('/api/assistant/skill', id);
+export async function getAssistantMemory(tier: 'global' | 'user' | 'group', group?: number): Promise<Record<string, unknown>> { const body = await mojoCall(`/api/assistant/memory/${tier}`, { params: group == null ? {} : { group } }); return body.data && typeof body.data === 'object' && !Array.isArray(body.data) ? body.data as Record<string, unknown> : {}; }
+export async function saveAssistantMemory(tier: 'global' | 'user' | 'group', key: string, value: string, group?: number): Promise<void> { await mojoCall(`/api/assistant/memory/${tier}`, { method: 'POST', params: group == null ? {} : { group }, body: { key, value } }); }
+export async function deleteAssistantMemory(tier: 'global' | 'user' | 'group', key: string, group?: number): Promise<void> { await mojoCall(`/api/assistant/memory/${tier}/${encodeURIComponent(key)}`, { method: 'DELETE', params: group == null ? {} : { group } }); }

package/src/admin/assistant/data.ts

@@ -0,0 +1,63 @@
+import type { AssistantBlock, AssistantConversation, AssistantConversationSummary, AssistantMessage, AssistantReply, AssistantScalar, AssistantSkill, AssistantUser } from './types';
+import { safeFileReference } from '../../client/record-feed';
+
+const MAX_BLOCKS = 8;
+const MAX_TEXT = 4_000;
+const MAX_ITEMS = 24;
+const MAX_COLUMNS = 12;
+const MAX_ROWS = 50;
+const obj = (value: unknown): Record<string, unknown> | null => value != null && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : null;
+const text = (value: unknown, cap = MAX_TEXT): string => typeof value === 'string' ? value.slice(0, cap) : '';
+const id = (value: unknown): number | string | null => typeof value === 'number' || typeof value === 'string' ? value : null;
+const number = (value: unknown): number | null => typeof value === 'number' && Number.isFinite(value) ? value : null;
+const scalar = (value: unknown): AssistantScalar | null => value === null || typeof value === 'boolean' || (typeof value === 'number' && Number.isFinite(value)) ? value : typeof value === 'string' ? value.slice(0, 500) : null;
+
+function pairItems(value: unknown): Array<{ label: string; value: AssistantScalar }> | null {
+    if (!Array.isArray(value) || value.length === 0 || value.length > MAX_ITEMS) return null;
+    const out = value.map(obj).map((item) => item && text(item.label, 120) && scalar(item.value) !== null ? { label: text(item.label, 120), value: scalar(item.value)! } : null);
+    return out.every(Boolean) ? out as Array<{ label: string; value: AssistantScalar }> : null;
+}
+
+function block(value: unknown, allowAttachment = false): AssistantBlock | null {
+    const raw = obj(value); if (!raw || typeof raw.type !== 'string') return null;
+    const title = text(raw.title, 200) || undefined;
+    if (raw.type === 'table') {
+        if (!Array.isArray(raw.columns) || !Array.isArray(raw.rows) || raw.columns.length === 0 || raw.columns.length > MAX_COLUMNS || raw.rows.length > MAX_ROWS) return null;
+        const columns = raw.columns.map((v) => text(v, 120)); if (columns.some((v) => !v)) return null;
+        const rows = raw.rows.map((row) => Array.isArray(row) && row.length === columns.length ? row.map(scalar) : null);
+        if (rows.some((row) => !row || row.some((v) => v === null))) return null;
+        return { type: 'table', title, columns, rows: rows as AssistantScalar[][] };
+    }
+    if (raw.type === 'chart') {
+        if (!['line', 'bar', 'pie', 'area'].includes(String(raw.chart_type)) || !Array.isArray(raw.labels) || raw.labels.length === 0 || raw.labels.length > MAX_ROWS || !Array.isArray(raw.series) || raw.series.length === 0 || raw.series.length > 8) return null;
+        const labels = raw.labels.map((v) => text(v, 80));
+        const series = raw.series.map(obj).map((s) => s && text(s.name, 80) && Array.isArray(s.values) && s.values.length === labels.length && s.values.every((v) => number(v) !== null) ? { name: text(s.name, 80), values: s.values as number[] } : null);
+        if (labels.some((v) => !v) || series.some((v) => !v)) return null;
+        return { type: 'chart', title, chart_type: raw.chart_type as 'line' | 'bar' | 'pie' | 'area', labels, series: series as Array<{ name: string; values: number[] }> };
+    }
+    if (raw.type === 'stat' || raw.type === 'list') { const items = pairItems(raw.items); return items ? { type: raw.type, title, items } : null; }
+    if (raw.type === 'action') {
+        if (!Array.isArray(raw.actions) || raw.actions.length === 0 || raw.actions.length > 6) return null;
+        const actions = raw.actions.map(obj).map((a) => a && text(a.label, 80) && text(a.value, 200) ? { label: text(a.label, 80), value: text(a.value, 200) } : null);
+        return actions.every(Boolean) ? { type: 'action', title, description: text(raw.description, 500) || undefined, action_id: text(raw.action_id, 120) || undefined, actions: actions as Array<{ label: string; value: string }> } : null;
+    }
+    if (raw.type === 'alert' && ['info', 'success', 'warning', 'error'].includes(String(raw.level)) && text(raw.message)) return { type: 'alert', level: raw.level as 'info' | 'success' | 'warning' | 'error', title, message: text(raw.message) };
+    if (raw.type === 'file' && text(raw.filename, 255) && text(raw.url, 2_000)) return { type: 'file', filename: text(raw.filename, 255), url: text(raw.url, 2_000), ...(number(raw.size) != null ? { size: number(raw.size)! } : {}), ...(text(raw.format, 32) ? { format: text(raw.format, 32) } : {}), ...(number(raw.row_count) != null ? { row_count: number(raw.row_count)! } : {}), ...(text(raw.expires_in, 80) ? { expires_in: text(raw.expires_in, 80) } : {}) };
+    if (allowAttachment && raw.type === 'attachment' && Array.isArray(raw.files)) {
+        const files = raw.files.slice(0, 5).map(safeFileReference).filter((file): file is NonNullable<typeof file> => file != null);
+        if (files.length && new Set(files.map((file) => file.id)).size === files.length) return { type: 'attachment', files };
+    }
+    if (raw.type === 'context' && Array.isArray(raw.references) && raw.references.length > 0 && raw.references.length <= MAX_ITEMS) {
+        const references = raw.references.map(obj).map((r) => r && (r.model === 'incident.Incident' || r.model === 'incident.Ticket') && id(r.pk) != null ? { model: r.model, pk: id(r.pk)!, ...(text(r.label, 160) ? { label: text(r.label, 160) } : {}) } : null);
+        return references.every(Boolean) ? { type: 'context', references: references as Array<{ model: 'incident.Incident' | 'incident.Ticket'; pk: number | string; label?: string }> } : null;
+    }
+    return null;
+}
+
+export function projectBlocks(value: unknown, allowAttachment = false): AssistantBlock[] { return Array.isArray(value) ? value.slice(0, MAX_BLOCKS).map((entry) => block(entry, allowAttachment)).filter((v): v is AssistantBlock => v != null) : []; }
+function projectUser(value: unknown): AssistantUser | null { const raw = obj(value); const userId = raw && number(raw.id); return raw && userId != null ? { id: userId, display_name: text(raw.display_name, 160) || `User #${userId}` } : null; }
+export function projectMessage(value: unknown): AssistantMessage | null { const raw = obj(value); const messageId = raw && id(raw.id); if (!raw || messageId == null || (raw.role !== 'user' && raw.role !== 'assistant')) return null; const blocks = projectBlocks(raw.blocks, raw.role === 'user'); return { id: messageId, role: raw.role, content: text(raw.content, 20_000), created: typeof raw.created === 'number' || typeof raw.created === 'string' ? raw.created : 0, blocks: raw.role === 'user' ? blocks.filter((entry) => entry.type === 'attachment') : blocks }; }
+export function projectConversation(value: unknown): AssistantConversation | null { const raw = obj(value); const conversationId = raw && number(raw.id); const user = raw && projectUser(raw.user); if (!raw || conversationId == null || !user) return null; return { id: conversationId, title: text(raw.title, 255) || `Conversation #${conversationId}`, created: typeof raw.created === 'number' || typeof raw.created === 'string' ? raw.created : 0, modified: typeof raw.modified === 'number' || typeof raw.modified === 'string' ? raw.modified : 0, user, messages: Array.isArray(raw.messages) ? raw.messages.map(projectMessage).filter((v): v is AssistantMessage => v != null) : [] }; }
+export function projectConversationSummary(value: unknown): AssistantConversationSummary | null { const conversation = projectConversation(value); if (!conversation) return null; const { messages: _messages, ...summary } = conversation; return summary; }
+export function projectSkill(value: unknown): AssistantSkill | null { const raw = obj(value); const skillId = raw && number(raw.id); if (!raw || skillId == null || !['global', 'user', 'group'].includes(String(raw.tier))) return null; const steps = Array.isArray(raw.steps) ? raw.steps.slice(0, MAX_ITEMS).map(obj).map((step) => step && text(step.tool, 160) && text(step.description, 500) ? { tool: text(step.tool, 160), description: text(step.description, 500), ...(text(step.condition, 500) ? { condition: text(step.condition, 500) } : {}) } : null).filter((step): step is { tool: string; description: string; condition?: string } => step != null) : []; return { id: skillId, tier: raw.tier as 'global' | 'user' | 'group', name: text(raw.name, 160) || `Skill #${skillId}`, description: text(raw.description, 2_000), auto_execute: raw.auto_execute === true, is_active: raw.is_active === true, created: typeof raw.created === 'number' || typeof raw.created === 'string' ? raw.created : 0, modified: typeof raw.modified === 'number' || typeof raw.modified === 'string' ? raw.modified : 0, user: projectUser(raw.user), triggers: Array.isArray(raw.triggers) ? raw.triggers.slice(0, 10).map((v) => text(v, 200)).filter(Boolean) : [], steps }; }
+export function projectReply(value: unknown): AssistantReply | null { const raw = obj(value); const conversationId = raw && number(raw.conversation_id); if (!raw || conversationId == null || typeof raw.response !== 'string') return null; const toolCount = Array.isArray(raw.tool_calls_made) ? Math.min(raw.tool_calls_made.length, 32) : Math.min(Math.max(0, number(raw.tool_calls_made) ?? 0), 32); return { response: text(raw.response, 20_000), conversation_id: conversationId, tool_calls_made: toolCount, duration_ms: number(raw.duration_ms) ?? 0, blocks: projectBlocks(raw.blocks) }; }

package/src/admin/assistant/index.ts

@@ -0,0 +1,21 @@
+import type { AdminSection } from '../index';
+import { ASSISTANT_PERMISSIONS } from './AssistantPanel';
+import { ConversationsPage, MemoriesPage, SkillsPage } from './pages';
+
+export * from './types';
+export * from './data';
+export * from './api';
+export * from './AssistantFeed';
+export * from './AssistantPanel';
+export * from './launchers';
+export * from './pages';
+export * from './streaming';
+
+export const ASSISTANT_ADMIN_SECTION: AdminSection = {
+    id: 'assistant', basePath: 'assistant', title: 'Assistant', icon: 'bi-stars', navigationGroup: 'assistant', permissions: ASSISTANT_PERMISSIONS,
+    routes: [
+        { path: 'conversations', label: 'Conversations', component: ConversationsPage, permissions: ASSISTANT_PERMISSIONS },
+        { path: 'skills', label: 'Skills', component: SkillsPage, permissions: ASSISTANT_PERMISSIONS },
+        { path: 'memories', label: 'Memory', component: MemoriesPage, permissions: ['sys.assistant'] },
+    ],
+};

package/src/admin/assistant/launchers.tsx

@@ -0,0 +1,33 @@
+import { useEffect, useRef, useState, type MouseEvent } from 'react';
+import { useCan } from '../../client';
+import { useRightPanel } from '../../ui';
+import { SECURITY_VIEW_PERMS } from '../security-permissions';
+import { AssistantPanel, ASSISTANT_PERMISSIONS } from './AssistantPanel';
+import { createAssistantContext } from './api';
+
+export function AssistantLauncher() {
+    const { can } = useCan(ASSISTANT_PERMISSIONS);
+    const panel = useRightPanel();
+    useEffect(() => { if (!can && panel.descriptor?.key.startsWith('assistant:')) panel.close(); }, [can, panel]);
+    if (!can) return null;
+    return <button type="button" className="btn-icon" title="Open Assistant" aria-label="Open Assistant" aria-pressed={panel.descriptor?.key === 'assistant:new'} onClick={(event) => panel.open({ key: 'assistant:new', title: 'Assistant', render: (context) => <AssistantPanel context={context} /> }, event.currentTarget)}><i className="bi bi-stars" aria-hidden="true" /></button>;
+}
+
+export function AssistantContextLauncher({ model, pk, label = 'Ask Assistant' }: { model: 'incident.Incident' | 'incident.Ticket'; pk: number; label?: string }) {
+    const assistant = useCan(ASSISTANT_PERMISSIONS);
+    const security = useCan(SECURITY_VIEW_PERMS);
+    const panel = useRightPanel();
+    const generation = useRef(0);
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState('');
+    useEffect(() => () => { generation.current += 1; }, []);
+    useEffect(() => { generation.current += 1; setLoading(false); setError(''); }, [model, pk]);
+    if (!assistant.can || !security.can) return null;
+    const launch = async (event: MouseEvent<HTMLButtonElement>) => {
+        const launcher = event.currentTarget; const run = ++generation.current; setLoading(true); setError('');
+        try { const conversation = await createAssistantContext(model, pk); if (generation.current !== run) return; panel.open({ key: `assistant:context:${model}:${pk}:${conversation.id}`, title: `Assistant · ${model === 'incident.Incident' ? 'Incident' : 'Ticket'} #${pk}`, render: (context) => <AssistantPanel context={context} initialConversation={conversation} /> }, launcher); }
+        catch (cause) { if (generation.current === run) setError(cause instanceof Error ? cause.message : 'Could not create context'); }
+        finally { if (generation.current === run) setLoading(false); }
+    };
+    return <span className="assistant-context-launcher"><button type="button" className="btn btn-compact" disabled={loading} onClick={(event) => void launch(event)}><i className="bi bi-stars" aria-hidden="true" /> {loading ? 'Opening…' : label}</button>{error && <span className="text-bad" role="alert">{error}</span>}</span>;
+}

package/src/admin/assistant/pages.tsx

@@ -0,0 +1,78 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { mojoList, useCan, useMe, useRealtime, useRealtimeStatus } from '../../client';
+import { Badge, fmt, modal, toast } from '../../ui';
+import { AssistantFeed } from './AssistantFeed';
+import { deleteAssistantConversation, deleteAssistantMemory, deleteAssistantSkill, getAssistantConversation, getAssistantMemory, getAssistantSkill, listAssistantConversations, listAssistantSkills, saveAssistantMemory, sendAssistantMessage } from './api';
+import type { AssistantConversation, AssistantConversationSummary, AssistantSkill } from './types';
+import type { FileReference } from '../../client/record-feed';
+import { ASSISTANT_PERMISSIONS } from './AssistantPanel';
+import { AssistantOutcomeUnknownError, chooseAssistantTransport, startAssistantRealtimeTurn, type AssistantRealtimeTurn } from './streaming';
+
+function PageState({ loading, error, retry }: { loading: boolean; error: string; retry(): void }) { if (loading) return <div className="panel panel-pad dim">Loading…</div>; if (error) return <div className="panel panel-pad"><div className="form-alert" role="alert">{error}</div><button type="button" className="btn" onClick={retry}>Retry</button></div>; return null; }
+function Heading({ eyebrow, title, description }: { eyebrow: string; title: string; description: string }) { return <header className="admin-page-heading"><div><div className="eyebrow">{eyebrow}</div><h1>{title}</h1><p>{description}</p></div></header>; }
+
+function ConversationInspect({ id, close }: { id: number; close(): void }) {
+    const { data: me } = useMe(); const { can: canAssistant } = useCan(ASSISTANT_PERMISSIONS); const { can: canViewAdmin } = useCan('sys.view_admin');
+    const realtime = useRealtime(); const realtimeStatus = useRealtimeStatus();
+    const [data, setData] = useState<AssistantConversation | null>(null); const [loading, setLoading] = useState(true); const [responding, setResponding] = useState(false); const [error, setError] = useState('');
+    const stream = useRef<AssistantRealtimeTurn | null>(null); const seenMessageIds = useRef(new Set<number | string>());
+    const load = useCallback(async () => { setLoading(true); setError(''); try { const next = await getAssistantConversation(id); seenMessageIds.current = new Set(next.messages.map((message) => message.id)); setData(next); } catch (cause) { setError(cause instanceof Error ? cause.message : 'Conversation unavailable'); } finally { setLoading(false); } }, [id]);
+    useEffect(() => { void load(); }, [load]);
+    useEffect(() => () => { stream.current?.cancel(); stream.current = null; }, []);
+    useEffect(() => { if (!canAssistant) { stream.current?.cancel(); stream.current = null; setResponding(false); close(); } }, [canAssistant, close]);
+    useEffect(() => { if (!canViewAdmin && stream.current) { stream.current.cancel(); stream.current = null; setResponding(false); void load(); } }, [canViewAdmin, load]);
+    if (loading || error || !data || !me) return <div className="modal-pad"><PageState loading={loading} error={error || (!data ? 'Conversation unavailable' : '')} retry={() => void load()} /><button type="button" className="btn" onClick={close}>Close</button></div>;
+    const owner = data.user.id === me.id;
+    const send = async (message: string, attachments: readonly FileReference[] = []) => {
+        if (!owner || responding) return;
+        setResponding(true); const now = Math.floor(Date.now() / 1000);
+        const userMessage = { id: `inspect-user-${Date.now()}`, role: 'user' as const, content: message, created: now, blocks: attachments.length ? [{ type: 'attachment' as const, files: [...attachments] }] : [] };
+        setData((current) => current ? { ...current, messages: [...current.messages, userMessage] } : current);
+        try {
+            const transport = chooseAssistantTransport({ owner, textOnly: attachments.length === 0, hasViewAdmin: canViewAdmin, realtimeStatus: realtimeStatus.status });
+            if (transport === 'websocket') {
+                const turn = startAssistantRealtimeTurn(realtime, { message, conversationId: data.id, seenMessageIds: seenMessageIds.current }, {
+                    onConversation: () => {},
+                    onText: (next) => setData((current) => current ? { ...current, messages: [...current.messages, next] } : current),
+                    onProgress: () => {},
+                    onResponse: (next) => setData((current) => current ? { ...current, modified: now, messages: current.messages.some((item) => item.id === next.id) ? current.messages : [...current.messages, next] } : current),
+                    onReconcile: setData,
+                    onUnknown: () => { window.dispatchEvent(new CustomEvent('portal-mojo:assistant-list-refresh')); },
+                });
+                stream.current = turn; await turn.promise; stream.current = null;
+            } else {
+                const reply = await sendAssistantMessage(message, data.id, attachments);
+                setData((current) => current ? { ...current, modified: now, messages: [...current.messages, { id: `inspect-assistant-${Date.now()}`, role: 'assistant', content: reply.response, created: now, blocks: reply.blocks }] } : current);
+            }
+        } catch (cause) {
+            if (!(cause instanceof AssistantOutcomeUnknownError)) setData((current) => current ? { ...current, messages: current.messages.filter((item) => item.id !== userMessage.id) } : current);
+            throw cause;
+        } finally { stream.current = null; setResponding(false); }
+    };
+    return <div className="modal-pad assistant-inspect"><header><div><div className="eyebrow">Conversation #{data.id}</div><h2>{data.title}</h2><p className="dim">Owner: {data.user.display_name} · updated {fmt.datetime(data.modified)}</p></div><button className="btn-icon" type="button" onClick={close} aria-label="Close"><i className="bi bi-x-lg" /></button></header><AssistantFeed messages={data.messages} user={{ id: me.id, display_name: me.display_name ?? 'You' }} onSend={send} responding={responding} disabled={!owner} attachmentKey={data.id} /></div>;
+}
+
+export function ConversationsPage() {
+    const { data: me } = useMe(); const { can: isAdmin } = useCan('sys.view_admin'); const [rows, setRows] = useState<AssistantConversationSummary[]>([]); const [loading, setLoading] = useState(true); const [error, setError] = useState('');
+    const load = useCallback(async () => { setLoading(true); setError(''); try { setRows((await listAssistantConversations()).rows); } catch (cause) { setError(cause instanceof Error ? cause.message : 'Conversations unavailable'); } finally { setLoading(false); } }, []);
+    useEffect(() => { void load(); }, [load]);
+    useEffect(() => { const refresh = () => { void load(); }; window.addEventListener('portal-mojo:assistant-list-refresh', refresh); return () => window.removeEventListener('portal-mojo:assistant-list-refresh', refresh); }, [load]);
+    const remove = async (row: AssistantConversationSummary) => { const confirmed = await modal.confirm({ title: 'Delete conversation?', message: `Delete “${row.title}”? This cannot be undone.`, confirmText: 'Delete', danger: true }); if (!confirmed) return; try { await deleteAssistantConversation(row.id); setRows((current) => current.filter((item) => item.id !== row.id)); toast.success('Conversation deleted'); } catch (cause) { toast.error(cause instanceof Error ? cause.message : 'Delete failed'); } };
+    return <div><Heading eyebrow="Assistant" title="Conversations" description="Inspect Assistant history. Only the owner may continue a conversation." /><PageState loading={loading} error={error} retry={() => void load()} />{!loading && !error && <div className="panel assistant-list"><table><thead><tr><th>Conversation</th><th>Owner</th><th>Updated</th><th /></tr></thead><tbody>{rows.map((row) => <tr key={row.id}><td><button className="link-button" type="button" onClick={() => void modal.detail((close) => <ConversationInspect id={row.id} close={() => close(null)} />)}>{row.title}</button><small>#{row.id}</small></td><td>{row.user.display_name}{row.user.id === me?.id && <Badge tone="info">You</Badge>}</td><td>{fmt.datetime(row.modified)}</td><td><button className="btn-icon" type="button" aria-label={`Delete ${row.title}`} disabled={!isAdmin && row.user.id !== me?.id} onClick={() => void remove(row)}><i className="bi bi-trash" /></button></td></tr>)}</tbody></table>{rows.length === 0 && <p className="empty">No conversations.</p>}</div>}</div>;
+}
+
+function SkillInspect({ id, close }: { id: number; close(): void }) { const [skill, setSkill] = useState<AssistantSkill | null>(null); const [error, setError] = useState(''); useEffect(() => { void getAssistantSkill(id).then(setSkill, (cause) => setError(cause instanceof Error ? cause.message : 'Skill unavailable')); }, [id]); return <div className="modal-pad assistant-skill-detail"><header><h2>{skill?.name ?? 'Skill'}</h2><button className="btn-icon" onClick={close} aria-label="Close"><i className="bi bi-x-lg" /></button></header>{error ? <div className="form-alert">{error}</div> : !skill ? <p className="dim">Loading…</p> : <><p>{skill.description || 'No description.'}</p><dl><div><dt>Tier</dt><dd>{skill.tier}</dd></div><div><dt>Active</dt><dd>{skill.is_active ? 'Yes' : 'No'}</dd></div><div><dt>Auto execute</dt><dd>{skill.auto_execute ? 'Yes' : 'No'}</dd></div></dl><h3>Triggers</h3>{skill.triggers.length ? <ul>{skill.triggers.map((trigger) => <li key={trigger}>{trigger}</li>)}</ul> : <p className="dim">No triggers.</p>}<h3>Steps</h3>{skill.steps.length ? <ol>{skill.steps.map((step, index) => <li key={index}><code>{JSON.stringify(step)}</code></li>)}</ol> : <p className="dim">No steps.</p>}</>}</div>; }
+
+export function SkillsPage() { const [rows, setRows] = useState<AssistantSkill[]>([]); const [loading, setLoading] = useState(true); const [error, setError] = useState(''); const load = useCallback(async () => { setLoading(true); setError(''); try { setRows((await listAssistantSkills()).rows); } catch (cause) { setError(cause instanceof Error ? cause.message : 'Skills unavailable'); } finally { setLoading(false); } }, []); useEffect(() => { void load(); }, [load]); const remove = async (row: AssistantSkill) => { const confirmed = await modal.confirm({ title: 'Delete skill?', message: `Delete “${row.name}”?`, confirmText: 'Delete', danger: true }); if (!confirmed) return; try { await deleteAssistantSkill(row.id); setRows((current) => current.filter((item) => item.id !== row.id)); toast.success('Skill deleted'); } catch (cause) { toast.error(cause instanceof Error ? cause.message : 'Delete failed'); } }; return <div><Heading eyebrow="Assistant" title="Skills" description="Inspect the bounded skill catalog exposed by django-mojo." /><PageState loading={loading} error={error} retry={() => void load()} />{!loading && !error && <div className="panel assistant-list"><table><thead><tr><th>Skill</th><th>Tier</th><th>Status</th><th /></tr></thead><tbody>{rows.map((row) => <tr key={row.id}><td><button className="link-button" onClick={() => void modal.detail((close) => <SkillInspect id={row.id} close={() => close(null)} />)}>{row.name}</button><small>{row.description}</small></td><td>{row.tier}</td><td><Badge tone={row.is_active ? 'success' : 'muted'}>{row.is_active ? 'Active' : 'Inactive'}</Badge></td><td><button className="btn-icon" aria-label={`Delete ${row.name}`} onClick={() => void remove(row)}><i className="bi bi-trash" /></button></td></tr>)}</tbody></table>{rows.length === 0 && <p className="empty">No skills.</p>}</div>}</div>; }
+
+interface GroupChoice { id: number; name: string }
+type MemoryTier = 'global' | 'user' | 'group';
+export function MemoriesPage() {
+    const [tier, setTier] = useState<MemoryTier>('user'); const [groups, setGroups] = useState<GroupChoice[]>([]); const [group, setGroup] = useState<number | null>(null); const [entries, setEntries] = useState<Record<string, unknown>>({}); const [key, setKey] = useState(''); const [value, setValue] = useState(''); const [loading, setLoading] = useState(false); const [error, setError] = useState('');
+    useEffect(() => { void mojoList<GroupChoice>('/api/group', { start: 0, size: 50, sort: 'name' }).then((page) => { setGroups(page.rows.map((row) => ({ id: Number(row.id), name: String(row.name) }))); setGroup((current) => current ?? page.rows[0]?.id ?? null); }, () => setGroups([])); }, []);
+    const load = useCallback(async () => { if (tier === 'group' && group == null) { setEntries({}); return; } setLoading(true); setError(''); try { setEntries(await getAssistantMemory(tier, tier === 'group' ? group! : undefined)); } catch (cause) { setError(cause instanceof Error ? cause.message : 'Memory unavailable'); } finally { setLoading(false); } }, [tier, group]); useEffect(() => { void load(); }, [load]);
+    const validKey = /^[a-z0-9:_-]{1,64}$/.test(key); const validValue = value.length > 0 && value.length <= 500;
+    const save = async () => { if (!validKey || !validValue || (tier === 'group' && group == null)) return; try { await saveAssistantMemory(tier, key, value, tier === 'group' ? group! : undefined); setKey(''); setValue(''); await load(); toast.success('Memory saved'); } catch (cause) { setError(cause instanceof Error ? cause.message : 'Save failed'); } };
+    const remove = async (entryKey: string) => { const confirmed = await modal.confirm({ title: 'Delete memory?', message: `Delete “${entryKey}” from ${tier} memory?`, confirmText: 'Delete', danger: true }); if (!confirmed) return; try { await deleteAssistantMemory(tier, entryKey, tier === 'group' ? group! : undefined); await load(); } catch (cause) { setError(cause instanceof Error ? cause.message : 'Delete failed'); } };
+    return <div><Heading eyebrow="Assistant" title="Memory" description="Manage global, personal, or explicitly selected group memory without ambient group state." /><div className="panel panel-pad assistant-memory-controls"><div className="seg">{(['global', 'user', 'group'] as MemoryTier[]).map((item) => <button key={item} className={`seg-btn${tier === item ? ' seg-active' : ''}`} onClick={() => setTier(item)}>{item}</button>)}</div>{tier === 'group' && <label className="field"><span className="field-label">Group (bounded first 50)</span><select className="input" value={group ?? ''} onChange={(event) => setGroup(event.target.value ? Number(event.target.value) : null)}><option value="">Choose a group</option>{groups.map((item) => <option key={item.id} value={item.id}>{item.name}</option>)}</select></label>}<div className="assistant-memory-form"><label className="field"><span className="field-label">Key</span><input className="input" maxLength={64} value={key} onChange={(event) => setKey(event.target.value)} placeholder="lowercase:key" /></label><label className="field"><span className="field-label">Value</span><textarea className="input" maxLength={500} rows={2} value={value} onChange={(event) => setValue(event.target.value)} /></label><button className="btn btn-primary" disabled={!validKey || !validValue || loading || (tier === 'group' && group == null)} onClick={() => void save()}>Save</button></div>{key && !validKey && <p className="field-error">Use 1–64 lowercase letters, numbers, colon, underscore, or hyphen.</p>}{error && <div className="form-alert" role="alert">{error}</div>}</div><div className="panel assistant-list">{loading ? <p className="empty">Loading…</p> : Object.entries(entries).length ? <table><thead><tr><th>Key</th><th>Value</th><th /></tr></thead><tbody>{Object.entries(entries).slice(0, 100).map(([entryKey, entryValue]) => <tr key={entryKey}><td><code>{entryKey}</code></td><td>{String(entryValue).slice(0, 500)}</td><td><button className="btn-icon" aria-label={`Delete ${entryKey}`} onClick={() => void remove(entryKey)}><i className="bi bi-trash" /></button></td></tr>)}</tbody></table> : <p className="empty">No {tier} memory.</p>}</div></div>;
+}