Files
waggle-os/packages/server/src/local/routes/artifacts.ts
shumeiko.it f310333970 refactor(server): search memory through the contract in artifacts, agent runs, route proposals and onboarding (P1.5)
- Artifact Center related search lists personal and workspace memories
  through server.memory and finds related chat sessions in the session
  files (UF-034).
- /api/agent/run searches the requested workspace's memory, or personal
  memory when no known workspace is given.
- Executor briefs search only the workspace's own memory and leave out
  temporary memories in the query; route proposals no longer borrow a
  mind from the cache.
- Onboarding treats any personal memory as evidence of prior use.
- The service no longer creates personal.mind on a fresh install, and
  isFirstRun also looks for waggle.db.
2026-10-24 13:19:06 +02:00

404 lines
18 KiB
TypeScript

import type { FastifyPluginAsync } from 'fastify';
import type {
Artifact, ArtifactKind, ArtifactStatus, Memory, RelatedRef, RelatedSearchResult,
} from '@waggle/shared';
import path from 'node:path';
import {
PERSONAL_SCOPE, workspaceScope, type MemoryRecord, type MemoryScope,
} from '@waggle/memory-contract';
import {
readArtifactIndex, addArtifact, getArtifactInWorkspace,
patchArtifactInWorkspace, deleteArtifactFromWorkspace, type NewArtifactInput,
} from './artifact-index.js';
import { memoryStatus } from '../memory-status.js';
import { searchSessions } from './session-utils.js';
import { readTasks } from './tasks.js';
import { emitAuditEvent } from './events.js';
import { assertSafeSegment } from './validate.js';
/**
* UX-Refactor Phase 2C — Artifact Center REST surface (S05, PRD §16.6).
*
* Artifacts are first-class produced OUTCOMES (decks/docs/sheets/dashboards/
* research), not raw file attachments. Per the Phase-2 gate ratification (A6) the
* backing store is a per-workspace `artifacts.json` index (`artifact-index.ts`) —
* NO `.mind` migration. This plugin exposes the 6 routes the Artifact Center needs:
* GET /api/artifacts list + facet-filter, cross-workspace
* POST /api/artifacts record a produced output
* GET /api/artifacts/:id one artifact (resolves owning workspace)
* PATCH /api/artifacts/:id edit title/status/tags/relations (Archive = status:'archived', A8)
* DELETE /api/artifacts/:id hard delete the index entry (A8)
* GET /api/artifacts/search-related the headline federated search (PRD line 532)
*
* Gate ratifications honoured: A6 (artifacts.json index), A8 (Archive = reversible
* status via PATCH; Delete = hard delete), C12 (previews are FE icon + on-click,
* no server thumbnails — no preview generation here). `POST /:id/share` is deferred
* to the Team phase (gap card §7) — gated behind TEAMS there, not in this cut.
*/
const ARTIFACT_KINDS: readonly ArtifactKind[] = [
'document', 'presentation', 'spreadsheet', 'dashboard',
'research', 'code', 'media', 'design', 'other',
];
const ARTIFACT_STATUSES: readonly ArtifactStatus[] = [
'draft', 'ready', 'in_review', 'final', 'archived',
];
// Defense-in-depth caps on free-form fields (mirrors memory-center.ts).
const MAX_TITLE_LEN = 500;
const MAX_TAGS = 30;
const MAX_TAG_LEN = 80;
const MAX_RELATED = 200;
const MAX_REL_ID_LEN = 200;
const MAX_PATH_LEN = 2000;
// Cross-workspace fan-out / federation guards.
const MAX_LIST = 200;
const MAX_WORKSPACE_FANOUT = 24;
const PER_SOURCE_CAP = 10;
const MEMORY_SCAN = 100;
const asKind = (v: unknown): ArtifactKind | undefined =>
ARTIFACT_KINDS.includes(v as ArtifactKind) ? (v as ArtifactKind) : undefined;
const asStatus = (v: unknown): ArtifactStatus | undefined =>
ARTIFACT_STATUSES.includes(v as ArtifactStatus) ? (v as ArtifactStatus) : undefined;
const clampStr = (s: unknown, max: number): string => String(s ?? '').slice(0, max);
const clampStrArray = (a: unknown, maxItems: number, maxLen: number): string[] =>
Array.isArray(a) ? a.slice(0, maxItems).map((x) => clampStr(x, maxLen)) : [];
/** First non-empty line of a memory, capped for display. */
function memoryTitle(text: string): string {
const firstLine = text.split('\n').find((l) => l.trim().length > 0)?.trim() ?? text.trim();
return firstLine.length > 80 ? `${firstLine.slice(0, 79)}…` : firstLine;
}
const stringArray = (v: unknown): string[] | undefined =>
Array.isArray(v) ? v.filter((x): x is string => typeof x === 'string') : undefined;
/** Project a memory into the shared `Memory` shape the Artifact Center renders. */
function toRelatedMemory(record: MemoryRecord): Memory {
const meta = record.metadata;
return {
id: record.id,
kind: record.kind === 'decision' || record.kind === 'preference' ? record.kind : 'fact',
title: typeof meta.title === 'string' && meta.title.trim() ? meta.title : memoryTitle(record.text),
content: record.text,
scope: record.scope.kind,
...(record.scope.kind === 'workspace' ? { workspaceId: record.scope.workspaceId } : {}),
source: record.source,
importance: record.importance,
tags: stringArray(meta.tags),
status: memoryStatus(record),
createdAt: record.createdAt,
...(record.updatedAt ? { updatedAt: record.updatedAt } : {}),
};
}
/** Case-insensitive substring match over an artifact's title + tags. */
function artifactMatches(a: Artifact, ql: string): boolean {
if (a.title.toLowerCase().includes(ql)) return true;
return (a.tags ?? []).some((t) => t.toLowerCase().includes(ql));
}
export const artifactRoutes: FastifyPluginAsync = async (server) => {
const dataDir = server.localConfig.dataDir;
/** Workspace ids to scan: the single requested one, else every workspace
* (bounded). A user-supplied `only` is path-segment-validated (it becomes a
* directory component in the artifacts.json path) to block traversal; the
* fan-out ids come from the trusted workspace manager. */
function workspaceIds(only?: string): string[] {
if (only) {
assertSafeSegment(only, 'workspaceId');
return [only];
}
try {
return server.workspaceManager.list().slice(0, MAX_WORKSPACE_FANOUT).map((w) => w.id);
} catch {
return [];
}
}
/** Read every requested workspace's artifact index, tagging read failures as
* skipped rather than failing the whole request. */
function collectArtifacts(only?: string): Artifact[] {
const out: Artifact[] = [];
for (const wsId of workspaceIds(only)) {
try {
out.push(...readArtifactIndex(dataDir, wsId));
} catch {
// Skip an unreadable workspace index — partial data beats a 500.
}
}
return out;
}
/** Resolve the workspace that owns an artifact id (scan when not given). */
function resolveOwner(id: string, only?: string): { workspaceId: string; artifact: Artifact } | undefined {
for (const wsId of workspaceIds(only)) {
const found = getArtifactInWorkspace(dataDir, wsId, id);
if (found) return { workspaceId: wsId, artifact: found };
}
return undefined;
}
// GET /api/artifacts — cross-workspace list with facet filters (PRD §12.5).
server.get<{
Querystring: {
workspaceId?: string; kind?: string; status?: string; tag?: string; q?: string; limit?: string;
};
}>('/api/artifacts', async (request) => {
const { workspaceId, kind, status, tag, q, limit } = request.query;
// Floor the lower bound too: a negative limit would otherwise reach
// slice(0, -n) and silently drop the newest n rows (review F1).
const parsedLimit = limit ? parseInt(limit, 10) : MAX_LIST;
const max = Math.min(Number.isFinite(parsedLimit) && parsedLimit > 0 ? parsedLimit : MAX_LIST, MAX_LIST);
let results = collectArtifacts(workspaceId);
if (kind) results = results.filter((a) => a.kind === kind);
if (status) results = results.filter((a) => a.status === status);
if (tag) {
const tl = tag.toLowerCase();
results = results.filter((a) => (a.tags ?? []).some((t) => t.toLowerCase() === tl));
}
if (q) {
const ql = q.toLowerCase();
results = results.filter((a) => artifactMatches(a, ql));
}
results.sort((a, b) => (b.updatedAt ?? '').localeCompare(a.updatedAt ?? ''));
const page = results.slice(0, max);
return { results: page, count: page.length };
});
// GET /api/artifacts/search-related — the headline federated endpoint (PRD line
// 532): a query returns matching artifacts PLUS related memories/sessions/tasks/
// agents. Each source is bounded + independently guarded so one failing group
// never breaks the response. NOTE: `agents` is intentionally empty in v1 — the
// Agent entity is a Phase-3 surface (S09, gate B3) that does not exist yet.
// Registered before `/:id` so the literal path is not shadowed by the param route.
server.get<{
Querystring: { q?: string; workspaceId?: string };
}>('/api/artifacts/search-related', async (request, reply) => {
const q = (request.query.q ?? '').trim();
if (!q) return reply.status(400).send({ error: 'q is required' });
const ql = q.toLowerCase();
const only = request.query.workspaceId;
// artifacts
const artifacts = collectArtifacts(only)
.filter((a) => artifactMatches(a, ql))
.sort((a, b) => (b.updatedAt ?? '').localeCompare(a.updatedAt ?? ''))
.slice(0, PER_SOURCE_CAP);
// memories — recent personal memories, then each (scoped|all) workspace's.
const memories: Memory[] = [];
try {
const scan = async (scope: MemoryScope) => {
if (memories.length >= PER_SOURCE_CAP) return;
for (const record of await server.memory.list({ scopes: [scope], limit: MEMORY_SCAN })) {
const m = toRelatedMemory(record);
if (m.content.toLowerCase().includes(ql) || m.title.toLowerCase().includes(ql)) {
memories.push(m);
if (memories.length >= PER_SOURCE_CAP) break;
}
}
};
await scan(PERSONAL_SCOPE);
for (const wsId of workspaceIds(only)) {
if (memories.length >= PER_SOURCE_CAP) break;
await scan(workspaceScope(wsId));
}
} catch {
// degrade to whatever was collected
}
// tasks — cross-workspace JSONL board, title match.
const tasks: RelatedRef[] = [];
try {
for (const wsId of workspaceIds(only)) {
if (tasks.length >= PER_SOURCE_CAP) break;
for (const t of readTasks(server.localConfig.dataDir, wsId)) {
if (t.title.toLowerCase().includes(ql)) {
tasks.push({ id: t.id, title: t.title, workspaceId: wsId, kind: t.status });
if (tasks.length >= PER_SOURCE_CAP) break;
}
}
}
} catch {
// skip
}
// sessions — chat sessions whose title, summary or messages match, the
// same search the dedicated /sessions/search route runs.
const sessions: RelatedRef[] = [];
try {
for (const wsId of workspaceIds(only)) {
if (sessions.length >= PER_SOURCE_CAP) break;
const sessionsDir = path.join(dataDir, 'workspaces', wsId, 'sessions');
for (const hit of searchSessions(sessionsDir, q, PER_SOURCE_CAP - sessions.length)) {
sessions.push({
id: hit.sessionId,
title: hit.title.slice(0, 120),
workspaceId: wsId,
...(hit.snippets[0] ? { snippet: hit.snippets[0].text } : {}),
});
}
}
} catch {
// skip
}
const result: RelatedSearchResult = { artifacts, memories, sessions, tasks, agents: [] };
return result;
});
// POST /api/artifacts — record a produced output in a workspace index.
server.post<{
Body: {
title?: string; kind?: string; workspaceId?: string; source?: string;
createdBy?: string; teamId?: string | null; status?: string; mimeType?: string;
storagePath?: string; previewUrl?: string; tags?: string[];
relatedMemoryIds?: string[]; relatedSessionIds?: string[];
relatedTaskIds?: string[]; relatedAgentIds?: string[];
};
}>('/api/artifacts', async (request, reply) => {
const b = request.body ?? {};
if (!b.title || !b.title.trim()) {
return reply.status(400).send({ error: 'title is required' });
}
if (!b.workspaceId) {
return reply.status(400).send({ error: 'workspaceId is required' });
}
assertSafeSegment(b.workspaceId, 'workspaceId');
const kind = asKind(b.kind);
if (!kind) {
return reply.status(400).send({ error: `kind must be one of: ${ARTIFACT_KINDS.join(', ')}` });
}
if (b.status !== undefined && !asStatus(b.status)) {
return reply.status(400).send({ error: `Invalid status "${b.status}"` });
}
const input: NewArtifactInput = {
title: clampStr(b.title, MAX_TITLE_LEN),
kind,
source: clampStr(b.source ?? 'user', 80),
createdBy: clampStr(b.createdBy ?? 'user', 200),
status: asStatus(b.status) ?? 'draft',
...(b.teamId !== undefined ? { teamId: b.teamId } : {}),
...(b.mimeType ? { mimeType: clampStr(b.mimeType, 200) } : {}),
...(b.storagePath ? { storagePath: clampStr(b.storagePath, MAX_PATH_LEN) } : {}),
...(b.previewUrl ? { previewUrl: clampStr(b.previewUrl, MAX_PATH_LEN) } : {}),
...(Array.isArray(b.tags) ? { tags: clampStrArray(b.tags, MAX_TAGS, MAX_TAG_LEN) } : {}),
...(Array.isArray(b.relatedMemoryIds) ? { relatedMemoryIds: clampStrArray(b.relatedMemoryIds, MAX_RELATED, MAX_REL_ID_LEN) } : {}),
...(Array.isArray(b.relatedSessionIds) ? { relatedSessionIds: clampStrArray(b.relatedSessionIds, MAX_RELATED, MAX_REL_ID_LEN) } : {}),
...(Array.isArray(b.relatedTaskIds) ? { relatedTaskIds: clampStrArray(b.relatedTaskIds, MAX_RELATED, MAX_REL_ID_LEN) } : {}),
...(Array.isArray(b.relatedAgentIds) ? { relatedAgentIds: clampStrArray(b.relatedAgentIds, MAX_RELATED, MAX_REL_ID_LEN) } : {}),
};
const artifact = addArtifact(dataDir, b.workspaceId, input);
emitAuditEvent(server, {
workspaceId: b.workspaceId,
eventType: 'artifact_write',
input: JSON.stringify({ action: 'create', title: input.title.slice(0, 200), kind }),
output: JSON.stringify({ artifactId: artifact.id }),
});
return reply.status(201).send(artifact);
});
// GET /api/artifacts/:id — one artifact (resolves owning workspace if not given).
server.get<{
Params: { id: string };
Querystring: { workspaceId?: string };
}>('/api/artifacts/:id', async (request, reply) => {
const owner = resolveOwner(request.params.id, request.query.workspaceId);
if (!owner) return reply.status(404).send({ error: 'Artifact not found' });
return owner.artifact;
});
// PATCH /api/artifacts/:id — edit metadata/relations. Archive = status:'archived'
// (A8 reversible — there is no separate archive route; un-archive is the inverse PATCH).
server.patch<{
Params: { id: string };
Querystring: { workspaceId: string };
Body: {
title?: string; kind?: string; status?: string; mimeType?: string;
storagePath?: string; previewUrl?: string; source?: string; teamId?: string | null;
tags?: string[]; relatedMemoryIds?: string[]; relatedSessionIds?: string[];
relatedTaskIds?: string[]; relatedAgentIds?: string[];
};
}>('/api/artifacts/:id', async (request, reply) => {
const b = request.body ?? {};
if (b.kind !== undefined && !asKind(b.kind)) {
return reply.status(400).send({ error: `Invalid kind "${b.kind}"` });
}
if (b.status !== undefined && !asStatus(b.status)) {
return reply.status(400).send({ error: `Invalid status "${b.status}"` });
}
const workspaceId = request.query.workspaceId;
if (!workspaceId) {
return reply.status(400).send({ error: 'workspaceId is required' });
}
const owner = resolveOwner(request.params.id, workspaceId);
if (!owner) return reply.status(404).send({ error: 'Artifact not found' });
const patch: Partial<Artifact> = {
...(b.title !== undefined ? { title: clampStr(b.title, MAX_TITLE_LEN) } : {}),
...(b.kind !== undefined ? { kind: b.kind as ArtifactKind } : {}),
...(b.status !== undefined ? { status: b.status as ArtifactStatus } : {}),
...(b.mimeType !== undefined ? { mimeType: clampStr(b.mimeType, 200) } : {}),
...(b.storagePath !== undefined ? { storagePath: clampStr(b.storagePath, MAX_PATH_LEN) } : {}),
...(b.previewUrl !== undefined ? { previewUrl: clampStr(b.previewUrl, MAX_PATH_LEN) } : {}),
...(b.source !== undefined ? { source: clampStr(b.source, 80) } : {}),
...(b.teamId !== undefined ? { teamId: b.teamId } : {}),
...(b.tags !== undefined ? { tags: clampStrArray(b.tags, MAX_TAGS, MAX_TAG_LEN) } : {}),
...(b.relatedMemoryIds !== undefined ? { relatedMemoryIds: clampStrArray(b.relatedMemoryIds, MAX_RELATED, MAX_REL_ID_LEN) } : {}),
...(b.relatedSessionIds !== undefined ? { relatedSessionIds: clampStrArray(b.relatedSessionIds, MAX_RELATED, MAX_REL_ID_LEN) } : {}),
...(b.relatedTaskIds !== undefined ? { relatedTaskIds: clampStrArray(b.relatedTaskIds, MAX_RELATED, MAX_REL_ID_LEN) } : {}),
...(b.relatedAgentIds !== undefined ? { relatedAgentIds: clampStrArray(b.relatedAgentIds, MAX_RELATED, MAX_REL_ID_LEN) } : {}),
};
// A8 reversibility: on Archive, stash the pre-archive status so Unarchive can
// restore the real prior lifecycle state; clear it when leaving the archive.
if (b.status !== undefined) {
const cur = owner.artifact.status;
if (b.status === 'archived' && cur !== 'archived') patch.prevStatus = cur;
else if (b.status !== 'archived' && cur === 'archived') patch.prevStatus = undefined;
}
const updated = patchArtifactInWorkspace(dataDir, owner.workspaceId, request.params.id, patch);
if (!updated) return reply.status(404).send({ error: 'Artifact not found' });
emitAuditEvent(server, {
workspaceId: owner.workspaceId,
eventType: 'artifact_write',
input: JSON.stringify({ action: 'patch', id: request.params.id }),
output: JSON.stringify({ artifactId: updated.id, status: updated.status }),
});
return updated;
});
// DELETE /api/artifacts/:id — hard delete the index entry (A8, no tombstone).
// v1 removes the artifact record only; the backing storage file (if any) is left
// in place — it may be referenced elsewhere, and storage-level deletion belongs to
// the storage routes. The FE gates this behind a scope-and-consequence confirm (J20).
server.delete<{
Params: { id: string };
Querystring: { workspaceId: string };
}>('/api/artifacts/:id', async (request, reply) => {
const workspaceId = request.query.workspaceId;
if (!workspaceId) {
return reply.status(400).send({ error: 'workspaceId is required' });
}
const owner = resolveOwner(request.params.id, workspaceId);
if (!owner) return reply.status(404).send({ error: 'Artifact not found' });
const removed = deleteArtifactFromWorkspace(dataDir, owner.workspaceId, request.params.id);
if (!removed) return reply.status(404).send({ error: 'Artifact not found' });
emitAuditEvent(server, {
workspaceId: owner.workspaceId,
eventType: 'artifact_delete',
input: JSON.stringify({ id: request.params.id, workspaceId: owner.workspaceId }),
});
return reply.status(200).send({ deleted: true, id: request.params.id });
});
};