@xingular/harness 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xingular/harness",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "description": "Xingular Harness \u2014 a Pi agent harness with multi-account sign-in, a compiled system prompt, a memory lifecycle (Wiki), tools, MCP, and skills",
   "exports": {

package/src/accounts/env.test.ts

@@ -0,0 +1,95 @@
+import { existsSync, lstatSync, linkSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, readlinkSync, symlinkSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { expect, test } from 'vitest'
+
+import { configDir, ensureSharedDir, linkSharedEntries, sharedDir, type EntryLinker } from './env'
+
+const temp = () => mkdtempSync(join(tmpdir(), 'harness-env-'))
+const refused = (code = 'EPERM') => Object.assign(new Error(`${code}: operation not permitted, symlink`), { code })
+const backups = (folder: string) => readdirSync(folder).filter((name) => name.includes('agentx-backup'))
+
+// A Windows account without the symlink privilege: file symlinks are refused, junctions and hard links work.
+const windowsLike: EntryLinker = {
+  symlink: (target, path, isDir) => {
+    if (!isDir) throw refused()
+    symlinkSync(target, path)
+  },
+  hardLink: (target, path) => linkSync(target, path)
+}
+
+const refusesAll: EntryLinker = {
+  symlink: () => {
+    throw refused()
+  },
+  hardLink: () => {
+    throw refused()
+  }
+}
+
+test('without the symlink privilege, files are hard-linked and folders are junctioned', () => {
+  const dir = temp()
+  const home = configDir(dir, { id: 'acc1' })
+  mkdirSync(home, { recursive: true })
+  writeFileSync(join(home, 'settings.json'), '{"theme":"dark"}')
+
+  const first = linkSharedEntries(dir, { id: 'acc1' }, windowsLike)
+  const shared = join(sharedDir(dir), 'settings.json')
+  expect(first.entries.find((entry) => entry.name === 'settings.json')).toEqual({ name: 'settings.json', state: 'linked' })
+  expect(lstatSync(join(home, 'settings.json')).ino).toBe(lstatSync(shared).ino)
+  expect(lstatSync(join(home, 'settings.json')).isSymbolicLink()).toBe(false)
+  expect(lstatSync(join(home, 'skills')).isSymbolicLink()).toBe(true)
+
+  // Entries with no shared copy yet cannot be hard-linked, so they stay the account's own.
+  expect(first.entries.find((entry) => entry.name === 'AGENTS.md')).toMatchObject({ state: 'unshared' })
+
+  // A second launch finds the links in place and moves nothing aside.
+  const second = linkSharedEntries(dir, { id: 'acc1' }, windowsLike)
+  expect(second.entries.find((entry) => entry.name === 'settings.json')?.state).toBe('linked')
+  expect(second.entries.find((entry) => entry.name === 'skills')?.state).toBe('linked')
+  expect(backups(home)).toEqual([])
+  expect(backups(sharedDir(dir))).toEqual([])
+  expect(readFileSync(join(home, 'settings.json'), 'utf8')).toBe('{"theme":"dark"}')
+})
+
+test('when links are refused, the account keeps its own settings', () => {
+  const dir = temp()
+  const home = configDir(dir, { id: 'acc1' })
+  mkdirSync(home, { recursive: true })
+  writeFileSync(join(home, 'settings.json'), '{"mine":true}')
+
+  const { entries } = linkSharedEntries(dir, { id: 'acc1' }, refusesAll)
+  expect(entries.find((entry) => entry.name === 'settings.json')).toEqual({ name: 'settings.json', state: 'unshared', reason: 'EPERM' })
+  expect(readFileSync(join(home, 'settings.json'), 'utf8')).toBe('{"mine":true}')
+  expect(existsSync(join(sharedDir(dir), 'settings.json'))).toBe(false)
+  expect(backups(home)).toEqual([])
+})
+
+test('when links are refused, a shared file the account lacks is copied in and stays put', () => {
+  const dir = temp()
+  writeFileSync(join(ensureSharedDir(dir), 'settings.json'), '{"shared":true}')
+  const home = configDir(dir, { id: 'acc2' })
+
+  const first = linkSharedEntries(dir, { id: 'acc2' }, refusesAll)
+  expect(readFileSync(join(home, 'settings.json'), 'utf8')).toBe('{"shared":true}')
+  expect(first.entries.find((entry) => entry.name === 'settings.json')?.state).toBe('unshared')
+
+  const second = linkSharedEntries(dir, { id: 'acc2' }, refusesAll)
+  expect(second.entries.find((entry) => entry.name === 'settings.json')?.state).toBe('unshared')
+  expect(readFileSync(join(home, 'settings.json'), 'utf8')).toBe('{"shared":true}')
+  expect(backups(home)).toEqual([])
+  expect(backups(sharedDir(dir))).toEqual([])
+})
+
+test('a refused link leaves the account\'s existing link as it was', () => {
+  const dir = temp()
+  const home = configDir(dir, { id: 'acc3' })
+  mkdirSync(home, { recursive: true })
+  const elsewhere = join(temp(), 'skills')
+  mkdirSync(elsewhere)
+  symlinkSync(elsewhere, join(home, 'skills'))
+
+  const { entries } = linkSharedEntries(dir, { id: 'acc3' }, refusesAll)
+  expect(entries.find((entry) => entry.name === 'skills')?.state).toBe('unshared')
+  expect(readlinkSync(join(home, 'skills'))).toBe(elsewhere)
+})

package/src/accounts/env.ts

@@ -3,11 +3,12 @@
 // variables are removed. A launch that would fall back to `~/.pi` is refused.
 //
 // Settings, skills, prompts, and instructions are shared by every account: the account's agent
-// folder links those entries to `_shared/pi/`. Credentials, sessions, and history stay in the
-// account's own folder.
-import { chmodSync, lstatSync, mkdirSync, readlinkSync, renameSync, symlinkSync, unlinkSync } from 'node:fs'
+// folder links those entries to `_shared/pi/`. Where the system refuses a link (Windows without
+// the symlink privilege), the entry stays the account's own, and a shared file is copied in so
+// its settings still load. Credentials, sessions, and history stay in the account's own folder.
+import { chmodSync, copyFileSync, linkSync, lstatSync, mkdirSync, readlinkSync, renameSync, rmdirSync, statSync, symlinkSync, unlinkSync, utimesSync } from 'node:fs'
 import { homedir } from 'node:os'
-import { basename, dirname, join, sep } from 'node:path'
+import { basename, dirname, join, resolve, sep } from 'node:path'
 
 import { HarnessError } from '../core/errors'
 import type { Account } from './store'
@@ -104,53 +105,178 @@ const modified = (path: string): number => {
   }
 }
 
-/** Moves a real file or folder aside so the shared link can take its place. */
-function backUp(path: string): void {
-  renameSync(path, join(dirname(path), `${basename(path)}.agentx-backup-${Math.floor(Date.now() / 1000)}`))
+/** Moves a real file or folder aside so the shared link can take its place; returns where it went. */
+function backUp(path: string): string {
+  const backup = join(dirname(path), `${basename(path)}.agentx-backup-${Math.floor(Date.now() / 1000)}`)
+  renameSync(path, backup)
+  return backup
 }
 
 /**
- * Links the account's shared entries to `_shared/pi/`. A real entry found in the account folder
- * (from before sharing, or a tool that replaced the link while saving) becomes the shared copy
- * when there is none or it is newer; otherwise it is kept as a backup.
+ * How one shared entry is linked into an account folder. Windows refuses a symbolic link to a
+ * user without the symlink privilege, so each kind has a fallback that needs none.
  */
-function linkShared(accountsDir: string, dir: string): void {
-  const shared = ensureSharedDir(accountsDir)
-  for (const [name, isDir] of SHARED_ENTRIES) {
-    const local = join(dir, name)
-    const target = join(shared, name)
-    let meta: ReturnType<typeof lstatSync> | null = null
-    try {
-      meta = lstatSync(local)
-    } catch {
-      meta = null
-    }
-    if (meta?.isSymbolicLink()) {
-      if (readlinkSync(local) === target) {
-        if (isDir) mkdirSync(target, { recursive: true })
-        continue
+export interface EntryLinker {
+  /** A symbolic link to a file, or a junction to a folder (junctions need no privilege on Windows). */
+  symlink(target: string, path: string, isDir: boolean): void
+  /** A hard link to a file on the same volume. */
+  hardLink(target: string, path: string): void
+}
+
+const nodeLinker: EntryLinker = {
+  symlink: (target, path, isDir) => symlinkSync(resolve(target), path, isDir ? 'junction' : 'file'),
+  hardLink: (target, path) => linkSync(target, path)
+}
+
+const codeOf = (error: unknown): string => (error as NodeJS.ErrnoException).code ?? String(error)
+const PRIVILEGE_CODES = ['EPERM', 'EACCES']
+
+function createLink(target: string, path: string, isDir: boolean, linker: EntryLinker): void {
+  try {
+    linker.symlink(target, path, isDir)
+  } catch (error) {
+    // A file can still be hard-linked without the privilege; a folder has no such fallback.
+    if (isDir || !PRIVILEGE_CODES.includes(codeOf(error))) throw error
+    linker.hardLink(target, path)
+  }
+}
+
+const isLink = (path: string): boolean => {
+  try {
+    return lstatSync(path).isSymbolicLink()
+  } catch {
+    return false
+  }
+}
+
+// Windows reports some link targets with the `\\?\` prefix.
+const LONG_PREFIX = /^\\\\\?\\/
+function samePath(a: string, b: string): boolean {
+  const normal = (path: string): string => {
+    const full = resolve(path.replace(LONG_PREFIX, ''))
+    return process.platform === 'win32' ? full.toLowerCase() : full
+  }
+  return normal(a) === normal(b)
+}
+
+/** A hard link is the same file on disk as its target, so it has the same device and inode. */
+function sameFile(a: string, b: string): boolean {
+  try {
+    const left = lstatSync(a)
+    const right = lstatSync(b)
+    return left.ino !== 0 && left.dev === right.dev && left.ino === right.ino
+  } catch {
+    return false
+  }
+}
+
+function isLinkTo(path: string, target: string, isDir: boolean): boolean {
+  try {
+    const meta = lstatSync(path)
+    if (meta.isSymbolicLink()) return samePath(readlinkSync(path), target)
+    return !isDir && meta.isFile() && sameFile(path, target)
+  } catch {
+    return false
+  }
+}
+
+/** Removes a link without touching what it points to. A Windows junction needs `rmdir`. */
+function removeLink(path: string, isDir: boolean): void {
+  try {
+    unlinkSync(path)
+  } catch (error) {
+    if (!isDir) throw error
+    rmdirSync(path)
+  }
+}
+
+/**
+ * A file the account does not have, for an entry whose link was refused: a copy of the shared one
+ * (with its time kept, so the newest-wins rule does not move it), so the account's settings load.
+ */
+function keepCopy(target: string, path: string, isDir: boolean): void {
+  if (isDir || present(path) || !present(target)) return
+  try {
+    copyFileSync(target, path)
+    const { atime, mtime } = statSync(target)
+    utimesSync(path, atime, mtime)
+  } catch {
+    // The account simply keeps no copy; its sign-in and its own files are not affected.
+  }
+}
+
+/** What happened to one shared entry: linked to the shared copy, or left as the account's own. */
+export interface SharedEntry {
+  name: string
+  state: 'linked' | 'unshared'
+  /** Why the link was refused, when it was. */
+  reason?: string
+}
+
+/**
+ * Links one entry to its shared copy. A real entry found in the account folder (from before
+ * sharing, or a tool that replaced the link while saving) becomes the shared copy when there is
+ * none or it is newer; otherwise it is kept as a backup. If the link is then refused, every move
+ * is undone, so the account keeps what it had.
+ */
+function linkOne(name: string, target: string, path: string, isDir: boolean, linker: EntryLinker): SharedEntry {
+  if (isLinkTo(path, target, isDir)) {
+    if (isDir) mkdirSync(target, { recursive: true })
+    return { name, state: 'linked' }
+  }
+  const undo: (() => void)[] = []
+  try {
+    if (isLink(path)) {
+      const previous = readlinkSync(path)
+      removeLink(path, isDir)
+      undo.push(() => nodeLinker.symlink(previous, path, isDir))
+    } else if (present(path)) {
+      if (!present(target)) {
+        renameSync(path, target)
+        undo.push(() => renameSync(target, path))
+      } else if (!isDir && modified(path) > modified(target)) {
+        const backup = backUp(target)
+        undo.push(() => renameSync(backup, target))
+        renameSync(path, target)
+        undo.push(() => renameSync(target, path))
+      } else {
+        const backup = backUp(path)
+        undo.push(() => renameSync(backup, path))
       }
-      unlinkSync(local)
-    } else if (meta) {
-      if (!present(target)) renameSync(local, target)
-      else if (!isDir && modified(local) > modified(target)) {
-        backUp(target)
-        renameSync(local, target)
-      } else backUp(local)
     }
     if (isDir) mkdirSync(target, { recursive: true })
-    symlinkSync(target, local)
+    createLink(target, path, isDir, linker)
+    return { name, state: 'linked' }
+  } catch (error) {
+    for (const step of undo.reverse()) {
+      try {
+        step()
+      } catch {
+        // The entry stays where that step left it; nothing further can be restored safely.
+      }
+    }
+    keepCopy(target, path, isDir)
+    return { name, state: 'unshared', reason: codeOf(error) }
   }
 }
 
-/** Creates the account's runtime folder and links the shared entries into it. */
-export function ensureHome(accountsDir: string, account: Pick<Account, 'id'>): string {
+/**
+ * Creates the account's runtime folder and links the shared entries into it. Never throws for a
+ * refused link: each entry is reported, and the account falls back to its own copy.
+ */
+export function linkSharedEntries(accountsDir: string, account: Pick<Account, 'id'>, linker: EntryLinker = nodeLinker): { dir: string; entries: SharedEntry[] } {
   makePrivate(join(accountsDir, account.id))
   makePrivate(homeDir(accountsDir, account.id))
   const dir = configDir(accountsDir, account)
   makePrivate(dir)
-  linkShared(accountsDir, dir)
-  return dir
+  const shared = ensureSharedDir(accountsDir)
+  const entries = SHARED_ENTRIES.map(([name, isDir]) => linkOne(name, join(shared, name), join(dir, name), isDir, linker))
+  return { dir, entries }
+}
+
+/** Creates the account's runtime folder and links the shared entries into it. */
+export function ensureHome(accountsDir: string, account: Pick<Account, 'id'>): string {
+  return linkSharedEntries(accountsDir, account).dir
 }
 
 const inside = (path: string, parent: string): boolean => path === parent || path.startsWith(parent.endsWith(sep) ? parent : `${parent}${sep}`)
@@ -166,16 +292,20 @@ export function assertIsolated(accountsDir: string, dir: string): void {
   }
 }
 
-/** Variables to set, or remove (`null`), when launching a session for this account. */
-export function launchEnv(accountsDir: string, account: Pick<Account, 'id'>, inherited: NodeJS.ProcessEnv = process.env): Record<string, string | null> {
-  const dir = ensureHome(accountsDir, account)
-  assertIsolated(accountsDir, dir)
+function sessionEnv(dir: string, inherited: NodeJS.ProcessEnv): Record<string, string | null> {
   const env: Record<string, string | null> = {}
   for (const name of inheritedCredentialVars(inherited)) env[name] = null
   env.PI_CODING_AGENT_DIR = dir
   return env
 }
 
+/** Variables to set, or remove (`null`), when launching a session for this account. */
+export function launchEnv(accountsDir: string, account: Pick<Account, 'id'>, inherited: NodeJS.ProcessEnv = process.env): Record<string, string | null> {
+  const dir = ensureHome(accountsDir, account)
+  assertIsolated(accountsDir, dir)
+  return sessionEnv(dir, inherited)
+}
+
 /** What a session needs to run for an account. */
 export interface AccountContext {
   id: string
@@ -185,10 +315,14 @@ export interface AccountContext {
   env: Record<string, string | null>
   /** The account's own agent folder. */
   configDir: string
+  /** Which shared entries are linked, and which the account keeps as its own. */
+  sharing: SharedEntry[]
 }
 
 export function accountContext(accountsDir: string, account: Account): AccountContext {
-  return { id: account.id, provider: 'pi', label: account.label, env: launchEnv(accountsDir, account), configDir: configDir(accountsDir, account) }
+  const { dir, entries } = linkSharedEntries(accountsDir, account)
+  assertIsolated(accountsDir, dir)
+  return { id: account.id, provider: 'pi', label: account.label, env: sessionEnv(dir, process.env), configDir: dir, sharing: entries }
 }
 
 /** The process environment for a `pi` process launched on behalf of this account. */

package/src/capabilities/api.ts

@@ -50,11 +50,11 @@ export async function resolve(harness: Harness, params: ListParams & { tools?: r
   }
 }
 
-export function toolIntersection(parent: CapabilitySet, assignee: CapabilitySet, taskTools: readonly string[] = []): CapabilitySet {
-  const permitted = new Set(taskTools.length ? taskTools : assignee.tools)
+export function toolIntersection(parent: CapabilitySet, assignee: CapabilitySet, taskTools?: readonly string[]): CapabilitySet {
+  const permitted = taskTools === undefined ? null : new Set(taskTools)
   return {
     version: 1,
-    tools: parent.tools.filter((tool) => assignee.tools.includes(tool) && permitted.has(tool)),
+    tools: parent.tools.filter((tool) => assignee.tools.includes(tool) && (!permitted || permitted.has(tool))),
     connectors: parent.connectors.filter((id) => assignee.connectors.includes(id)),
     contributions: parent.contributions.filter((id) => assignee.contributions.includes(id))
   }

package/src/harness.ts

@@ -15,6 +15,7 @@ import { readJsonOr } from './core/fs'
 import { closeIndex } from './core/index'
 import { projectsOrNone } from './core/projects'
 import { ConnectedApps } from './mcp/service'
+import { migrateConnectionScopes } from './mcp/scopeMigration'
 import type { MaintainerFactory } from './memory/maintainer'
 import { Maintenance } from './memory/maintenance'
 import * as migrate from './memory/migrate'
@@ -179,7 +180,7 @@ export class Harness {
       policy: this.policy,
       broker: this.apps,
       plugins: this.plugins,
-      resolveCapabilities: (caller, tools) => capabilities.resolve(this, { agentId: caller.agentId ?? null, projectId: caller.projectId ?? null, tools }),
+      resolveCapabilities: (caller, tools, cwd) => capabilities.resolve(this, { agentId: caller.agentId ?? null, projectId: caller.projectId ?? null, cwd, tools }),
       factory: options.sessionFactory
     })
     this.maintenance = new Maintenance({ env: this.env, bus: this.bus, accounts: this.accounts, factory: options.maintainerFactory, idleMs: options.idleMs })
@@ -221,13 +222,22 @@ export class Harness {
     void this.hooks.reload()
     for (const folder of ['registry/skills', 'registry/prompts', 'registry/rules', 'config', 'runs']) mkdirSync(join(root, folder), { recursive: true })
     let migrationError: string | null = null
+    let wikiMigrationError: string | null = null
     try {
       if (migrate.run(this.env, agentIds)) log(`started Wiki storage version ${migrate.WIKI_VERSION}; the earlier Wiki is kept as a backup in the data root`)
     } catch (error) {
       migrationError = error instanceof Error ? error.message : String(error)
+      wikiMigrationError = migrationError
       log('Wiki migration failed', migrationError)
     }
-    if (!migrationError) {
+    try {
+      migrateConnectionScopes(root, this.stateDir)
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : String(error)
+      migrationError = migrationError ? `${migrationError}; connector scope migration: ${detail}` : detail
+      log('connector scope migration failed', detail)
+    }
+    if (!wikiMigrationError) {
       try {
         store.ensureLayout(root, this.env.productName)
         // Every project has its fixed pages, and the generated indexes match the files.

package/src/index.ts

@@ -17,6 +17,7 @@ export { fileSecretStore, memorySecretStore, secretKey, type SecretStore } from
 export type { Account, AccountsOverview, Pool } from './accounts/store'
 export type { ModelOption } from './accounts/accounts'
 export type { Capability, CapabilityCatalogue, CapabilityKind, CapabilityScope, CapabilitySet } from './capabilities/types'
+export type { RunCapabilitySnapshot } from './capabilities/runSnapshot'
 
 export type { CallerContext } from './memory/caller'
 export { dispatch as memoryCall } from './memory/dispatch'
@@ -61,7 +62,7 @@ export { HARNESS_PLUGINS } from './plugins/builtin'
 export { FIRST_PARTY_PLUGINS } from './plugins/firstParty'
 export type { Found, Resolver } from './plugins/discover'
 export type { Loading, Registered } from './plugins/plugins'
-export { CONTRIBUTION_KINDS, PLUGIN_SOURCES, type Contribution, type ContributionKind, type ContributionState, type Delivery, type Inventory, type InventoryItem, type Plugin, type PluginDescriptor, type PluginManage, type PluginSetting, type PluginSource } from './plugins/types'
+export { CONTRIBUTION_KINDS, PLUGIN_SOURCES, type ConnectorTemplate, type Contribution, type ContributionKind, type ContributionState, type Delivery, type Inventory, type InventoryItem, type Plugin, type PluginDescriptor, type PluginManage, type PluginSetting, type PluginSource } from './plugins/types'
 
 export { methods } from './server/methods'
 export { remoteDirectory, remotePolicy, remoteSecrets, remoteTools } from './server/remote'