@xingular/harness 0.1.3 → 0.1.5

package/src/terminal/socket.ts

@@ -1,9 +1,9 @@
 // The session socket: how a process the harness did not start in-process (the `pi` command in
-// a terminal, with its extension and the `agentx-wiki` / `agentx-mcp` commands) reaches the
-// session it belongs to. Owner-only Unix socket, newline-delimited JSON, one request per
-// connection. Each terminal session holds a random token bound to its caller, its connected-apps
-// grant, and its controller; the token stops working when the terminal ends.
-import { createHash } from 'node:crypto'
+// a terminal, with its extension and the `xagent-wiki` / `xagent-mcp` commands) reaches the
+// session it belongs to. Owner-only Unix socket (a named pipe on Windows), newline-delimited JSON,
+// one request per connection. Each terminal session holds a random token bound to its caller, its
+// connected-apps grant, and its controller; the token stops working when the terminal ends.
+import { createHash, randomBytes } from 'node:crypto'
 import { chmodSync, mkdirSync, rmSync, statSync } from 'node:fs'
 import { createServer, type Server, type Socket } from 'node:net'
 import { tmpdir } from 'node:os'
@@ -42,16 +42,32 @@ const MAX_REQUEST_BYTES = 1024 * 1024
 /** macOS refuses a socket path longer than 103 bytes. */
 const MAX_SOCKET_PATH = 100
 
+/**
+ * Windows has no socket files for Node's `net`: it listens on a named pipe, which lives in a
+ * machine-wide namespace. A random name keeps another local process from guessing it and standing
+ * in front of the session; the token still decides what a caller may do.
+ */
 export function socketPath(stateDir: string): string {
+  if (process.platform === 'win32') return `\\\\.\\pipe\\xingular-harness-${randomBytes(12).toString('hex')}`
   const path = join(stateDir, 'run', 'harness.sock')
   if (Buffer.byteLength(path) <= MAX_SOCKET_PATH) return path
   return join(tmpdir(), `xh-${createHash('sha256').update(path).digest('hex').slice(0, 16)}.sock`)
 }
 
+/** A named pipe has no folder, file mode, or owner to check or clean up. */
+const isPipePath = (path: string): boolean => path.startsWith('\\\\.\\pipe\\')
+
 /** Names the folder and the user when the operating system refuses the socket, so the cause shows. */
 function refusedBind(path: string, error: unknown): unknown {
   const code = (error as { code?: unknown } | null)?.code
   if (code !== 'EACCES' && code !== 'EPERM') return error
+  if (isPipePath(path)) {
+    return new HarnessError(
+      'session_socket_denied',
+      `The session pipe ${path} could not be created (${code}).`,
+      'Start the harness again from your own user session. If it keeps failing, report this code and the Windows version.'
+    )
+  }
   let folder: string
   try {
     const stat = statSync(dirname(path))
@@ -169,18 +185,22 @@ export class SessionSocket {
   /** Binds the socket once; later calls wait for the same bind. */
   listen(): Promise<void> {
     this.listening ??= new Promise<void>((resolve, reject) => {
-      mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 })
-      rmSync(this.path, { force: true })
+      if (!isPipePath(this.path)) {
+        mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 })
+        rmSync(this.path, { force: true })
+      }
       const server = createServer((client) => this.serve(client))
       server.once('error', (error) => {
         this.listening = null
         reject(refusedBind(this.path, error))
       })
       server.listen(this.path, () => {
-        try {
-          chmodSync(this.path, 0o600)
-        } catch (error) {
-          log('session socket permissions', error instanceof Error ? error.message : String(error))
+        if (!isPipePath(this.path)) {
+          try {
+            chmodSync(this.path, 0o600)
+          } catch (error) {
+            log('session socket permissions', error instanceof Error ? error.message : String(error))
+          }
         }
         this.server = server
         resolve()
@@ -196,6 +216,6 @@ export class SessionSocket {
     this.listening = null
     for (const client of this.clients) client.destroy()
     if (server) await new Promise<void>((resolve) => server.close(() => resolve()))
-    rmSync(this.path, { force: true })
+    if (!isPipePath(this.path)) rmSync(this.path, { force: true })
   }
 }

package/src/terminal/standalone.test.ts

@@ -117,4 +117,14 @@ describe('standalone terminal startup', () => {
     expect(existsSync(socketPath(harness.stateDir))).toBe(false)
     expect(harness.terminals.has('failed')).toBe(false)
   })
+
+  it('explains a missing Pi executable in terms of the terminal launch', async () => {
+    const home = temporaryDirectory('harness-standalone-enoent-')
+    const cwd = temporaryDirectory('harness-cwd-enoent-')
+    const error = Object.assign(new Error('spawn /opt/pi/bin/pi ENOENT'), { code: 'ENOENT' })
+    const spawn = fakeSpawn(() => undefined, { error })
+
+    await expect(runStandaloneTerminal([], { home, cwd, stdinIsTTY: true, stdoutIsTTY: true, createSessionId: () => 'missing-pi', createHarness: harnessFactory, spawn }))
+      .rejects.toThrow(/Could not start Pi terminal.*Pi executable.*\/opt\/pi\/bin\/pi/)
+  })
 })

package/src/terminal/standalone.ts

@@ -73,6 +73,16 @@ function exitCode(code: number | null, signal: NodeJS.Signals | null): number {
   return 1
 }
 
+function spawnError(error: Error, launch: TerminalLaunch): Error {
+  const code = (error as NodeJS.ErrnoException).code
+  if (code !== 'ENOENT' && code !== 'EACCES' && code !== 'EPERM') return error
+  if (launch.program === process.execPath || launch.env.XINGULAR_HARNESS_NODE === launch.program) {
+    return new Error(`Could not start the Pi terminal because Node could not run "${launch.args[0] ?? 'the bundled Pi CLI'}" (${code}). Verify Node and the bundled Pi package are installed.`, { cause: error })
+  }
+  const problem = code === 'ENOENT' ? 'was not found' : `could not start (${code})`
+  return new Error(`Could not start Pi terminal. Pi executable "${launch.program}" ${problem}; verify it is installed and executable or check the configured terminal executable.`, { cause: error })
+}
+
 function spawnPi(launch: TerminalLaunch, cwd: string, spawn = nodeSpawn): Promise<number> {
   return new Promise((resolveExit, reject) => {
     const child = spawn(launch.program, launch.args, {
@@ -103,7 +113,7 @@ function spawnPi(launch: TerminalLaunch, cwd: string, spawn = nodeSpawn): Promis
     process.on('SIGINT', onInterrupt)
     process.on('SIGTERM', onTerminate)
     process.on('SIGHUP', onHangup)
-    child.once('error', (error) => finish(() => reject(error)))
+    child.once('error', (error) => finish(() => reject(spawnError(error, launch))))
     child.once('exit', (code, signal) => finish(() => resolveExit(exitCode(code, signal))))
   })
 }

package/src/terminal/terminal.test.ts

@@ -1,4 +1,5 @@
-import { mkdtempSync, readFileSync } from 'node:fs'
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs'
+import { spawnSync } from 'node:child_process'
 import { connect } from 'node:net'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
@@ -24,6 +25,10 @@ afterEach(async () => {
 async function setup(policy: ToolPolicy = {}) {
   const root = rootWithProject()
   const harness = createHarness({ dataRoot: root, stateDir: mkdtempSync(join(tmpdir(), 'hs-')), secrets: memorySecretStore(), policy, piProgram: () => '/opt/pi/bin/pi', assets: { node: '/opt/node', cli: '/opt/harness/cli.js', piExtension: '/opt/harness/terminal-pi.js' } })
+  const legacyBin = join(harness.stateDir, 'run', 'bin')
+  mkdirSync(legacyBin, { recursive: true })
+  writeFileSync(join(legacyBin, 'agentx-wiki'), 'old wrapper')
+  writeFileSync(join(legacyBin, 'agentx-mcp'), 'old wrapper')
   open.push(harness)
   const account = harness.accounts.create('Main', 'apiKey').accounts[0]
   const events: RunEvent[] = []
@@ -59,7 +64,7 @@ describe('a pi terminal session', () => {
     expect(launch.accountId).toBe(account.id)
     expect(launch.args[0]).toBe('--append-system-prompt')
     expect(launch.args[1]).toContain('# Xingular Harness context')
-    expect(launch.args[1]).toContain('agentx-wiki')
+    expect(launch.args[1]).toContain('xagent-wiki')
     // Pi's own discovery is off; its command's built-in extensions are named, and the harness's comes last.
     expect(launch.args.slice(2)).toEqual([
       '--model', 'chosen-model', '--no-extensions', '--no-skills', '--no-prompt-templates', '--no-themes',
@@ -68,13 +73,36 @@ describe('a pi terminal session', () => {
     ])
     expect(launch.env.PI_CODING_AGENT_DIR).toBe(join(harness.accounts.dir, account.id, 'home', 'pi'))
     expect(String(launch.env.PATH).split(':')[0]).toBe(join(harness.stateDir, 'run', 'bin'))
-    expect(readFileSync(join(harness.stateDir, 'run', 'bin', 'agentx-wiki'), 'utf8')).toBe("#!/bin/sh\nexec '/opt/node' '/opt/harness/cli.js' wiki \"$@\"\n")
-    expect(readFileSync(join(harness.stateDir, 'run', 'bin', 'agentx-mcp'), 'utf8')).toContain("'/opt/harness/cli.js' mcp")
+    expect(readFileSync(join(harness.stateDir, 'run', 'bin', 'xagent-wiki'), 'utf8')).toBe("#!/bin/sh\nexec '/opt/node' '/opt/harness/cli.js' wiki \"$@\"\n")
+    expect(readFileSync(join(harness.stateDir, 'run', 'bin', 'xagent-mcp'), 'utf8')).toContain("'/opt/harness/cli.js' mcp")
+    expect(existsSync(join(harness.stateDir, 'run', 'bin', 'agentx-wiki'))).toBe(false)
+    expect(existsSync(join(harness.stateDir, 'run', 'bin', 'agentx-mcp'))).toBe(false)
     // The session keeps the pack it started with.
     expect(JSON.parse(readFileSync(join(sessionFolder, 'context.json'), 'utf8')).profile).toBe('session')
     expect(root).toBeTruthy()
   })
 
+  it.skipIf(process.platform !== 'win32')('starts the resolved Pi CLI through Node without a model or interactive terminal', async () => {
+    const root = rootWithProject()
+    const stateDir = mkdtempSync(join(tmpdir(), 'hs-pi-smoke-'))
+    const harness = createHarness({ dataRoot: root, stateDir, secrets: memorySecretStore() })
+    open.push(harness)
+    harness.accounts.create('Main', 'subscription')
+    const launch = await harness.terminals.prepare({ sessionId: 'pi-smoke', cwd: root, sessionFolder: join(root, 'sessions', 'pi-smoke') })
+    const cli = launch.args[0]
+    const pathKeys = Object.keys(launch.env).filter((name) => name.toLowerCase() === 'path')
+
+    expect(launch.program).toBe(process.execPath)
+    expect(pathKeys).toHaveLength(1)
+    expect(launch.env[pathKeys[0]]).toContain(';')
+    expect(launch.env.XINGULAR_HARNESS_NODE).toBe(process.execPath)
+    expect(readFileSync(join(stateDir, 'run', 'bin', 'xagent-wiki.cmd'), 'utf8')).toContain(' wiki %*\r\n')
+    const result = spawnSync(launch.program, [cli, '--help'], { cwd: root, encoding: 'utf8', timeout: 20_000 })
+    expect(result.error).toBeUndefined()
+    expect(result.status).toBe(0)
+    expect(`${result.stdout}${result.stderr}`).toMatch(/usage|options|pi coding agent/i)
+  })
+
   it('passes what the harness found as paths, the enabled registry items with them, and its own extension last', async () => {
     const root = rootWithProject()
     writeFile(join(root, 'registry/skills/release/SKILL.md'), '# Release\n')
@@ -284,7 +312,7 @@ describe('the session socket', () => {
   })
 })
 
-describe('agentx-wiki command', () => {
+describe('xagent-wiki command', () => {
   it('maps commands onto memory and Wiki calls', () => {
     expect(parseCli(['search', 'deploy', 'steps', '--kind', 'page'])).toEqual({ kind: 'call', call: 'wiki.search', params: { query: 'deploy steps', kinds: ['page'] } })
     expect(parseCli(['read', '/projects/app/arch'])).toEqual({ kind: 'call', call: 'wiki.read', params: { id: '/projects/app/arch' } })

package/src/terminal/terminals.ts

@@ -3,7 +3,7 @@
 // skills, the session socket), then follows the process through its extension. It never owns
 // the terminal: the application spawns the process from the spec returned here and reports when
 // it exits.
-import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
@@ -15,7 +15,7 @@ import { log } from '../core/bus'
 import type { HarnessEnv } from '../core/env'
 import { HarnessError, invalid } from '../core/errors'
 import { newId, now } from '../core/fs'
-import { findBinary, searchPath } from '../core/path'
+import { prependSearchPath, searchPath } from '../core/path'
 import type { BrokerSession, ConnectedApps } from '../mcp/service'
 import type { CallerContext } from '../memory/caller'
 import { dispatch } from '../memory/dispatch'
@@ -33,6 +33,7 @@ import type { ToolSpec } from '../tools/types'
 import { APPS_COMMAND, WIKI_COMMAND } from './cli'
 import { SOCKET_ENV, TOKEN_ENV } from './client'
 import { TerminalController, type PolicyReply } from './controller'
+import { resolvePiCommand, terminalCommandFiles } from './launch'
 import { SessionSocket, socketPath } from './socket'
 
 /** The files a terminal session needs on disk, outside this process. */
@@ -102,7 +103,7 @@ export interface TerminalsOptions {
   /** Lists plugins and applies a person's choices, for the session's `/plugins` command. */
   pluginControl?: PluginControl
   assets?: TerminalAssets
-  /** The `pi` executable. Defaults to the one on the search path. */
+  /** The `pi` executable. Defaults to the PATH command on POSIX and the bundled CLI on Windows. */
   program?: () => string | null
 }
 
@@ -134,19 +135,27 @@ export class Terminals {
   private ensureCommands(): string {
     const bin = join(this.options.stateDir, 'run', 'bin')
     mkdirSync(bin, { recursive: true })
-    const quote = (value: string) => `'${value.replaceAll("'", "'\\''")}'`
-    for (const [name, mode] of [[WIKI_COMMAND, 'wiki'], [APPS_COMMAND, 'mcp']] as const) {
-      const wrapper = join(bin, name)
-      const text = `#!/bin/sh\nexec ${quote(this.assets.node)} ${quote(this.assets.cli)} ${mode} "$@"\n`
-      let current: string | null = null
+    for (const name of ['agentx-wiki', 'agentx-mcp', 'agentx-wiki.cmd', 'agentx-mcp.cmd']) {
+      const path = join(bin, name)
       try {
-        current = readFileSync(wrapper, 'utf8')
+        if (lstatSync(path).isFile()) unlinkSync(path)
       } catch {
-        current = null
+        // These names belonged to the previous generated wrappers.
       }
-      if (current !== text) {
-        writeFileSync(wrapper, text)
-        chmodSync(wrapper, 0o755)
+    }
+    for (const [name, mode] of [[WIKI_COMMAND, 'wiki'], [APPS_COMMAND, 'mcp']] as const) {
+      for (const file of terminalCommandFiles(process.platform, this.assets.node, this.assets.cli, name, mode)) {
+        const path = join(bin, file.name)
+        let current: string | null = null
+        try {
+          current = readFileSync(path, 'utf8')
+        } catch {
+          current = null
+        }
+        if (current !== file.content) {
+          writeFileSync(path, file.content)
+          chmodSync(path, 0o755)
+        }
       }
     }
     return bin
@@ -298,8 +307,7 @@ export class Terminals {
     const { root } = env
     if (!input?.sessionId || !input.cwd || !input.sessionFolder) throw invalid('A terminal session needs an id, a working folder, and its own folder.')
     await this.dispose(input.sessionId)
-    const program = this.options.program ? this.options.program() : findBinary('pi')
-    if (!program) throw new HarnessError('harness_unavailable', 'The Pi CLI was not found on PATH.')
+    const command = resolvePiCommand({ platform: process.platform, node: this.assets.node, programOverride: this.options.program })
     // A pinned account is used as it is; it is never exchanged for another one.
     const account = input.accountId ? accounts.find(input.accountId) : accounts.resolve(null, null)
     const launch = launchEnv(accounts.dir, account)
@@ -343,7 +351,7 @@ export class Terminals {
       live.token = token
       this.sessions.set(sessionId, live)
 
-      const args = ['--append-system-prompt', render(env, pack)]
+      const args = [...command.argsPrefix, '--append-system-prompt', render(env, pack)]
       if (input.model) args.push('--model', input.model)
       if (loading) {
         // Pi's own discovery is off: the terminal loads what the harness found and nothing else.
@@ -358,9 +366,15 @@ export class Terminals {
       args.push('--extension', this.assets.piExtension, '--session-dir', this.historyDir(input))
       if (input.nativeSessionId) args.push('--session', input.nativeSessionId)
       return {
-        program,
+        program: command.program,
         args,
-        env: { ...launch, PATH: `${this.ensureCommands()}:${searchPath()}`, [SOCKET_ENV]: this.socket.path, [TOKEN_ENV]: token },
+        env: {
+          ...launch,
+          ...(process.platform === 'win32' ? { XINGULAR_HARNESS_NODE: this.assets.node, XINGULAR_HARNESS_CLI: this.assets.cli } : {}),
+          ...prependSearchPath(this.ensureCommands(), searchPath()),
+          [SOCKET_ENV]: this.socket.path,
+          [TOKEN_ENV]: token
+        },
         accountId: account.id,
         nativeSessionId: input.nativeSessionId ?? null
       }

package/src/tools/definitions.ts

@@ -1,5 +1,5 @@
 // The memory and Wiki tools a session gets, defined once. An SDK session gets them as Pi tools;
-// a terminal session gets them from the `agentx-wiki` command or the bundled MCP server. All of
+// a terminal session gets them from the `xagent-wiki` command or the bundled MCP server. All of
 // them reach the same calls.
 
 export type WikiCall =
@@ -116,7 +116,7 @@ export const WIKI_TOOLS: WikiToolDefinition[] = [
     name: 'wiki_read',
     call: 'wiki.read',
     label: 'Read Wiki entry',
-    description: 'Read one Wiki page, fact, skill, rule, or prompt in full, with its sources, links, and backlinks. Pass an id (arch, skills/review) or a Wiki path (/projects/agent-x/arch).',
+    description: 'Read one Wiki page, fact, skill, rule, or prompt in full, with its sources, links, and backlinks. Pass an id (arch, skills/review) or a Wiki path (/projects/xagent/arch).',
     parameters: { type: 'object', properties: { id: text('Entry id or Wiki path'), revision: text('Optional pinned revision selected for this reply'), offset: { type: 'integer', minimum: 0, description: 'Character offset when reading a pinned revision; use nextOffset to continue.' } }, required: ['id'] }
   },
   {

package/src/tools/types.ts

@@ -3,10 +3,13 @@
 import type { CallerContext } from '../memory/caller'
 import type { CapabilitySet } from '../capabilities/types'
 import type { ActiveRun } from '../sessions/registry'
+import type { ToolAttachmentRef } from '../sessions/contracts'
 
 export interface ToolResult {
   text: string
   image?: { data: string; mimeType: string }
+  /** References to content stored by the provider; bytes never enter the run-event stream. */
+  attachments?: ToolAttachmentRef[]
 }
 
 export interface ToolSpec {