fuli-context 0.7.4-beta.2 → 0.7.5

package/graph-provider/pyproject.toml

@@ -1,11 +1,12 @@
 [project]
 name = "fuli-graph-provider"
-version = "0.7.4b1"
+version = "0.7.5"
 description = "Graphiti-backed personal and shared project provider for Fuli."
 requires-python = ">=3.12"
 dependencies = [
   "fastapi==0.116.1",
   "graphiti-core==0.29.2",
+  "openai>=1.91,<2",
   "pydantic-settings==2.10.1",
   "uvicorn[standard]==0.35.0",
 ]

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "fuli-context",
-  "version": "0.7.4-beta.2",
+  "version": "0.7.5",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "fuli-context",
-      "version": "0.7.4-beta.2",
+      "version": "0.7.5",
       "license": "Apache-2.0",
       "dependencies": {
         "@hono/node-server": "2.0.12",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fuli-context",
-  "version": "0.7.4-beta.2",
+  "version": "0.7.5",
   "description": "Local-first collaboration relationship graph for AI agents.",
   "type": "module",
   "files": [
@@ -9,6 +9,7 @@
     "src/",
     "dist/web/",
     "docs/external-knowledge-architecture.md",
+    "docs/public-personal-architecture.md",
     "examples/external-knowledge/markdown-folder.mjs",
     "graph-provider/Dockerfile",
     "graph-provider/pyproject.toml",

package/skills/capturing-session-knowledge/SKILL.md

@@ -213,6 +213,45 @@ lowers ranking and marks the item for attention without deleting its history. Ag
 must not demote human/source-confirmed knowledge; authoritative contradiction may require review
 or demotion under the Provider policy.
 
+## Coordinate Project Agents
+
+Use a project Agent team only when the user requests delegation or the host's active delegation
+policy authorizes it and the task has independently verifiable work. Keep one primary coordinator
+responsible for decisions, integration, and final verification. Do not split a small or tightly
+coupled task merely to create more workers.
+
+For an eligible task, call `coordinate_project_agent_task` once with the exact current
+`projectPath`, one stable idempotency key, an explicit complexity hint when known, and focused
+context queries. Enable its parallel plan only when there are at least two conflict-free
+workstreams with independent verification; state each workstream boundary. The Provider chooses
+the lead and collaborators from active project assignments, preferring Agents with relevant
+project history. Explicit user-selected Agents and locked policies remain higher priority.
+
+Treat the returned durable Agent identity and a host worker as different things. A durable Agent
+keeps its project assignment, preferences, task history, and Agent-scoped graph memory while idle;
+the host creates an execution process only when needed. Start only entries in `worker_plan`, give
+each worker only its returned isolated `context`, role, and workstream boundary, and never expose
+another Agent's private context. Fuli is the control plane and does not itself prove that a native
+worker started.
+
+The host adapter must keep an adaptive-runtime graph lease for the whole worker run, and an
+executor lease when Fuli manages that executor. Call `acquire_runtime_lease` before starting
+workers; its MCP process keeps the heartbeat alive. Call `release_runtime_lease` in a `finally`
+path after all results and terminal events are recorded. Record queued/running and terminal state
+with `record_project_agent_task_activity`,
+including concrete worker identity. Call `record_project_agent_executor_actual` only after real
+executor/model use. If the host cannot start a worker, report the task as blocked or failed and do
+not fabricate an execution-summary row. The Provider's `executionSummary` remains authoritative.
+
+## Report Actual Worker Execution
+
+When a FULI task or task view returns a non-empty Provider `executionSummary`, append one row per worker.
+Include the worker label and occupation emoji, actual executor and `sourceApplication` environment,
+work summary, and `workerStatus`/terminal status. This applies only to Provider-reported actual workers.
+When empty `executionSummary` is returned, omit rows; an absent `executionSummary` also omits rows.
+Configured, allowed, or available clients/executors are not evidence of actual use. Keep this
+Agent-agnostic; client-specific details and work-kind routing remain at adapter boundaries.
+
 ## Classify Knowledge State
 
 Every entity and relationship needs an `originQuadrant`, `confirmationBasis`, and
@@ -254,8 +293,10 @@ confirmation time. Legacy items without that audit record are `pending`, even if
 for new product logic and do not treat them as confirmation evidence.
 
 Agent retrieval includes pending items on demand and returns their status so the caller can
-calibrate claims. Only user or authoritative-source `confirmed` project knowledge may enter
-public review, regardless of how it was originally discovered; normal personal preview and
+calibrate claims. Only project knowledge whose immutable discovery-time `originQuadrant` is
+`known_known` and whose status is user or authoritative-source `confirmed` may enter public
+review. Knowledge first discovered as `known_unknown`, `unknown_known`, or `unknown_unknown`
+remains in the personal graph even if it is later confirmed; normal personal preview and
 Maintainer review gates still apply.
 
 ## Grow The Personal Profile Separately

package/src/adaptive-runtime/executor-pool.js

@@ -0,0 +1,127 @@
+export function createExecutorPool({
+  adapters = new Map(),
+  idleMs,
+  setTimer = setTimeout,
+  clearTimer = clearTimeout
+}) {
+  const entries = new Map();
+  let closed = false;
+
+  async function acquire(executorId, leaseId) {
+    assertExecutorId(executorId);
+    if (closed) throw new Error('Executor pool is closed');
+    const entry = entryFor(executorId);
+    if (entry.timer) {
+      clearTimer(entry.timer);
+      entry.timer = null;
+    }
+    entry.leases.add(leaseId);
+    if (!entry.adapter) {
+      entry.stage = 'external';
+      return snapshotEntry(executorId, entry);
+    }
+    await exclusive(entry, async () => {
+      if (entry.stage !== 'running') {
+        entry.stage = 'starting';
+        try {
+          await entry.adapter.start({ executorId });
+          entry.stage = 'running';
+          entry.lastError = null;
+        } catch (error) {
+          entry.leases.delete(leaseId);
+          entry.stage = 'failed';
+          entry.lastError = errorMessage(error);
+          throw error;
+        }
+      }
+    });
+    return snapshotEntry(executorId, entry);
+  }
+
+  function release(executorId, leaseId) {
+    const entry = entries.get(executorId);
+    if (!entry) return;
+    entry.leases.delete(leaseId);
+    if (!entry.adapter || entry.leases.size > 0 || entry.timer || closed) return;
+    entry.timer = setTimer(() => {
+      entry.timer = null;
+      if (entry.leases.size > 0 || closed) return;
+      void exclusive(entry, async () => {
+        if (entry.leases.size > 0 || closed) return;
+        await stopEntry(executorId, entry);
+      });
+    }, idleMs);
+    entry.timer?.unref?.();
+  }
+
+  async function stopEntry(executorId, entry) {
+    entry.stage = 'stopping';
+    try {
+      await entry.adapter.stop({ executorId });
+      entry.stage = 'idle';
+      entry.lastError = null;
+    } catch (error) {
+      entry.stage = 'failed';
+      entry.lastError = errorMessage(error);
+    }
+  }
+
+  function status() {
+    return [...entries.entries()].map(([executorId, entry]) =>
+      snapshotEntry(executorId, entry));
+  }
+
+  function close() {
+    closed = true;
+    for (const entry of entries.values()) {
+      if (entry.timer) clearTimer(entry.timer);
+      entry.timer = null;
+    }
+  }
+
+  function entryFor(executorId) {
+    let entry = entries.get(executorId);
+    if (!entry) {
+      entry = {
+        adapter: adapters.get(executorId) ?? null,
+        leases: new Set(),
+        timer: null,
+        transition: Promise.resolve(),
+        stage: adapters.has(executorId) ? 'idle' : 'external',
+        lastError: null
+      };
+      entries.set(executorId, entry);
+    }
+    return entry;
+  }
+
+  return { acquire, release, status, close };
+}
+
+function exclusive(entry, operation) {
+  const result = entry.transition.then(operation, operation);
+  entry.transition = result.catch(() => {});
+  return result;
+}
+
+function snapshotEntry(executorId, entry) {
+  return {
+    executorId,
+    managed: Boolean(entry.adapter),
+    stage: entry.stage,
+    activeLeaseCount: entry.leases.size,
+    lastError: entry.lastError
+  };
+}
+
+function assertExecutorId(value) {
+  if (typeof value !== 'string' || !value.trim() || value.length > 200) {
+    throw new TypeError('executorId must be non-empty text with at most 200 characters');
+  }
+}
+
+function errorMessage(error) {
+  return String(error instanceof Error ? error.message : error)
+    .replace(/[\r\n\t]+/g, ' ')
+    .slice(0, 500);
+}

package/src/adaptive-runtime/graph-services.js

@@ -0,0 +1,166 @@
+import { readJsonFile } from '../storage/json-file.js';
+import { createNativeGraphServices } from '../native-runtime/runtime.js';
+import {
+  ensureContainerRuntime,
+  runDockerCompose
+} from '../setup/container-runtime.js';
+import {
+  DEFAULT_RUNTIME_SETTINGS,
+  managedProviderUrls,
+  readRuntimeSettings
+} from '../system/runtime-settings.js';
+
+const PERSONAL_SERVICES = Object.freeze({
+  providers: ['personal-provider'],
+  databases: ['personal-neo4j']
+});
+const WORKSPACE_SERVICES = Object.freeze({
+  providers: ['workspace-provider'],
+  databases: ['workspace-neo4j']
+});
+
+export function createGraphServices({
+  paths,
+  readSettings = readRuntimeSettings,
+  createContainerServices = createManagedGraphServices,
+  createNativeServices = createNativeGraphServices
+}) {
+  const settings = paths.runtimeSettingsPath
+    ? readSettings(paths.runtimeSettingsPath)
+    : DEFAULT_RUNTIME_SETTINGS;
+  return settings.graphRuntimeMode === 'native'
+    ? createNativeServices({ paths })
+    : createContainerServices({ paths });
+}
+
+export function createManagedGraphServices({
+  paths,
+  readJson = readJsonFile,
+  readSettings = readRuntimeSettings,
+  ensureRuntime = ensureContainerRuntime,
+  runCompose = runDockerCompose,
+  fetchImpl = globalThis.fetch,
+  wait = delay,
+  onProgress = () => {}
+}) {
+  let containerRuntime = null;
+
+  async function runtime() {
+    if (containerRuntime?.status === 'ready') return containerRuntime;
+    containerRuntime = await ensureRuntime({ onProgress });
+    return containerRuntime;
+  }
+
+  function managedServices() {
+    const state = readJson(paths.graphRuntimeStatePath, null);
+    const config = readJson(paths.graphRuntimeConfigPath, null);
+    const workspace = state?.managedProviders?.includes('development-workspace') ||
+      (config?.workspaces ?? []).some(isManagedWorkspace);
+    return {
+      providers: [
+        ...PERSONAL_SERVICES.providers,
+        ...(workspace ? WORKSPACE_SERVICES.providers : [])
+      ],
+      databases: [
+        ...PERSONAL_SERVICES.databases,
+        ...(workspace ? WORKSPACE_SERVICES.databases : [])
+      ],
+      providerUrls: providerUrls(config, paths, readSettings, workspace)
+    };
+  }
+
+  async function start() {
+    const services = managedServices();
+    compose([
+      'up', '-d', '--no-build',
+      ...services.databases,
+      ...services.providers
+    ], await runtime());
+    for (const url of services.providerUrls) await waitForProvider(url, fetchImpl, wait);
+  }
+
+  async function stopProviders() {
+    const services = managedServices();
+    compose(['stop', '-t', '20', ...services.providers], await runtime());
+  }
+
+  async function stopDatabases() {
+    const services = managedServices();
+    // Keep shutdown ordering explicit even if an external action restarted a Provider.
+    compose(['stop', '-t', '20', ...services.providers], await runtime());
+    compose(['stop', '-t', '20', ...services.databases], await runtime());
+  }
+
+  async function ready() {
+    const services = managedServices();
+    const checks = await Promise.all(services.providerUrls.map((url) =>
+      providerReady(url, fetchImpl)));
+    return checks.every(Boolean);
+  }
+
+  function compose(action, selectedRuntime) {
+    runCompose([
+      'compose',
+      '--env-file', paths.graphEnvPath,
+      '-f', paths.graphComposePath,
+      ...action
+    ], selectedRuntime);
+  }
+
+  return { start, stopProviders, stopDatabases, ready };
+}
+
+function providerUrls(config, paths, readSettings, includesWorkspace) {
+  const settings = paths.runtimeSettingsPath
+    ? readSettings(paths.runtimeSettingsPath)
+    : DEFAULT_RUNTIME_SETTINGS;
+  const defaults = managedProviderUrls(settings);
+  const urls = [config?.personal?.providerUrl ?? defaults.personal];
+  if (!includesWorkspace) return urls;
+  const managed = (config?.workspaces ?? []).find(isManagedWorkspace);
+  return [...urls, managed?.providerUrl ?? defaults.workspace];
+}
+
+function isManagedWorkspace(workspace) {
+  if (workspace?.managedDevelopment === true) return true;
+  try {
+    const url = new URL(workspace?.providerUrl);
+    return url.protocol === 'http:' && isLoopback(url.hostname) && url.port === '8788';
+  } catch {
+    return false;
+  }
+}
+
+async function waitForProvider(url, fetchImpl, wait) {
+  for (let attempt = 0; attempt < 120; attempt += 1) {
+    try {
+      const response = await fetchImpl(`${String(url).replace(/\/$/, '')}/health`, {
+        signal: AbortSignal.timeout(2500)
+      });
+      if (response.ok) return;
+    } catch {
+      // Neo4j recovery and Provider index initialization can take a while after a cold wake.
+    }
+    if (attempt < 119) await wait(1000);
+  }
+  throw new Error('The managed graph Provider did not become ready after waking');
+}
+
+async function providerReady(url, fetchImpl) {
+  try {
+    const response = await fetchImpl(`${String(url).replace(/\/$/, '')}/health`, {
+      signal: AbortSignal.timeout(2500)
+    });
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+
+function isLoopback(hostname) {
+  return ['127.0.0.1', 'localhost', '::1', '[::1]'].includes(hostname);
+}
+
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}