@phren/cli 0.1.31 → 0.1.33

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. package/dist/capabilities/cli.js +2 -2
  2. package/dist/cli/config-access.d.ts +1 -0
  3. package/dist/cli/config-access.js +59 -0
  4. package/dist/cli/config-llm.d.ts +1 -0
  5. package/dist/cli/config-llm.js +60 -0
  6. package/dist/cli/config-policy.d.ts +11 -0
  7. package/dist/cli/config-policy.js +328 -0
  8. package/dist/cli/config-proactivity.d.ts +15 -0
  9. package/dist/cli/config-proactivity.js +129 -0
  10. package/dist/cli/config-shared.d.ts +6 -0
  11. package/dist/cli/config-shared.js +23 -0
  12. package/dist/cli/config-synonyms.d.ts +1 -0
  13. package/dist/cli/config-synonyms.js +60 -0
  14. package/dist/cli/config.d.ts +6 -24
  15. package/dist/cli/config.js +13 -670
  16. package/dist/finding-graph-id.d.ts +15 -0
  17. package/dist/finding-graph-id.js +58 -0
  18. package/dist/generated/memory-ui-graph.browser.js +15 -15
  19. package/dist/governance/activity.d.ts +36 -0
  20. package/dist/governance/activity.js +83 -0
  21. package/dist/governance/rbac.d.ts +17 -0
  22. package/dist/governance/rbac.js +37 -1
  23. package/dist/memory-ui-graph.runtime.js +15 -15
  24. package/dist/phren-paths.d.ts +6 -0
  25. package/dist/phren-paths.js +8 -0
  26. package/dist/shared/governance.d.ts +1 -0
  27. package/dist/shared/governance.js +1 -0
  28. package/dist/shared.d.ts +1 -1
  29. package/dist/shared.js +1 -1
  30. package/dist/tools/config.js +39 -2
  31. package/dist/tools/finding.js +5 -11
  32. package/dist/tools/search.js +28 -1
  33. package/dist/tools/tasks.js +3 -12
  34. package/dist/ui/data.d.ts +2 -0
  35. package/dist/ui/data.js +8 -3
  36. package/dist/ui/graph.js +2 -0
  37. package/dist/ui/page.js +45 -2
  38. package/dist/ui/scripts.d.ts +13 -0
  39. package/dist/ui/scripts.js +229 -2
  40. package/dist/ui/server.js +165 -1
  41. package/dist/ui/styles.d.ts +1 -0
  42. package/dist/ui/styles.js +38 -0
  43. package/package.json +1 -1
  44. package/dist/cli-hooks-prompt.d.ts +0 -18
  45. package/dist/cli-hooks-prompt.js +0 -359
  46. package/dist/cli-hooks-session-handlers.d.ts +0 -3
  47. package/dist/cli-hooks-session-handlers.js +0 -356
  48. package/dist/cli-hooks-stop.d.ts +0 -11
  49. package/dist/cli-hooks-stop.js +0 -584
  50. package/dist/init-bootstrap.d.ts +0 -5
  51. package/dist/init-bootstrap.js +0 -21
  52. package/dist/init-detect.d.ts +0 -8
  53. package/dist/init-detect.js +0 -38
  54. package/dist/init-env.d.ts +0 -6
  55. package/dist/init-env.js +0 -114
  56. package/dist/init-fresh.d.ts +0 -10
  57. package/dist/init-fresh.js +0 -234
  58. package/dist/init-hooks.d.ts +0 -5
  59. package/dist/init-hooks.js +0 -26
  60. package/dist/init-mcp.d.ts +0 -8
  61. package/dist/init-mcp.js +0 -65
  62. package/dist/init-modes.d.ts +0 -4
  63. package/dist/init-modes.js +0 -135
  64. package/dist/init-npm.d.ts +0 -10
  65. package/dist/init-npm.js +0 -37
  66. package/dist/init-project-local.d.ts +0 -2
  67. package/dist/init-project-local.js +0 -99
  68. package/dist/init-semantic.d.ts +0 -4
  69. package/dist/init-semantic.js +0 -48
  70. package/dist/init-types.d.ts +0 -59
  71. package/dist/init-types.js +0 -1
  72. package/dist/init-update.d.ts +0 -10
  73. package/dist/init-update.js +0 -96
@@ -37,6 +37,12 @@ export declare function shellStateFile(phrenPath: string): string;
37
37
  export declare function sessionMetricsFile(phrenPath: string): string;
38
38
  export declare function memoryScoresFile(phrenPath: string): string;
39
39
  export declare function memoryUsageLogFile(phrenPath: string): string;
40
+ /**
41
+ * Live "lookup events" log: one JSONL entry per memory a search lands on.
42
+ * Distinct from memory-usage.log (injection scoring) — this feed powers the
43
+ * real-time activity surfaces in the web UI and the VS Code extension.
44
+ */
45
+ export declare function lookupEventsLogFile(phrenPath: string): string;
40
46
  export declare function sessionMarker(phrenPath: string, name: string): string;
41
47
  export declare function debugLog(msg: string): void;
42
48
  /** Always-on structured error log (no PHREN_DEBUG gate). */
@@ -265,6 +265,14 @@ export function memoryScoresFile(phrenPath) {
265
265
  export function memoryUsageLogFile(phrenPath) {
266
266
  return path.join(runtimeDir(phrenPath), "memory-usage.log");
267
267
  }
268
+ /**
269
+ * Live "lookup events" log: one JSONL entry per memory a search lands on.
270
+ * Distinct from memory-usage.log (injection scoring) — this feed powers the
271
+ * real-time activity surfaces in the web UI and the VS Code extension.
272
+ */
273
+ export function lookupEventsLogFile(phrenPath) {
274
+ return path.join(runtimeDir(phrenPath), "lookup-events.jsonl");
275
+ }
268
276
  export function sessionMarker(phrenPath, name) {
269
277
  const dir = sessionsDir(phrenPath);
270
278
  fs.mkdirSync(dir, { recursive: true });
@@ -1,4 +1,5 @@
1
1
  export * from '../governance/policy.js';
2
2
  export * from '../governance/scores.js';
3
3
  export * from '../governance/audit.js';
4
+ export * from '../governance/activity.js';
4
5
  export { withFileLock, isFiniteNumber, hasValidSchemaVersion } from '../governance/locks.js';
@@ -1,4 +1,5 @@
1
1
  export * from '../governance/policy.js';
2
2
  export * from '../governance/scores.js';
3
3
  export * from '../governance/audit.js';
4
+ export * from '../governance/activity.js';
4
5
  export { withFileLock, isFiniteNumber, hasValidSchemaVersion } from '../governance/locks.js';
package/dist/shared.d.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  export type { HookToolName } from "./provider-adapters.js";
2
2
  export { HOOK_TOOL_NAMES, hookConfigPath } from "./provider-adapters.js";
3
3
  export { EXEC_TIMEOUT_MS, EXEC_TIMEOUT_QUICK_MS, PhrenError, type PhrenErrorCode, type PhrenResult, phrenOk, phrenErr, forwardErr, parsePhrenErrorCode, isRecord, withDefaults, FINDING_TYPES, type FindingType, FINDING_TAGS, type FindingTag, KNOWN_OBSERVATION_TAGS, DOC_TYPES, type DocType, capCache, RESERVED_PROJECT_DIR_NAMES, } from "./phren-core.js";
4
- export { ROOT_MANIFEST_FILENAME, type InstallMode, type SyncMode, type PhrenRootManifest, type InstallContext, isInstallMode, homeDir, homePath, expandHomePath, defaultPhrenPath, rootManifestPath, readRootManifest, writeRootManifest, resolveInstallContext, findNearestPhrenPath, isProjectLocalMode, runtimeDir, tryUnlink, sessionsDir, runtimeFile, installPreferencesFile, runtimeHealthFile, shellStateFile, sessionMetricsFile, memoryScoresFile, memoryUsageLogFile, sessionMarker, debugLog, appendIndexEvent, resolveFindingsPath, findPhrenPath, ensurePhrenPath, findPhrenPathWithArg, normalizeProjectNameForCreate, findProjectNameCaseInsensitive, findArchivedProjectNameCaseInsensitive, getProjectDirs, listInvalidProjectDirs, collectNativeMemoryFiles, computePhrenLiveStateToken, getPhrenPath, qualityMarkers, atomicWriteText, } from "./phren-paths.js";
4
+ export { ROOT_MANIFEST_FILENAME, type InstallMode, type SyncMode, type PhrenRootManifest, type InstallContext, isInstallMode, homeDir, homePath, expandHomePath, defaultPhrenPath, rootManifestPath, readRootManifest, writeRootManifest, resolveInstallContext, findNearestPhrenPath, isProjectLocalMode, runtimeDir, tryUnlink, sessionsDir, runtimeFile, installPreferencesFile, runtimeHealthFile, shellStateFile, sessionMetricsFile, memoryScoresFile, memoryUsageLogFile, lookupEventsLogFile, sessionMarker, debugLog, appendIndexEvent, resolveFindingsPath, findPhrenPath, ensurePhrenPath, findPhrenPathWithArg, normalizeProjectNameForCreate, findProjectNameCaseInsensitive, findArchivedProjectNameCaseInsensitive, getProjectDirs, listInvalidProjectDirs, collectNativeMemoryFiles, computePhrenLiveStateToken, getPhrenPath, qualityMarkers, atomicWriteText, } from "./phren-paths.js";
5
5
  export { PROACTIVITY_LEVELS, type ProactivityLevel, parseProactivityLevel, getProactivityLevel, getProactivityLevelForFindings, getProactivityLevelForTask, hasExplicitFindingSignal, hasExplicitTaskSignal, hasExecutionIntent, hasDiscoveryIntent, shouldAutoCaptureFindingsForLevel, shouldAutoCaptureTaskForLevel, } from "./proactivity.js";
6
6
  export declare function normalizeMemoryScope(scope?: string | null): string | undefined;
7
7
  export declare function isMemoryScopeVisible(itemScope: string | undefined, activeScope?: string): boolean;
package/dist/shared.js CHANGED
@@ -6,7 +6,7 @@ import { withFileLock } from "./governance/locks.js";
6
6
  const MAX_LOG_LINES = 1000;
7
7
  export { HOOK_TOOL_NAMES, hookConfigPath } from "./provider-adapters.js";
8
8
  export { EXEC_TIMEOUT_MS, EXEC_TIMEOUT_QUICK_MS, PhrenError, phrenOk, phrenErr, forwardErr, parsePhrenErrorCode, isRecord, withDefaults, FINDING_TYPES, FINDING_TAGS, KNOWN_OBSERVATION_TAGS, DOC_TYPES, capCache, RESERVED_PROJECT_DIR_NAMES, } from "./phren-core.js";
9
- export { ROOT_MANIFEST_FILENAME, isInstallMode, homeDir, homePath, expandHomePath, defaultPhrenPath, rootManifestPath, readRootManifest, writeRootManifest, resolveInstallContext, findNearestPhrenPath, isProjectLocalMode, runtimeDir, tryUnlink, sessionsDir, runtimeFile, installPreferencesFile, runtimeHealthFile, shellStateFile, sessionMetricsFile, memoryScoresFile, memoryUsageLogFile, sessionMarker, debugLog, appendIndexEvent, resolveFindingsPath, findPhrenPath, ensurePhrenPath, findPhrenPathWithArg, normalizeProjectNameForCreate, findProjectNameCaseInsensitive, findArchivedProjectNameCaseInsensitive, getProjectDirs, listInvalidProjectDirs, collectNativeMemoryFiles, computePhrenLiveStateToken, getPhrenPath, qualityMarkers, atomicWriteText, } from "./phren-paths.js";
9
+ export { ROOT_MANIFEST_FILENAME, isInstallMode, homeDir, homePath, expandHomePath, defaultPhrenPath, rootManifestPath, readRootManifest, writeRootManifest, resolveInstallContext, findNearestPhrenPath, isProjectLocalMode, runtimeDir, tryUnlink, sessionsDir, runtimeFile, installPreferencesFile, runtimeHealthFile, shellStateFile, sessionMetricsFile, memoryScoresFile, memoryUsageLogFile, lookupEventsLogFile, sessionMarker, debugLog, appendIndexEvent, resolveFindingsPath, findPhrenPath, ensurePhrenPath, findPhrenPathWithArg, normalizeProjectNameForCreate, findProjectNameCaseInsensitive, findArchivedProjectNameCaseInsensitive, getProjectDirs, listInvalidProjectDirs, collectNativeMemoryFiles, computePhrenLiveStateToken, getPhrenPath, qualityMarkers, atomicWriteText, } from "./phren-paths.js";
10
10
  export { PROACTIVITY_LEVELS, parseProactivityLevel, getProactivityLevel, getProactivityLevelForFindings, getProactivityLevelForTask, hasExplicitFindingSignal, hasExplicitTaskSignal, hasExecutionIntent, hasDiscoveryIntent, shouldAutoCaptureFindingsForLevel, shouldAutoCaptureTaskForLevel, } from "./proactivity.js";
11
11
  const MEMORY_SCOPE_PATTERN = /^[a-z][a-z0-9_-]{0,63}$/;
12
12
  export function normalizeMemoryScope(scope) {
@@ -8,6 +8,7 @@ import { writeGovernanceInstallPreferences, } from "../init/preferences.js";
8
8
  import { FINDING_SENSITIVITY_CONFIG, buildProactivitySnapshot, checkProjectInProfile } from "../cli/config.js";
9
9
  import { readProjectConfig, updateProjectConfigOverrides, } from "../project-config.js";
10
10
  import { isValidProjectName, safeProjectPath } from "../utils.js";
11
+ import { ACCESS_ROLE_KEYS, setAccessRoles } from "../governance/rbac.js";
11
12
  import { readProjectTopics, writeProjectTopics, } from "../project-topics.js";
12
13
  import { buildConfigView } from "../config/resolve.js";
13
14
  import { getConfigField, CONFIG_DOMAINS } from "../config/schema.js";
@@ -451,6 +452,41 @@ async function handleSetConfig(ctx, { domain, settings, project }) {
451
452
  data: result.data,
452
453
  });
453
454
  }
455
+ // ── access ────────────────────────────────────────────────────
456
+ case "access": {
457
+ const patch = {};
458
+ let touched = false;
459
+ for (const key of ACCESS_ROLE_KEYS) {
460
+ const value = settings[key];
461
+ if (value === undefined)
462
+ continue;
463
+ if (!Array.isArray(value) || value.some((v) => typeof v !== "string")) {
464
+ return mcpResponse({ ok: false, error: `Invalid access roles: "${key}" must be an array of strings.` });
465
+ }
466
+ patch[key] = value;
467
+ touched = true;
468
+ }
469
+ if (!touched) {
470
+ return mcpResponse({ ok: false, error: "Provide at least one of: admins, contributors, readers (each an array of actor names)." });
471
+ }
472
+ let warning;
473
+ if (project) {
474
+ const err = validateProject(project);
475
+ if (err)
476
+ return mcpResponse({ ok: false, error: err });
477
+ warning = checkProjectRegistered(phrenPath, project) ?? undefined;
478
+ }
479
+ const written = setAccessRoles(phrenPath, patch, project);
480
+ return mcpResponse({
481
+ ok: true,
482
+ message: project
483
+ ? (warning
484
+ ? `Access roles updated for project "${project}". WARNING: ${warning}`
485
+ : `Access roles updated for project "${project}".`)
486
+ : "Access roles updated.",
487
+ data: { ...(project ? { project } : {}), ...written, ...(warning ? { warning } : {}) },
488
+ });
489
+ }
454
490
  // ── index ─────────────────────────────────────────────────────
455
491
  case "index": {
456
492
  const { includeGlobs, excludeGlobs, includeHidden } = settings;
@@ -560,11 +596,12 @@ export function register(server, ctx) {
560
596
  "and set_topic_config. When project is provided, writes to that project's phren.project.yaml " +
561
597
  "instead of global .config/.",
562
598
  inputSchema: z.object({
563
- domain: z.enum(["proactivity", "taskMode", "findingSensitivity", "retention", "workflow", "index", "topic"]),
599
+ domain: z.enum(["proactivity", "taskMode", "findingSensitivity", "retention", "workflow", "access", "index", "topic"]),
564
600
  settings: z.record(z.string(), z.unknown()).describe("Domain-specific settings. proactivity: { level, scope? } | taskMode: { mode } | " +
565
601
  "findingSensitivity: { level } | retention: { ttlDays?, retentionDays?, autoAcceptThreshold?, " +
566
602
  "minInjectConfidence?, decay? } | workflow: { lowConfidenceThreshold?, riskySections?, taskMode?, " +
567
- "findingSensitivity? } | index: { includeGlobs?, excludeGlobs?, includeHidden? } | " +
603
+ "findingSensitivity? } | access: { admins?, contributors?, readers? } (each an array of actor names) | " +
604
+ "index: { includeGlobs?, excludeGlobs?, includeHidden? } | " +
568
605
  "topic: { topics, domain? }"),
569
606
  project: z.string().optional().describe("Project name. When provided, writes to that project's phren.project.yaml instead of global .config/. " +
570
607
  "Required for the 'topic' domain."),
@@ -130,6 +130,9 @@ async function handleAddFinding(ctx, params) {
130
130
  });
131
131
  }
132
132
  }
133
+ const normalizedScope = normalizeMemoryScope(scope ?? "shared");
134
+ if (!normalizedScope)
135
+ return mcpResponse({ ok: false, error: `Invalid scope: "${scope}". Use lowercase letters/numbers with '-' or '_' (max 64 chars), e.g. "researcher".` });
133
136
  if (Array.isArray(finding)) {
134
137
  const findings = finding;
135
138
  if (findings.length > 100)
@@ -183,9 +186,6 @@ async function handleAddFinding(ctx, params) {
183
186
  }
184
187
  if (finding.length > 5000)
185
188
  return mcpResponse({ ok: false, error: "Finding text exceeds 5000 character limit." });
186
- const normalizedScope = normalizeMemoryScope(scope ?? "shared");
187
- if (!normalizedScope)
188
- return mcpResponse({ ok: false, error: `Invalid scope: "${scope}". Use lowercase letters/numbers with '-' or '_' (max 64 chars), e.g. "researcher".` });
189
189
  return withWriteQueue(async () => {
190
190
  try {
191
191
  const taggedFinding = applyFindingTypePrefix(finding, findingType);
@@ -629,10 +629,7 @@ export function register(server, ctx) {
629
629
  " Optionally classify with findingType: decision, pitfall, pattern, tradeoff, architecture, or bug.",
630
630
  inputSchema: z.object({
631
631
  project: z.string().describe("Project name (must match a directory in your phren store)."),
632
- finding: z.union([
633
- z.string().describe("A single insight, written as a bullet point."),
634
- z.array(z.string()).describe("Multiple insights to record in one call."),
635
- ]).describe("The insight(s) to save. Pass a string for one finding, or an array for bulk."),
632
+ finding: z.preprocess((v) => (typeof v === "string" ? [v] : v), z.array(z.string()).min(1)).describe("The insight(s) to save. Always pass as an array of strings — use a single-element array for one finding."),
636
633
  citation: z.object({
637
634
  file: z.string().optional().describe("Source file path that supports this finding."),
638
635
  line: z.number().int().positive().optional().describe("1-based line number in file."),
@@ -717,10 +714,7 @@ export function register(server, ctx) {
717
714
  " Pass a single string or an array of strings.",
718
715
  inputSchema: z.object({
719
716
  project: z.string().describe("Project name."),
720
- finding: z.union([
721
- z.string().describe("Partial text to match against existing findings."),
722
- z.array(z.string()).describe("List of partial texts to match and remove."),
723
- ]).describe("Text(s) to match and remove. Pass a string for one, or an array for bulk."),
717
+ finding: z.preprocess((v) => (typeof v === "string" ? [v] : v), z.array(z.string()).min(1)).describe("Text(s) to match and remove. Always pass as an array of strings — use a single-element array for one."),
724
718
  }),
725
719
  }, (params) => handleRemoveFinding(ctx, params));
726
720
  server.registerTool("push_changes", {
@@ -11,7 +11,8 @@ import { debugLog, runtimeFile, DOC_TYPES, FINDING_TAGS, isMemoryScopeVisible, n
11
11
  import { FINDING_LIFECYCLE_STATUSES, parseFindingLifecycle, } from "../shared/content.js";
12
12
  import { decodeStringRow, queryRows, queryDocRows, queryFragmentLinks, logFragmentMiss, extractSnippet, queryDocBySourceKey, normalizeMemoryId, } from "../shared/index.js";
13
13
  import { runCustomHooks } from "../hooks.js";
14
- import { entryScoreKey, getQualityMultiplier, getRetentionPolicy } from "../shared/governance.js";
14
+ import { entryScoreKey, getQualityMultiplier, getRetentionPolicy, recordLookupEvents } from "../shared/governance.js";
15
+ import { bestFindingNodeId } from "../finding-graph-id.js";
15
16
  import { callLlm } from "../content/dedup.js";
16
17
  import { rankResults, searchKnowledgeRows, applyTrustFilter, searchFederatedStores } from "../shared/retrieval.js";
17
18
  import { formatActorAttribution, parseScopeComment, parseSourceComment } from "../content/citation.js";
@@ -378,6 +379,32 @@ async function handleSearchKnowledge(ctx, { query, limit, project, type, tag, si
378
379
  ...(federationSource ? { federation_source: federationSource } : {}),
379
380
  };
380
381
  });
382
+ // Live activity: record each memory this search landed on so the web UI and
383
+ // VS Code extension can surface lookups in real time. Best-effort only.
384
+ try {
385
+ const at = new Date().toISOString();
386
+ recordLookupEvents(phrenPath, results.map((r, i) => {
387
+ // For findings, resolve the specific finding node so phren can walk
388
+ // to it on the graph; otherwise the project node is used downstream.
389
+ const nodeId = r.type === "findings"
390
+ ? bestFindingNodeId(r.project, rows[i]?.content ?? "", query)
391
+ : null;
392
+ return {
393
+ at,
394
+ query,
395
+ project: r.project,
396
+ filename: r.filename,
397
+ type: r.type,
398
+ path: r.path,
399
+ snippet: r.snippet,
400
+ source: "search",
401
+ ...(nodeId ? { nodeId } : {}),
402
+ };
403
+ }));
404
+ }
405
+ catch (err) {
406
+ debugLog(`search_knowledge lookup-events: ${errorMessage(err)}`);
407
+ }
381
408
  let relatedFragments = [];
382
409
  try {
383
410
  const terms = query.toLowerCase().split(/\s+/).filter(t => t.length > 2);
@@ -203,10 +203,7 @@ export function register(server, ctx) {
203
203
  description: "Append one or more tasks to a project's tasks.md file. Adds to the Queue section. Pass a single string or an array of strings.",
204
204
  inputSchema: z.object({
205
205
  project: z.string().describe("Project name (must match a directory in your phren)."),
206
- item: z.union([
207
- z.string().describe("A single task to add."),
208
- z.array(z.string()).describe("Multiple tasks to add in one call."),
209
- ]).describe("The task(s) to add. Pass a string for one task, or an array for bulk."),
206
+ item: z.preprocess((v) => (typeof v === "string" ? [v] : v), z.array(z.string()).min(1)).describe("The task(s) to add. Always pass as an array of strings — use a single-element array for one task."),
210
207
  scope: z.string().optional().describe("Optional memory scope label. Defaults to 'shared'. Example: 'researcher' or 'builder'."),
211
208
  }),
212
209
  }, async ({ project: projectInput, item, scope }) => {
@@ -253,10 +250,7 @@ export function register(server, ctx) {
253
250
  description: "Move one or more tasks to the Done section by matching text. Pass a single string or an array of strings.",
254
251
  inputSchema: z.object({
255
252
  project: z.string().describe("Project name."),
256
- item: z.union([
257
- z.string().describe("Exact or partial text of the item to complete."),
258
- z.array(z.string()).describe("List of partial item texts to complete."),
259
- ]).describe("The task(s) to complete. Pass a string for one, or an array for bulk."),
253
+ item: z.preprocess((v) => (typeof v === "string" ? [v] : v), z.array(z.string()).min(1)).describe("The task(s) to complete. Always pass as an array of strings — use a single-element array for one."),
260
254
  sessionId: z.string().optional().describe("Optional session ID from session_start. Pass this to track per-session task completion metrics."),
261
255
  }),
262
256
  }, async ({ project: projectInput, item, sessionId }) => {
@@ -324,10 +318,7 @@ export function register(server, ctx) {
324
318
  description: "Remove one or more tasks from a project's tasks.md file by matching text or ID. Pass a single string or an array of strings.",
325
319
  inputSchema: z.object({
326
320
  project: z.string().describe("Project name."),
327
- item: z.union([
328
- z.string().describe("Exact or partial text of the task, or a task ID like A1/Q3/D2."),
329
- z.array(z.string()).describe("List of partial item texts or IDs to remove."),
330
- ]).describe("The task(s) to remove. Pass a string for one, or an array for bulk."),
321
+ item: z.preprocess((v) => (typeof v === "string" ? [v] : v), z.array(z.string()).min(1)).describe("The task(s) to remove. Always pass as an array of strings (or task IDs like A1/Q3/D2) — use a single-element array for one."),
331
322
  }),
332
323
  }, async ({ project: projectInput, item }) => {
333
324
  const resolved = resolveStoreForProject(ctx, projectInput);
package/dist/ui/data.d.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  import type { SqlJsDatabase } from "../shared/index.js";
2
+ import { type LookupEvent } from "../governance/activity.js";
2
3
  interface EntryScore {
3
4
  impressions: number;
4
5
  helpful: number;
@@ -108,6 +109,7 @@ export declare function buildGraph(phrenPath: string, profile?: string, focusPro
108
109
  topics: GraphTopicMeta[];
109
110
  }>;
110
111
  export declare function recentUsage(phrenPath: string): string[];
112
+ export declare function recentLookups(phrenPath: string, limit?: number): LookupEvent[];
111
113
  export declare function recentAccepted(phrenPath: string): string[];
112
114
  export declare function collectProjectsForUI(phrenPath: string, profile?: string): ProjectInfo[];
113
115
  export {};
package/dist/ui/data.js CHANGED
@@ -14,6 +14,8 @@ import { FINDINGS_FILENAME } from "../data/access.js";
14
14
  import { buildIndex, queryDocBySourceKey, queryRows } from "../shared/index.js";
15
15
  import { readProjectTopics, classifyTopicForText } from "../project-topics.js";
16
16
  import { entryScoreKey } from "../governance/scores.js";
17
+ import { findingStableId } from "../finding-graph-id.js";
18
+ import { readRecentLookups } from "../governance/activity.js";
17
19
  import { logger } from "../logger.js";
18
20
  function extractGithubUrl(content) {
19
21
  const match = content.match(/https?:\/\/github\.com\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+/);
@@ -262,7 +264,7 @@ export async function buildGraph(phrenPath, profile, focusProject, existingDb) {
262
264
  continue;
263
265
  const topic = classifyTopicForText(`[${currentHeadingTag}] ${text}`, projectTopics);
264
266
  const scoreKey = entryScoreKey(project, FINDINGS_FILENAME, `[${currentHeadingTag}] ${text}`);
265
- const nodeId = stableId("finding", scoreKey);
267
+ const nodeId = findingStableId(scoreKey);
266
268
  taggedCount++;
267
269
  nodes.push({
268
270
  id: nodeId,
@@ -297,7 +299,7 @@ export async function buildGraph(phrenPath, profile, focusProject, existingDb) {
297
299
  // Classify the finding using the project's topic system
298
300
  const topic = classifyTopicForText(`[${tag}] ${text}`, projectTopics);
299
301
  const scoreKey = entryScoreKey(project, FINDINGS_FILENAME, `[${tag}] ${text}`);
300
- const nodeId = stableId("finding", scoreKey);
302
+ const nodeId = findingStableId(scoreKey);
301
303
  taggedCount++;
302
304
  nodes.push({
303
305
  id: nodeId,
@@ -332,7 +334,7 @@ export async function buildGraph(phrenPath, profile, focusProject, existingDb) {
332
334
  // Classify using dynamic topics
333
335
  const topic = classifyTopicForText(text, projectTopics);
334
336
  const scoreKey = entryScoreKey(project, FINDINGS_FILENAME, text);
335
- const nodeId = stableId("finding", scoreKey);
337
+ const nodeId = findingStableId(scoreKey);
336
338
  untaggedAdded++;
337
339
  nodes.push({
338
340
  id: nodeId,
@@ -558,6 +560,9 @@ export function recentUsage(phrenPath) {
558
560
  const lines = fs.readFileSync(usage, "utf8").trim().split("\n").filter(Boolean);
559
561
  return lines.slice(-40).reverse();
560
562
  }
563
+ export function recentLookups(phrenPath, limit = 40) {
564
+ return readRecentLookups(phrenPath, limit);
565
+ }
561
566
  export function recentAccepted(phrenPath) {
562
567
  const audit = path.join(runtimeDir(phrenPath), "audit.log");
563
568
  if (!fs.existsSync(audit))
package/dist/ui/graph.js CHANGED
@@ -34,6 +34,8 @@ export function renderGraphScript() {
34
34
  onSelectionClear: function() {},
35
35
  clearSelection: function() {},
36
36
  selectNode: function() { return false; },
37
+ focusNode: function() { return false; },
38
+ walkTo: function() { return false; },
37
39
  getNodeAt: function() { return null; },
38
40
  getNodeDetail: function() { return null; },
39
41
  destroy: function() {}
package/dist/ui/page.js CHANGED
@@ -1,8 +1,8 @@
1
1
  import { WEB_UI_STYLES, renderWebUiScript } from "./assets.js";
2
2
  import { renderGraphScript } from "./graph.js";
3
- import { PROJECT_REFERENCE_UI_STYLES, REVIEW_UI_STYLES, SETTINGS_TAB_UI_STYLES, TASK_UI_STYLES } from "./styles.js";
3
+ import { LAYOUT_VIEWPORT_STYLES, PROJECT_REFERENCE_UI_STYLES, REVIEW_UI_STYLES, SETTINGS_TAB_UI_STYLES, TASK_UI_STYLES } from "./styles.js";
4
4
  import { PHREN_DEEP_VOID_STYLES } from "./deep-void.js";
5
- import { renderSharedWebUiHelpers, renderSkillUiEnhancementScript, renderProfileSwitcherScript, renderProjectReferenceEnhancementScript, renderTasksAndSettingsScript, renderReviewQueueKeyboardScript, renderSearchScript, renderEventWiringScript, renderGraphHostScript, } from "./scripts.js";
5
+ import { renderSharedWebUiHelpers, renderSkillUiEnhancementScript, renderProfileSwitcherScript, renderProjectReferenceEnhancementScript, renderTasksAndSettingsScript, renderReviewQueueKeyboardScript, renderSearchScript, renderEventWiringScript, renderGraphHostScript, renderActivityStreamScript, renderGraphWalkScript, } from "./scripts.js";
6
6
  function h(s) {
7
7
  return s
8
8
  .replace(/&/g, "&")
@@ -27,6 +27,7 @@ ${SETTINGS_TAB_UI_STYLES}
27
27
  ${TASK_UI_STYLES}
28
28
  ${REVIEW_UI_STYLES}
29
29
  ${PHREN_DEEP_VOID_STYLES}
30
+ ${LAYOUT_VIEWPORT_STYLES}
30
31
  </style>
31
32
  </head>
32
33
  <body>
@@ -106,6 +107,7 @@ ${PHREN_DEEP_VOID_STYLES}
106
107
  <nav class="nav">
107
108
  <button class="nav-item active" data-tab="projects">Projects</button>
108
109
  <button class="nav-item" data-tab="review">Review</button>
110
+ <button class="nav-item" data-tab="activity">Activity</button>
109
111
  <button class="nav-item" data-tab="search">Search</button>
110
112
  <button class="nav-item" data-tab="graph">Graph</button>
111
113
  <button class="nav-item" data-tab="tasks">Tasks</button>
@@ -171,6 +173,35 @@ ${PHREN_DEEP_VOID_STYLES}
171
173
  </div>
172
174
  </div>
173
175
 
176
+ <!-- ── Activity Tab ──────────────────────────────────────── -->
177
+ <div id="tab-activity" class="tab-content">
178
+ <style>
179
+ .activity-led{display:inline-block;width:10px;height:10px;border-radius:50%;background:var(--muted);flex:0 0 auto}
180
+ .activity-led-ok{background:var(--success);box-shadow:0 0 0 0 var(--success-dim);animation:activity-pulse 2s infinite}
181
+ .activity-led-warn{background:var(--warning)}
182
+ .activity-led-err{background:var(--danger)}
183
+ @keyframes activity-pulse{0%{box-shadow:0 0 0 0 var(--success-glow,rgba(16,185,129,.35))}70%{box-shadow:0 0 0 7px rgba(16,185,129,0)}100%{box-shadow:0 0 0 0 rgba(16,185,129,0)}}
184
+ .activity-feed{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:8px}
185
+ .activity-item{border:1px solid var(--border);border-radius:var(--radius-sm);padding:10px 12px;background:var(--surface);transition:background .6s ease,border-color .6s ease}
186
+ .activity-item-new{background:var(--accent-dim);border-color:var(--accent)}
187
+ .activity-row{display:flex;align-items:center;gap:8px}
188
+ .activity-type{font-size:var(--text-xs);text-transform:uppercase;letter-spacing:.04em;color:var(--accent);border:1px solid var(--border);border-radius:999px;padding:1px 8px;flex:0 0 auto}
189
+ .activity-loc{font-family:var(--mono);font-size:var(--text-sm);color:var(--ink);overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
190
+ .activity-time{margin-left:auto;font-size:var(--text-xs);color:var(--muted);flex:0 0 auto}
191
+ .activity-query{font-size:var(--text-sm);color:var(--ink-secondary);margin-top:4px}
192
+ .activity-snippet{font-size:var(--text-sm);color:var(--muted);margin-top:4px;overflow:hidden;text-overflow:ellipsis;display:-webkit-box;-webkit-line-clamp:2;-webkit-box-orient:vertical}
193
+ </style>
194
+ <div style="max-width:860px;margin:0 auto">
195
+ <div style="display:flex;align-items:center;gap:10px;margin-bottom:6px">
196
+ <span id="activity-led" class="activity-led" title="Live status"></span>
197
+ <h2 style="font-size:var(--text-lg);font-weight:600;margin:0">Live Lookups</h2>
198
+ <span id="activity-status" class="text-muted" style="font-size:var(--text-sm);margin-left:auto">Connecting…</span>
199
+ </div>
200
+ <p class="text-muted" style="font-size:var(--text-sm);margin:0 0 16px 0">Memories phren lands on as it searches, streamed in real time.</p>
201
+ <ul id="activity-feed" class="activity-feed"><li style="color:var(--muted);list-style:none">Waiting for lookups…</li></ul>
202
+ </div>
203
+ </div>
204
+
174
205
  <!-- ── Search Tab ────────────────────────────────────────── -->
175
206
  <div id="tab-search" class="tab-content">
176
207
  <div style="max-width:720px;margin:0 auto">
@@ -321,6 +352,12 @@ ${PHREN_DEEP_VOID_STYLES}
321
352
  <div id="settings-workflow" style="color:var(--muted)">Loading...</div>
322
353
  </div>
323
354
  </section>
355
+ <section class="settings-section" style="border-top:3px solid color-mix(in srgb, var(--danger, var(--warning)) 45%, var(--border))">
356
+ <div class="settings-section-header">Access Control</div>
357
+ <div class="settings-section-body">
358
+ <div id="settings-access" style="color:var(--muted)">Loading...</div>
359
+ </div>
360
+ </section>
324
361
  <section class="settings-section" style="border-top:3px solid color-mix(in srgb, var(--cyan) 45%, var(--border))">
325
362
  <div class="settings-section-header">Index Policy</div>
326
363
  <div class="settings-section-body">
@@ -380,6 +417,12 @@ ${renderTasksAndSettingsScript(authToken || "")}
380
417
  ${renderReviewQueueKeyboardScript(authToken || "")}
381
418
  </script>
382
419
  <script${nonceAttr}>
420
+ ${renderActivityStreamScript(authToken || "")}
421
+ </script>
422
+ <script${nonceAttr}>
423
+ ${renderGraphWalkScript()}
424
+ </script>
425
+ <script${nonceAttr}>
383
426
  ${renderSearchScript(authToken || "")}
384
427
  </script>
385
428
  <script${nonceAttr}>
@@ -15,3 +15,16 @@ export declare function renderSearchScript(authToken: string): string;
15
15
  export declare function renderEventWiringScript(): string;
16
16
  export declare function renderGraphHostScript(): string;
17
17
  export declare function renderReviewQueueKeyboardScript(_authToken: string): string;
18
+ /**
19
+ * Live "Activity" tab: streams memory lookups from /api/lookups/stream (SSE)
20
+ * and prepends them to #activity-feed in real time, so you can watch phren land
21
+ * on memories as it searches. Falls back gracefully if EventSource is missing.
22
+ */
23
+ export declare function renderActivityStreamScript(_authToken: string): string;
24
+ /**
25
+ * Drives the graph mascot from the live lookup feed: each 'phren:lookup' event
26
+ * (dispatched by the activity stream) maps to a graph node and sends phren
27
+ * walking to it, so you can watch phren traverse the knowledge graph in real
28
+ * time. No-ops gracefully until the graph is mounted (Graph tab opened).
29
+ */
30
+ export declare function renderGraphWalkScript(): string;