@xingular/harness 0.1.4 → 0.1.6

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 {