Files
waggle-os/packages/agent/src/cross-workspace-tools.ts
shumeiko.it 784ca770b1 refactor(memory): run agent recall, memory tools and the server on the memory contract (P1.5)
- Orchestrator, memory tools, context loader and pattern write-back use a
  MemoryStore and a workspace scope instead of MindDB layers; the knowledge
  graph tools, cognify, memory linker and feedback handler are gone (graph
  hidden in v1, ADR-0002).
- The server opens one mem0 store in <dataDir>/memory/, embedded by the
  in-process model on first use, and extracts facts about the user in the
  background with the model the user chose (memoryExtraction setting).
- Legacy .mind memories are copied into the store once, in the background;
  the legacy files are only read.
- Weaver consolidation, harvest, wiki, memory import, memory lanes, vector
  backfill and index reconciliation are removed; agent runs, loops, sub-agent
  results, connector fetch and the failed-turn capture write through the
  contract. Workspace sessions no longer hold a mind handle.
- FileIndexer and the install audit move to waggle.db; recall date helpers and
  the reranker are copied into core.
- The CLI REPL opens the same memory store.
2026-10-24 11:56:26 +02:00

314 lines
11 KiB
TypeScript

/**
* Cross-workspace tools — Phase B.2 of the Killer Story plan.
*
* Gives the agent read-only access to OTHER workspaces' memory and files
* so a chat running in Workspace A can surface prior decisions or files
* from Workspace B. Writes are never allowed through this path —
* cross-workspace writes require a separate, explicit flow.
*
* Every call is gated by the existing confirmation mechanism (the tools
* are listed in ALWAYS_CONFIRM). The approvals inbox and persistent
* "always allow" grants land in Phase B.3.
*/
import { workspaceScope, type MemoryStore } from '@waggle/memory-contract';
import type { ToolDefinition } from './tools.js';
export interface CrossWorkspaceToolDeps {
/** The workspace this tool instance is running in (the "source"). */
sourceWorkspaceId: string;
/** Memory of every workspace; this tool reads only the target workspace's scope. */
memory: MemoryStore;
/** Returns the list of known workspace IDs + display names (for discovery). */
listWorkspaces: () => Array<{ id: string; name: string }>;
/** Returns a file listing for the given workspace (workspace-scoped path). */
listWorkspaceFiles?: (workspaceId: string, subPath?: string) => Promise<Array<{
name: string;
type: 'file' | 'directory';
size?: number;
modifiedAt?: string;
}>>;
/**
* L-21: read a file from another workspace. Optional dependency — if not
* wired, `read_other_workspace_file` surfaces a clear error instead of
* failing silently. Resolves to file content as a UTF-8 string (callers
* that need binary should extend this signature before wiring it).
*/
readWorkspaceFile?: (workspaceId: string, relativePath: string) => Promise<string>;
}
export function createCrossWorkspaceTools(deps: CrossWorkspaceToolDeps): ToolDefinition[] {
const { sourceWorkspaceId, memory, listWorkspaces, listWorkspaceFiles, readWorkspaceFile } = deps;
const readOtherWorkspace: ToolDefinition = {
name: 'read_other_workspace',
description: [
'Search memory in another workspace. READ-ONLY — never writes.',
'Use when the user references something they worked on in a different project.',
'Requires the target workspace ID. Call list_workspaces first if unsure.',
'Returns ranked memories with the target workspace explicitly named',
'so you can cite the source clearly ("In Workspace B, you decided...").',
'First use on a new target workspace prompts the user for approval.',
].join(' '),
parameters: {
type: 'object' as const,
required: ['target_workspace_id', 'query'],
properties: {
target_workspace_id: {
type: 'string' as const,
description: 'The workspace ID to read from. Use list_workspaces to discover valid IDs.',
},
query: {
type: 'string' as const,
description: 'Natural-language search query. Semantic search over the target workspace memory.',
},
limit: {
type: 'number' as const,
description: 'Max results to return. Default 10, capped at 30.',
},
},
},
// Tagged as requiring confirmation — the confirmation gate reads
// the tool name and triggers the approval hook.
offlineCapable: false,
execute: async (args: Record<string, unknown>) => {
const targetId = String(args.target_workspace_id ?? '').trim();
const query = String(args.query ?? '').trim();
const limit = Math.min(Math.max(Number(args.limit) || 10, 1), 30);
if (!targetId) {
return JSON.stringify({
error: 'target_workspace_id is required',
hint: 'Call list_workspaces to see valid IDs.',
});
}
if (!query) {
return JSON.stringify({ error: 'query is required' });
}
if (targetId === sourceWorkspaceId) {
return JSON.stringify({
error: 'Target workspace is the same as the source. Use search_memory instead.',
});
}
const known = listWorkspaces();
if (!known.some(w => w.id === targetId)) {
return JSON.stringify({
error: `Workspace "${targetId}" not found or not accessible.`,
knownWorkspaces: known.map(w => ({ id: w.id, name: w.name })),
});
}
try {
const results = await memory.search(query, { scopes: [workspaceScope(targetId)], limit });
const targetName = known.find(w => w.id === targetId)?.name ?? targetId;
if (results.length === 0) {
return JSON.stringify({
sourceWorkspace: sourceWorkspaceId,
targetWorkspace: targetId,
targetWorkspaceName: targetName,
query,
matchCount: 0,
hint: `No matches in workspace "${targetName}". Try broader terms.`,
});
}
const matches = results.map(r => ({
content: r.text.slice(0, 500),
importance: r.importance,
createdAt: r.createdAt,
score: r.score,
}));
return JSON.stringify({
sourceWorkspace: sourceWorkspaceId,
targetWorkspace: targetId,
targetWorkspaceName: targetName,
query,
matchCount: matches.length,
matches,
citation: `(from workspace "${targetName}")`,
});
} catch (err) {
return JSON.stringify({
error: `Cross-workspace search failed: ${(err as Error).message}`,
});
}
},
};
const listWorkspacesTool: ToolDefinition = {
name: 'list_workspaces',
description: [
'List every workspace the user has, with their IDs and names.',
'Use this for orientation before calling read_other_workspace or',
'list_workspace_files when you\'re not sure which target ID to use.',
'Read-only, no approval required, no cost.',
].join(' '),
parameters: {
type: 'object' as const,
required: [],
properties: {},
},
offlineCapable: true,
execute: async () => {
const workspaces = listWorkspaces();
return JSON.stringify({
sourceWorkspace: sourceWorkspaceId,
count: workspaces.length,
workspaces: workspaces.map(w => ({
id: w.id,
name: w.name,
isCurrentWorkspace: w.id === sourceWorkspaceId,
})),
});
},
};
const listWorkspaceFilesTool: ToolDefinition = {
name: 'list_workspace_files',
description: [
'List files in ANOTHER workspace (read-only). Use to find documents',
'or files referenced from elsewhere in the user\'s projects.',
'First use on a new target workspace prompts the user for approval.',
].join(' '),
parameters: {
type: 'object' as const,
required: ['target_workspace_id'],
properties: {
target_workspace_id: {
type: 'string' as const,
description: 'The workspace ID to list files in. Call list_workspaces to discover IDs.',
},
path: {
type: 'string' as const,
description: 'Optional sub-path within the workspace. Defaults to the root.',
},
},
},
offlineCapable: false,
execute: async (args: Record<string, unknown>) => {
const targetId = String(args.target_workspace_id ?? '').trim();
const subPath = args.path ? String(args.path) : undefined;
if (!targetId) {
return JSON.stringify({ error: 'target_workspace_id is required' });
}
if (targetId === sourceWorkspaceId) {
return JSON.stringify({
error: 'Target workspace is the same as the source. Use search_files / read_file on local paths instead.',
});
}
if (!listWorkspaceFiles) {
return JSON.stringify({
error: 'Cross-workspace file listing is not available (listWorkspaceFiles not wired).',
});
}
try {
const files = await listWorkspaceFiles(targetId, subPath);
const targetName = listWorkspaces().find(w => w.id === targetId)?.name ?? targetId;
return JSON.stringify({
sourceWorkspace: sourceWorkspaceId,
targetWorkspace: targetId,
targetWorkspaceName: targetName,
path: subPath ?? '/',
fileCount: files.length,
files: files.map(f => ({
name: f.name,
type: f.type,
size: f.size,
modifiedAt: f.modifiedAt,
})),
});
} catch (err) {
return JSON.stringify({
error: `Cross-workspace file listing failed: ${(err as Error).message}`,
});
}
},
};
// L-21: read_other_workspace_file. Read-only file access in another
// workspace. Gated by the same confirmation pattern as the memory
// reader (key = tool name, registered in ALWAYS_CONFIRM).
const readOtherWorkspaceFile: ToolDefinition = {
name: 'read_other_workspace_file',
description: [
'Read the contents of a file in ANOTHER workspace. READ-ONLY.',
'Use after list_workspace_files has shown the file exists — paths',
'are relative to the target workspace root.',
'First use on a new target workspace prompts the user for approval.',
'Returns the file as a UTF-8 string; binary files surface as a',
'warning rather than raw bytes.',
].join(' '),
parameters: {
type: 'object' as const,
required: ['target_workspace_id', 'path'],
properties: {
target_workspace_id: {
type: 'string' as const,
description: 'The workspace ID to read from. Call list_workspaces to discover IDs.',
},
path: {
type: 'string' as const,
description: 'Path relative to the target workspace root.',
},
},
},
offlineCapable: false,
execute: async (args: Record<string, unknown>) => {
const targetId = String(args.target_workspace_id ?? '').trim();
const relativePath = String(args.path ?? '').trim();
if (!targetId) {
return JSON.stringify({
error: 'target_workspace_id is required',
hint: 'Call list_workspaces to see valid IDs.',
});
}
if (!relativePath) {
return JSON.stringify({
error: 'path is required',
hint: 'Call list_workspace_files to discover file paths first.',
});
}
if (targetId === sourceWorkspaceId) {
return JSON.stringify({
error: 'Target workspace is the same as the source. Use read_file on a local path instead.',
});
}
if (!readWorkspaceFile) {
return JSON.stringify({
error: 'Cross-workspace file reading is not available (readWorkspaceFile not wired).',
});
}
try {
const content = await readWorkspaceFile(targetId, relativePath);
const targetName = listWorkspaces().find(w => w.id === targetId)?.name ?? targetId;
// Cap at 100KB so a huge file doesn't blow the agent's context.
const MAX_CHARS = 100_000;
const truncated = content.length > MAX_CHARS;
const body = truncated ? content.slice(0, MAX_CHARS) : content;
return JSON.stringify({
sourceWorkspace: sourceWorkspaceId,
targetWorkspace: targetId,
targetWorkspaceName: targetName,
path: relativePath,
size: content.length,
truncated,
content: body,
});
} catch (err) {
return JSON.stringify({
error: `Cross-workspace file read failed: ${(err as Error).message}`,
});
}
},
};
return [readOtherWorkspace, listWorkspacesTool, listWorkspaceFilesTool, readOtherWorkspaceFile];
}