@xingular/harness 0.1.7 → 2.1.0

package/src/harness.ts

@@ -1,6 +1,7 @@
 // The harness, assembled: Pi sessions on isolated accounts, a compiled prompt, a memory
 // lifecycle, tools, connected apps, and skills. An application embeds one of these and adds
 // its own prompt sections, tools, and policy; nothing here knows what that application is.
+import { Subagents } from './sessions/subagentService'
 import { mkdirSync } from 'node:fs'
 import { join } from 'node:path'
 
@@ -16,6 +17,7 @@ import { readJsonOr } from './core/fs'
 import { closeIndex } from './core/index'
 import { projectsOrNone } from './core/projects'
 import { ConnectedApps } from './mcp/service'
+import type { AppOAuthClients } from './mcp/types'
 import { migrateConnectionScopes } from './mcp/scopeMigration'
 import type { MaintainerFactory } from './memory/maintainer'
 import { Maintenance } from './memory/maintenance'
@@ -76,6 +78,11 @@ export interface HarnessOptions {
   plugins?: PluginDescriptor[]
   /** Replaces Pi's own search for extensions, skills, prompts and themes, for tests. */
   resolver?: Resolver
+  /**
+   * The application's own registered OAuth clients, so a connector it publishes needs no client
+   * from the person. Only a catalog entry listed in `ids` can use one, and nothing is stored.
+   */
+  oauthClients?: AppOAuthClients
   /** Replaces how a plugin's hooks file is read as a module, for tests. */
   hookImporter?: (address: string) => Promise<unknown>
 }
@@ -124,6 +131,7 @@ export class Harness {
   /** Every part described as a plugin: the harness's own, then the application's. */
   descriptors: readonly PluginDescriptor[] = HARNESS_PLUGINS
   applicationPlugins: ReadonlySet<string> = new Set()
+  readonly subagents: Subagents
   readonly sessions: Sessions
   readonly maintenance: Maintenance
   readonly terminals: Terminals
@@ -152,7 +160,7 @@ export class Harness {
       redact: (event) => this.apps.connections.redactEvent(event),
       ended: (runId, sessionId) => this.apps.revokeRun(runId, sessionId)
     })
-    this.apps = new ConnectedApps({ env: this.env, stateDir: this.stateDir, secrets, bus: this.bus, runs: this.runs, policy: this.policy })
+    this.apps = new ConnectedApps({ env: this.env, stateDir: this.stateDir, secrets, bus: this.bus, runs: this.runs, policy: this.policy, oauthClients: options.oauthClients })
     this.plugins = new Plugins({ stateDir: this.stateDir, bus: this.bus, resolver: options.resolver, attachments: () => (this.env.dataRoot ? attachments.load(this.env.dataRoot) : null), packagesDir: () => (this.env.dataRoot ? join(this.env.dataRoot, 'plugins') : null) })
     this.hooks = new Hooks({
       stateDir: this.stateDir,
@@ -182,7 +190,9 @@ export class Harness {
       reloadTimer.unref?.()
     })
     this.describe(options.plugins ?? [])
+    this.subagents = new Subagents(this.env, this.runs, (input) => this.sessions.run(input))
     this.sessions = new Sessions({
+      subagents: this.subagents,
       env: this.env,
       accounts: this.accounts,
       runs: this.runs,
@@ -193,7 +203,7 @@ export class Harness {
       factory: options.sessionFactory
     })
     this.maintenance = new Maintenance({ env: this.env, bus: this.bus, accounts: this.accounts, factory: options.maintainerFactory, idleMs: options.idleMs, external: options.externalMaintenance, excludedTriggers: options.maintenanceExcludedTriggers, runTrigger: options.maintenanceRunTrigger })
-    this.terminals = new Terminals({ env: this.env, stateDir: this.stateDir, accounts: this.accounts, runs: this.runs, apps: this.apps, policy: this.policy, bus: this.bus, plugins: this.plugins, pluginControl: { list: (scope) => pluginApi.list(this, scope), attach: (params, on) => pluginApi.attach(this, params, on), trust: (scope) => pluginApi.trust(this, scope), untrust: (scope) => pluginApi.untrust(this, scope) }, assets: options.assets, program: options.piProgram, hub: this.hub })
+    this.terminals = new Terminals({ subagents: this.subagents, resolveCapabilities: (caller, tools, cwd) => capabilities.resolve(this, { agentId: caller.agentId ?? null, projectId: caller.projectId ?? null, cwd, tools }), env: this.env, stateDir: this.stateDir, accounts: this.accounts, runs: this.runs, approvals: this.approvals, apps: this.apps, policy: this.policy, bus: this.bus, plugins: this.plugins, pluginControl: { list: (scope) => pluginApi.list(this, scope), attach: (params, on) => pluginApi.attach(this, params, on), trust: (scope) => pluginApi.trust(this, scope), untrust: (scope) => pluginApi.untrust(this, scope) }, assets: options.assets, program: options.piProgram, hub: this.hub })
     this.ready = this.apps.start().catch((error) => log('connected apps', error instanceof Error ? error.message : String(error)))
     this.runs.listen((event, run) => {
       this.accounts.onRunEvent(event, run)

package/src/hub/hub.test.ts

@@ -40,6 +40,8 @@ describe('Hub installation', () => {
     expect(existsSync(join(root, 'config', 'plugin-attachments.json'))).toBe(false)
     writeFileSync(join(root, 'hub', 'documents', receipt.document!), '{"edited":true}')
     expect(() => hub.readDocument('example/review', '1.0.0')).toThrow('differs')
+    expect((await hub.list()).installed[0]).toMatchObject({ state: 'changed' })
+    await expect(hub.install('example/review', '1.0.0')).rejects.toThrow('Uninstall it before installing')
   })
   it('imports complete skills disabled and refuses overwriting local files', async () => {
     const { hub, root } = fixture([entry('registry', skill())])
@@ -90,12 +92,58 @@ describe('Hub installation', () => {
     expect(preview.delivery.kind !== 'pi-package' && preview.delivery.bundled).toContain('data only')
     expect(existsSync(join(root, 'hub'))).toBe(false)
   })
+  it('returns bounded UTF-8-safe preview pages and reuses the verified download for install', async () => {
+    const content = `"${'é'.repeat(20_000)}"`
+    const item = entry('document', content)
+    if (item.delivery.kind !== 'pi-package') delete item.delivery.bundled
+    const fetcher = vi.fn(async () => new Response(content)) as typeof fetch
+    const { hub, root } = fixture([item], fetcher)
+    const pages = []
+    let offset = 0
+    while (true) {
+      const page = await hub.preview(item.id, item.version, offset)
+      expect(Buffer.byteLength(page.content)).toBeLessThanOrEqual(16 * 1024)
+      pages.push(page.content)
+      if (page.done) break
+      offset = page.nextOffset
+    }
+    expect(pages.join('')).toBe(content)
+    expect(fetcher).toHaveBeenCalledTimes(1)
+    await hub.install(item.id, item.version)
+    expect(fetcher).toHaveBeenCalledTimes(1)
+    expect(existsSync(join(root, 'hub', 'documents'))).toBe(true)
+  })
+  it('uninstalls only its receipt-owned document, including local edits', async () => {
+    const first = entry()
+    const second = { ...entry(), id: 'example/second', title: 'Second' }
+    const { hub, root } = fixture([first, second])
+    const owned = await hub.install(first.id, first.version)
+    const other = await hub.install(second.id, second.version)
+    writeFileSync(join(root, 'hub', 'documents', owned.document!), '{"local":true}')
+    await hub.uninstall(first.id, first.version)
+    expect(existsSync(join(root, 'hub', 'documents', owned.document!))).toBe(false)
+    expect(existsSync(join(root, 'hub', 'documents', other.document!))).toBe(true)
+    expect((await hub.list()).installed.map((receipt) => receipt.entry.id)).toEqual([second.id])
+  })
+  it('uninstalls only receipt-owned registry resources and leaves unrelated files', async () => {
+    const { hub, root } = fixture([entry('registry', skill())])
+    const receipt = await hub.install('example/review', '1.0.0')
+    const unrelated = join(root, 'registry', 'skills', 'unrelated', 'SKILL.md')
+    mkdirSync(join(root, 'registry', 'skills', 'unrelated'), { recursive: true })
+    writeFileSync(unrelated, '---\nname: unrelated\ndescription: Local.\n---\n')
+    await hub.uninstall('example/review', '1.0.0')
+    expect(existsSync(join(root, 'registry', 'skills', 'review'))).toBe(false)
+    expect(readFileSync(unrelated, 'utf8')).toContain('unrelated')
+    expect((await hub.list()).installed).toEqual([])
+    expect(receipt.resourceIds).toEqual(['skills/review'])
+  })
   it('can reinstall deleted resources and clears stale attachment grants', async () => {
     const { hub, root } = fixture([entry('registry', skill())])
     await hub.install('example/review', '1.0.0')
     registry.setEnabled(root, null, ['skills/review'])
     rmSync(join(root, 'registry', 'skills', 'review'), { recursive: true })
-    expect((await hub.list()).installed).toEqual([])
+    expect((await hub.list()).installed[0]).toMatchObject({ state: 'incomplete' })
+    await hub.uninstall('example/review', '1.0.0')
     await hub.install('example/review', '1.0.0')
     expect(registry.enabledFor(root, null)).toEqual([])
     expect((await hub.list()).installed).toHaveLength(1)

package/src/hub/hub.ts

@@ -1,5 +1,5 @@
 import { createHash } from 'node:crypto'
-import { closeSync, lstatSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { closeSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { watch } from 'node:fs'
 
@@ -12,7 +12,7 @@ import * as registry from '../skills/registry'
 import * as attachments from '../plugins/attachments'
 import { version as harnessVersion } from '../../package.json'
 import bundled from './catalog.json'
-import { HUB_CATALOG_URL, HUB_MAX_BYTES, hubCatalogSchema, hubEntrySchema, hubReceiptSchema, meetsMinimum, type HubCatalog, type HubEntry, type HubOverview, type HubReceipt } from './schema'
+import { HUB_CATALOG_URL, HUB_MAX_BYTES, HUB_PREVIEW_PAGE_BYTES, hubCatalogSchema, hubEntrySchema, hubReceiptSchema, meetsMinimum, type HubCatalog, type HubEntry, type HubOverview, type HubReceipt } from './schema'
 
 export interface HubOptions {
   catalogUrl?: string
@@ -60,6 +60,7 @@ export class Hub {
   private watcher: ReturnType<typeof watch> | null = null
   private refresh: Promise<HubOverview> | null = null
   private installing = false
+  private cachedPayload: { key: string; bytes: Buffer; expiresAt: number } | null = null
   get busy(): boolean { return this.installing }
 
   constructor(private readonly harness: Harness, options: HubOptions = {}) {
@@ -80,12 +81,25 @@ export class Hub {
     const cached = readJsonOr<{ catalog: unknown; at: string } | null>(join(this.harness.stateDir, 'hub', 'catalog.json'), null)
     const parsed = hubCatalogSchema.safeParse(cached?.catalog)
     const catalog = parsed.success ? parsed.data : this.fallback
-    const installed = this.receipts().filter((receipt) => this.present(receipt))
+    const installed = this.receipts().map((receipt) => ({ ...receipt, state: this.receiptState(receipt) }))
     const entries = new Map(catalog.entries.map((entry) => [`${entry.id}@${entry.version}`, entry]))
     for (const receipt of installed) if (!entries.has(`${receipt.entry.id}@${receipt.entry.version}`)) entries.set(`${receipt.entry.id}@${receipt.entry.version}`, receipt.entry)
     return { entries: [...entries.values()], installed, origin: parsed.success ? 'cached' : 'bundled', refreshedAt: parsed.success ? cached!.at : null, error: null, dataRoot: this.harness.dataRoot, stateDir: this.harness.stateDir }
   }
 
+  private receiptState(receipt: HubReceipt): 'installed' | 'changed' | 'incomplete' {
+    if (receipt.document && receipt.entry.delivery.kind === 'document') {
+      if (receipt.document !== `${receiptName(receipt.entry)}.json`) return 'incomplete'
+      try {
+        const path = join(this.harness.dataRoot!, 'hub', 'documents', receipt.document)
+        const stat = lstatSync(path)
+        if (!stat.isFile() || stat.size > HUB_MAX_BYTES) return 'incomplete'
+        return digest(readFileSync(path)) === receipt.entry.delivery.sha256 ? 'installed' : 'changed'
+      } catch { return 'incomplete' }
+    }
+    return this.present(receipt) ? 'installed' : 'incomplete'
+  }
+
   private present(receipt: HubReceipt): boolean {
     const root = this.harness.dataRoot
     if (!root) return false
@@ -169,6 +183,28 @@ export class Hub {
     return { ...entry, delivery: { ...entry.delivery, bundled: this.decode(bytes) } }
   }
 
+  private async verifiedPayload(entry: HubEntry): Promise<Buffer> {
+    if (entry.delivery.kind === 'pi-package') throw invalid('Packages do not have a JSON payload preview.')
+    const key = `${entry.id}@${entry.version}`
+    if (this.cachedPayload?.key === key && this.cachedPayload.expiresAt > Date.now()) return this.cachedPayload.bytes
+    const bytes = entry.delivery.bundled === undefined ? await this.bytes(entry.delivery.url) : Buffer.from(entry.delivery.bundled)
+    if (digest(bytes) !== entry.delivery.sha256) throw invalid('The downloaded item differs from the reviewed version. Nothing was installed.')
+    this.decode(bytes)
+    this.cachedPayload = { key, bytes, expiresAt: Date.now() + 5 * 60 * 1000 }
+    return bytes
+  }
+
+  async preview(id: string, version: string, offset = 0) {
+    if (!Number.isSafeInteger(offset) || offset < 0) throw invalid('Preview offset must be a non-negative byte position.')
+    const entry = this.find(id, version)
+    const bytes = await this.verifiedPayload(entry)
+    if (offset > bytes.length || offset < bytes.length && (bytes[offset] & 0xc0) === 0x80) throw invalid('Preview offset is outside the payload or splits a UTF-8 character.')
+    let end = Math.min(offset + HUB_PREVIEW_PAGE_BYTES, bytes.length)
+    while (end > offset && end < bytes.length && (bytes[end] & 0xc0) === 0x80) end -= 1
+    const content = this.decode(bytes.subarray(offset, end))
+    return { entry, content, offset, nextOffset: end, totalBytes: bytes.length, done: end >= bytes.length }
+  }
+
   async install(id: string, version: string): Promise<HubReceipt> {
     const root = this.harness.env.root
     const entry = hubEntrySchema.parse(this.find(id, version))
@@ -181,6 +217,7 @@ export class Hub {
       const records = this.receipts()
       const existing = records.find((receipt) => receipt.entry.id === id && receipt.entry.version === version)
       if (existing && this.present(existing)) return existing
+      if (existing) throw invalid('This Hub receipt is changed or incomplete. Uninstall it before installing this version again.')
       const remaining = records.filter((record) => record !== existing)
       const receipt: HubReceipt = { entry, installedAt: now(), resourceIds: [], document: null }
       const choicesBefore = attachments.load(root)
@@ -195,13 +232,14 @@ export class Hub {
         if (!receipt.resourceIds.length) throw invalid('The package did not add an installable plugin. No hub installation was recorded.')
       } else {
         const delivery = entry.delivery
-        const bytes = delivery.bundled === undefined ? await this.bytes(delivery.url) : Buffer.from(delivery.bundled)
-        if (digest(bytes) !== delivery.sha256) throw invalid('The downloaded item differs from the reviewed version. Nothing was installed.')
+        const bytes = await this.verifiedPayload(entry)
         const text = this.decode(bytes)
         if (delivery.kind === 'document') {
           JSON.parse(text)
           receipt.document = `${receiptName(entry)}.json`
-          atomicWrite(join(root, 'hub', 'documents', receipt.document), bytes)
+          const documentPath = join(root, 'hub', 'documents', receipt.document)
+          try { lstatSync(documentPath); throw invalid('A file already exists at the Hub document path. Review or remove it before installing.') } catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error }
+          atomicWrite(documentPath, bytes)
         } else {
           const payload = JSON.parse(text)
           const previous = new Set(registry.list(root).map((item) => item.id))
@@ -232,6 +270,84 @@ export class Hub {
     } finally { this.installing = false; releaseData?.(); releaseState() }
   }
 
+  async uninstall(id: string, version: string): Promise<HubReceipt> {
+    const root = this.harness.env.root
+    const releaseState = acquire(join(this.harness.stateDir, 'hub', 'install.lock'))
+    this.installing = true
+    let releaseData: (() => void) | null = null
+    try {
+      releaseData = acquire(join(root, 'hub', 'install.lock'))
+      const records = this.receipts()
+      const receipt = records.find((item) => item.entry.id === id && item.entry.version === version)
+      if (!receipt) throw invalid('This Hub installation receipt no longer exists.')
+      const staged = mkdtempSync(join(root, 'hub', '.uninstall-'))
+      const moves: Array<{ source: string; staged: string }> = []
+      let choicesBefore: ReturnType<typeof attachments.load> | null = null
+      let committed = false
+      let rollbackComplete = true
+      try {
+        const ownedPaths: string[] = []
+        if (receipt.document) {
+          if (receipt.entry.delivery.kind !== 'document' || receipt.document !== `${receiptName(receipt.entry)}.json`) throw invalid('The Hub receipt has an invalid document path.')
+          const path = join(root, 'hub', 'documents', receipt.document)
+          try {
+            const stat = lstatSync(path)
+            if (!stat.isFile()) throw invalid('The receipt-owned document path is not a regular file; it was left untouched.')
+            ownedPaths.push(path)
+          } catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error }
+        }
+        if (receipt.entry.delivery.kind === 'registry') {
+          const expectedKind = receipt.entry.delivery.registryKind
+          for (const id of receipt.resourceIds) {
+            if (!/^(skills|prompts|rules)\/[a-z0-9-]{1,64}$/.test(id)) throw invalid('The Hub receipt contains an invalid registry resource path.')
+            const [kind, name] = id.split('/')
+            if (kind !== expectedKind) throw invalid('The Hub receipt contains a resource outside its registry kind.')
+            const path = join(root, 'registry', kind, kind === 'skills' ? name : `${name}.md`)
+            try { lstatSync(path); ownedPaths.push(path) } catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error }
+          }
+          choicesBefore = attachments.load(root)
+          const choices = structuredClone(choicesBefore)
+          const owned = new Set(receipt.resourceIds)
+          for (const scope of [choices.global, ...Object.values(choices.agents), ...Object.values(choices.projects)]) {
+            scope.on = scope.on.filter((value) => !owned.has(value))
+            scope.off = scope.off.filter((value) => !owned.has(value))
+          }
+          for (let index = 0; index < ownedPaths.length; index += 1) {
+            const source = ownedPaths[index]
+            const destination = join(staged, String(index))
+            renameSync(source, destination)
+            moves.push({ source, staged: destination })
+          }
+          attachments.save(root, choices)
+        } else {
+          for (let index = 0; index < ownedPaths.length; index += 1) {
+            const source = ownedPaths[index]
+            const destination = join(staged, String(index))
+            renameSync(source, destination)
+            moves.push({ source, staged: destination })
+          }
+        }
+        if (receipt.entry.delivery.kind === 'pi-package') for (const pluginId of receipt.resourceIds) await packages.remove(this.harness, { pluginId })
+        writeJson(join(root, 'hub', 'installed.json'), records.filter((item) => item !== receipt))
+        committed = true
+        try { rmSync(staged, { recursive: true, force: true }) } catch { /* The receipt is removed; leave the staged copy for disk recovery. */ }
+        this.cachedPayload = this.cachedPayload?.key === `${id}@${version}` ? null : this.cachedPayload
+        this.harness.bus.emit({ type: 'hub.changed' })
+        this.harness.bus.emit({ type: 'plugins.changed' })
+        return receipt
+      } catch (error) {
+        if (!committed) {
+          if (choicesBefore) try { attachments.save(root, choicesBefore) } catch { /* Preserve the original failure and restore the owned files below. */ }
+          for (const move of moves.reverse()) {
+            try { lstatSync(move.staged); renameSync(move.staged, move.source) } catch { rollbackComplete = false }
+          }
+          if (rollbackComplete) try { rmSync(staged, { recursive: true, force: true }) } catch { /* Keep the staging directory for recovery. */ }
+        }
+        throw error
+      }
+    } finally { this.installing = false; releaseData?.(); releaseState() }
+  }
+
   readDocument(id: string, version: string): { entry: HubEntry; content: string } {
     const receipt = this.receipts().find((item) => item.entry.id === id && item.entry.version === version)
     if (!receipt?.document || receipt.document !== `${receiptName(receipt.entry)}.json`) throw invalid('Install this document before opening it.')

package/src/hub/schema.ts

@@ -2,6 +2,7 @@ import { z } from 'zod'
 
 export const HUB_CATALOG_URL = 'https://raw.githubusercontent.com/tanntnny/xingular-hub/main/catalog.json'
 export const HUB_MAX_BYTES = 16 * 1024 * 1024
+export const HUB_PREVIEW_PAGE_BYTES = 16 * 1024
 
 const httpsUrl = z.string().max(2000).url().refine((value) => {
   const url = new URL(value)
@@ -53,7 +54,17 @@ export const hubReceiptSchema = z.object({
   entry: hubEntrySchema,
   installedAt: z.string(),
   resourceIds: z.array(z.string()),
-  document: z.string().nullable()
+  document: z.string().nullable(),
+  state: z.enum(['installed', 'changed', 'incomplete']).optional()
+}).strict()
+
+export const hubPreviewPageSchema = z.object({
+  entry: hubEntrySchema,
+  content: z.string(),
+  offset: z.number().int().nonnegative(),
+  nextOffset: z.number().int().nonnegative(),
+  totalBytes: z.number().int().nonnegative(),
+  done: z.boolean()
 }).strict()
 
 export const hubOverviewSchema = z.object({
@@ -69,6 +80,7 @@ export const hubOverviewSchema = z.object({
 export type HubEntry = z.infer<typeof hubEntrySchema>
 export type HubCatalog = z.infer<typeof hubCatalogSchema>
 export type HubReceipt = z.infer<typeof hubReceiptSchema>
+export type HubPreviewPage = z.infer<typeof hubPreviewPageSchema>
 export type HubOverview = z.infer<typeof hubOverviewSchema>
 
 export function meetsMinimum(actual: string, minimum: string): boolean {

package/src/index.ts

@@ -47,7 +47,7 @@ export type { Effort } from './sessions/runner'
 
 export { describeTool, WIKI_TOOLS, WIKI_TOOL_NAMES, type WikiCall, type WikiToolDefinition } from './tools/definitions'
 export type { ToolProvider, ToolResult, ToolSession, ToolSpec } from './tools/types'
-export { SPAWN_SUBAGENT, SUBAGENT_RELATION, DEFAULT_SUBAGENT_DEPTH, MAX_SUBAGENT_DEPTH, type SubagentOptions } from './tools/spawnSubagent'
+export { SPAWN_SUBAGENT, SUBAGENT_RELATION } from './tools/spawnSubagent'
 export { maintenanceTools, MAINTENANCE_PLUGIN, MAINTENANCE_TOOL_NAMES } from './tools/maintenance'
 export type { CurationJob } from './memory/curation'
 export { webTools, WEB_PLUGIN, WEB_SEARCH_KEY, type WebToolOptions } from './web/tools'
@@ -55,7 +55,7 @@ export { registryTools, REGISTRY_WRITE, PLUGIN_WRITE, REGISTRY_WRITE_PLUGIN, typ
 export { safeRequest, type WebRequest, type WebResponse } from './web/safeRequest'
 
 export type { BrokeredTools, BrokerSession, BrokerTool } from './mcp/service'
-export type { Connection, ConnectionInput } from './mcp/types'
+export type { Connection, ConnectionInput, AppOAuthClients } from './mcp/types'
 
 export { configureBuiltins, type RegistryItem, type RegistryState, type SkillBundleInput } from './skills/registry'
 
@@ -73,3 +73,8 @@ export { methods } from './server/methods'
 export { remoteDirectory, remotePolicy, remoteSecrets, remoteTools } from './server/remote'
 export { PROTOCOL_VERSION, RpcPeer, stdioTransport, type Handler, type Transport } from './server/rpc'
 export { attach, serve, type Served } from './server/serve'
+
+export { DEFAULT_SUBAGENT_DEPTH, MAX_SUBAGENT_DEPTH, type SubagentOptions, type SubagentInput } from './sessions/subagents'
+
+export { Subagents } from './sessions/subagentService'
+export { WAIT_SUBAGENTS, type SubagentResult, type SubagentSelection } from './sessions/subagents'

package/src/mcp/connections.ts

@@ -12,7 +12,7 @@ import { isDir } from '../memory/store'
 import type { RunEvent } from '../sessions/contracts'
 import * as attachments from '../plugins/attachments'
 import { connectionScopeMigrationComplete } from './scopeMigration'
-import { connectionCapabilityId, connectionInputSchema, connectionSchema, type Connection, type ConnectionInput, type LaunchConfig, type Scope } from './types'
+import { connectionCapabilityId, connectionInputSchema, connectionSchema, type AppOAuthClients, type Connection, type ConnectionInput, type LaunchConfig, type Scope } from './types'
 
 const OAUTH_STATE = 'oauth'
 const OAUTH_CLIENT_ID = 'oauth_client_id'
@@ -175,7 +175,8 @@ export class Connections {
     stateDir: string,
     private readonly secrets: SecretStore,
     private readonly bus: Bus,
-    private readonly attachmentRoot: () => string | null = () => null
+    private readonly attachmentRoot: () => string | null = () => null,
+    private readonly appClients: AppOAuthClients | null = null
   ) {
     this.path = join(stateDir, 'connections.json')
   }
@@ -468,23 +469,49 @@ export class Connections {
 
   // ---- OAuth state --------------------------------------------------------------------------
 
-  private requireOauth(id: string): void {
-    if (!this.list().some((item) => item.id === id && item.kind === 'remote' && item.auth === 'oauth')) throw notFound('Connection')
+  private requireOauth(id: string): Connection {
+    const connection = this.list().find((item) => item.id === id && item.kind === 'remote' && item.auth === 'oauth')
+    if (!connection) throw notFound('Connection')
+    return connection
   }
 
-  /** The saved sign-in of a connection, with the client the user registered, if any. */
+  /** The saved sign-in of a connection, with the client the user registered, or the application's own. */
   async oauthLoad(id: string): Promise<Record<string, unknown>> {
-    this.requireOauth(id)
+    const connection = this.requireOauth(id)
     const saved = (parsedContainer((await this.secret(id, OAUTH_STATE)) ?? '') ?? {}) as Record<string, unknown>
     const state = Array.isArray(saved) ? {} : saved
-    const clientId = await this.secret(id, OAUTH_CLIENT_ID)
-    if (clientId) {
-      const clientSecret = await this.secret(id, OAUTH_CLIENT_SECRET)
-      state.staticClient = { client_id: clientId, ...(clientSecret ? { client_secret: clientSecret } : {}) }
+    delete state.staticClient
+    if (connection.oauthClient === 'app') {
+      const client = await this.appClient(connection)
+      if (client) state.staticClient = { client_id: client.clientId, ...(client.clientSecret ? { client_secret: client.clientSecret } : {}) }
+    } else if (connection.oauthClient === 'user' || connection.oauthClient === null) {
+      const clientId = await this.secret(id, OAUTH_CLIENT_ID)
+      if (clientId) {
+        const clientSecret = await this.secret(id, OAUTH_CLIENT_SECRET)
+        state.staticClient = { client_id: clientId, ...(clientSecret ? { client_secret: clientSecret } : {}) }
+      }
     }
     return state
   }
 
+  /** The client this application registered for a catalog entry, if it has one. */
+  private async appClient(connection: Connection): Promise<{ clientId: string; clientSecret?: string } | null> {
+    if (!connection.catalogId) return null
+    return (await this.appClients?.get(connection.catalogId)) ?? null
+  }
+
+  /** Whether a sign-in can be started: a dynamic server registers itself, the others need a client. */
+  async hasSignInClient(connection: Connection): Promise<boolean> {
+    if (connection.oauthClient === 'user') return (await this.secret(connection.id, OAUTH_CLIENT_ID)) !== null
+    if (connection.oauthClient === 'app') return (await this.appClient(connection)) !== null
+    return true
+  }
+
+  /** The catalog entries this application can sign in for without asking for a client. */
+  availableAppClients(): string[] {
+    return this.appClients?.ids() ?? []
+  }
+
   async oauthSave(id: string, state: Record<string, unknown>): Promise<void> {
     this.requireOauth(id)
     const { staticClient: _static, ...saved } = state ?? {}
@@ -515,7 +542,7 @@ export class Connections {
     if (remote) {
       if (!webUrl(connection.url)) throw invalid('Server URL must be an https:// address.')
       if (!['none', 'headers', 'oauth'].includes(connection.auth)) throw invalid('Unsupported sign-in method.')
-      if (connection.oauthClient && !['dynamic', 'user'].includes(connection.oauthClient)) throw invalid('Unsupported OAuth client.')
+      if (connection.oauthClient && !['dynamic', 'user', 'app'].includes(connection.oauthClient)) throw invalid('Unsupported OAuth client.')
       Object.assign(connection, { command: '', args: [], cwd: null })
       if (connection.auth !== 'oauth') Object.assign(connection, { oauthClient: null, oauthScopes: [] })
     } else {
@@ -533,7 +560,7 @@ export class Connections {
     connection.envKeys = [...(existing?.envKeys ?? [])]
     connection.headerKeys = [...(existing?.headerKeys ?? [])]
     // A sign-in belongs to one server and one client; never carry it to another.
-    const sameServer = (existing?.url ?? null) === connection.url && (existing?.auth ?? '') === connection.auth && !oauthCredentials
+    const sameServer = (existing?.url ?? null) === connection.url && (existing?.auth ?? '') === connection.auth && existing?.oauthClient === connection.oauthClient && existing?.catalogId === connection.catalogId && !oauthCredentials
     if (!sameServer || connection.auth !== 'oauth') await this.forgetSignIn(connection.id)
     connection.authState = connection.auth === 'oauth' ? (sameServer ? (existing?.authState ?? 'signed_out') : 'signed_out') : null
     if (oauthCredentials) {

package/src/mcp/service.test.ts

@@ -8,7 +8,7 @@ import { McpServer, WebStandardStreamableHTTPServerTransport } from '@modelconte
 import { afterEach, describe, expect, it } from 'vitest'
 
 import { memorySecretStore } from '../accounts/secrets'
-import { createHarness, type Harness } from '../harness'
+import { createHarness, type Harness, type HarnessOptions } from '../harness'
 import type { RunEvent } from '../sessions/contracts'
 import type { ToolPolicy } from '../sessions/policy'
 import type { PiSessionLike } from '../sessions/runner'
@@ -106,12 +106,12 @@ afterEach(async () => {
 const tick = (ms = 30) => new Promise((resolve) => setTimeout(resolve, ms))
 
 /** A harness with one live run whose session keeps going until the test releases it. */
-async function live(policy: ToolPolicy = {}) {
+async function live(policy: ToolPolicy = {}, extra: Partial<HarnessOptions> = {}) {
   let release: () => void = () => undefined
   const stateDir = mkdtempSync(join(tmpdir(), 'harness-mcp-state-'))
   const secrets = memorySecretStore()
   const session: PiSessionLike = { sessionId: 'native', subscribe: () => () => undefined, prompt: () => new Promise<void>((resolve) => (release = resolve)), sendCustomMessage: async () => undefined, abort: async () => release(), dispose: () => undefined }
-  const harness = createHarness({ dataRoot: mkdtempSync(join(tmpdir(), 'harness-mcp-data-')), stateDir, secrets, policy, sessionFactory: async () => session })
+  const harness = createHarness({ dataRoot: mkdtempSync(join(tmpdir(), 'harness-mcp-data-')), stateDir, secrets, policy, sessionFactory: async () => session, ...extra })
   open.push(harness)
   harness.accounts.create('Main', 'apiKey')
   const events: RunEvent[] = []
@@ -277,6 +277,7 @@ describe('remote connected apps', () => {
     await expect(harness.apps.save({ name: '', kind: 'local', command: 'x' })).rejects.toThrow('A name, executable')
     await expect(harness.apps.save({ ...local, env: { 'BAD NAME': 'x' } })).rejects.toThrow('environment variable')
     await expect(harness.apps.save({ ...remote, url: 'https://x.example/mcp', auth: 'headers', headers: { 'X-Key': 'a\nb' } })).rejects.toThrow('header')
+    await expect(harness.apps.save({ ...remote, url: 'https://x.example/mcp', auth: 'oauth', oauthClient: 'whoever' })).rejects.toThrow('Unsupported OAuth client')
     const workspace = await harness.apps.save({ name: 'Xingular Workspace', kind: 'workspace', command: process.execPath, enabled: true, global: true })
     expect(() => harness.apps.connections.allowTool(workspace.id, 'x_workspace_mutation_apply')).toThrow('one at a time')
     await harness.apps.remove(workspace.id)
@@ -373,4 +374,49 @@ describe('signing in to a remote connected app', () => {
     expect(server.seen.tokenRequests[0]).toContain('fixture-code')
     expect(server.seen.tokenRequests[0]).toMatch(/own-client|b3duLWNsaWVudDpvd24tc2VjcmV0/)
   })
+
+  it('signs in with the application\'s own client, keeps it out of storage, and offers it only for that catalog entry', async () => {
+    const server = await oauthFixture()
+    const { harness, secrets } = await live({}, { oauthClients: { ids: () => ['fixture-app'], get: async (id) => (id === 'fixture-app' ? { clientId: 'app-client', clientSecret: 'app-secret' } : null) } })
+    harness.bus.on((notice) => {
+      if (notice.type === 'connections.openUrl') void fetch(String(notice.url))
+    })
+    expect(harness.apps.appClients()).toEqual({ catalogIds: ['fixture-app'] })
+    const saved = await harness.apps.save({ name: 'App client', kind: 'remote', enabled: true, global: true, url: server.url, auth: 'oauth', oauthClient: 'app', catalogId: 'fixture-app', oauthScopes: ['read'] })
+    expect((await harness.apps.signIn(saved.id)).authState).toBe('signed_in')
+    // No client of its own is registered, and the application's client is what the provider sees.
+    expect(server.seen.registered).toBe(0)
+    expect(server.seen.authorizeUrls[0].searchParams.get('client_id')).toBe('app-client')
+    // Neither the saved connection nor the secret store ever holds the application's client secret.
+    expect(JSON.stringify(harness.apps.connections.list())).not.toContain('app-secret')
+    expect(JSON.stringify([...secrets.values.entries()])).not.toContain('app-secret')
+    expect(JSON.parse(secrets.values.get(`mcp--${saved.id}/oauth`)!).tokens).toMatchObject({ refresh_token: 'fixture-refresh' })
+  })
+
+  it('uses the application client and resets sign-in when switching from a saved user client', async () => {
+    const server = await oauthFixture()
+    const { harness, secrets } = await live({}, { oauthClients: { ids: () => ['fixture-app'], get: async (id) => (id === 'fixture-app' ? { clientId: 'app-client', clientSecret: 'app-secret' } : null) } })
+    harness.bus.on((notice) => {
+      if (notice.type === 'connections.openUrl') void fetch(String(notice.url))
+    })
+    const user = await harness.apps.save({ name: 'Switched client', kind: 'remote', enabled: true, global: true, url: server.url, auth: 'oauth', oauthClient: 'user', oauthCredentials: { clientId: 'user-client', clientSecret: 'user-secret' } })
+    const signedInUser = await harness.apps.signIn(user.id)
+    expect(signedInUser.authState).toBe('signed_in')
+
+    const app = await harness.apps.save({ ...user, oauthClient: 'app', catalogId: 'fixture-app' })
+    expect(app.authState).toBe('signed_out')
+    expect(secrets.values.has(`mcp--${user.id}/oauth`)).toBe(false)
+    await harness.apps.signIn(user.id)
+
+    expect(server.seen.authorizeUrls.map((url) => url.searchParams.get('client_id'))).toEqual(['user-client', 'app-client'])
+    expect(server.seen.tokenRequests[1]).toMatch(/app-client|YXBwLWNsaWVudDphcHAtc2VjcmV0/)
+  })
+
+  it('refuses an application sign-in this build has no client for, naming the reason', async () => {
+    const { harness } = await live()
+    const saved = await harness.apps.save({ name: 'No client', kind: 'remote', enabled: true, global: true, url: 'https://example.com/mcp', auth: 'oauth', oauthClient: 'app', catalogId: 'google-drive', oauthScopes: [] })
+    expect(harness.apps.appClients()).toEqual({ catalogIds: [] })
+    await expect(harness.apps.signIn(saved.id)).rejects.toThrow(/no app sign-in/)
+    expect(harness.apps.connections.find(saved.id).authState).toBe('signed_out')
+  })
 })

package/src/mcp/service.ts

@@ -20,7 +20,7 @@ import type { ToolSession, ToolSpec } from '../tools/types'
 import { allowed, Connections, webUrl } from './connections'
 import { isSignInRequired, McpManager, signInRequired } from './manager'
 import { signIn, type OAuthHost } from './oauth'
-import type { Connection, HttpConfig, LaunchConfig, McpSource, McpTrace } from './types'
+import type { AppOAuthClients, Connection, HttpConfig, LaunchConfig, McpSource, McpTrace } from './types'
 
 /** A session's access to the broker. A terminal session presents `token`; an SDK session holds the object. */
 export interface BrokerSession {
@@ -118,6 +118,8 @@ export interface ConnectedAppsOptions {
   bus: Bus
   runs: RunRegistry
   policy: ToolPolicy
+  /** The application's own registered OAuth clients, if it has any. */
+  oauthClients?: AppOAuthClients
 }
 
 /** The scope a plugin hook's connections are opened under: they belong to no session. */
@@ -134,7 +136,7 @@ export class ConnectedApps implements SessionBroker {
   private brokered: BrokeredTools | null = null
 
   constructor(private readonly options: ConnectedAppsOptions) {
-    this.connections = new Connections(options.stateDir, options.secrets, options.bus, () => options.env.root)
+    this.connections = new Connections(options.stateDir, options.secrets, options.bus, () => options.env.root, options.oauthClients ?? null)
     this.oauth = {
       clientName: options.env.productName,
       load: (id) => this.connections.oauthLoad(id),
@@ -469,7 +471,11 @@ export class ConnectedApps implements SessionBroker {
   async signIn(connectionId: string): Promise<Connection> {
     const connection = this.connections.find(connectionId)
     if (connection.kind !== 'remote' || connection.auth !== 'oauth') throw invalid('This connection does not use browser sign-in.')
-    if (connection.oauthClient === 'user' && !(await this.connections.hasOauthClient(connection.id))) throw invalid('Add your OAuth client ID before signing in.')
+    if (!(await this.connections.hasSignInClient(connection))) {
+      throw invalid(connection.oauthClient === 'app'
+        ? 'This connector has no app sign-in in this build. Enable its OAuth client or use your own client.'
+        : 'Add your OAuth client ID before signing in.')
+    }
     await signIn(this.oauth, (await this.connections.launch(connection)) as HttpConfig)
     const updated = this.connections.update(connectionId, (item) => Object.assign(item, { authState: 'signed_in', error: null }))
     await this.manager.close(connectionId)
@@ -477,6 +483,11 @@ export class ConnectedApps implements SessionBroker {
     return updated
   }
 
+  /** The catalog entries this application can sign in for, so a client need not be added by hand. */
+  appClients(): { catalogIds: string[] } {
+    return { catalogIds: this.connections.availableAppClients() }
+  }
+
   async signOut(connectionId: string): Promise<Connection> {
     const updated = await this.connections.signOut(connectionId)
     this.cancelConnection(connectionId)

package/src/mcp/types.ts

@@ -7,6 +7,16 @@ import { z } from 'zod'
 export const MCP_OAUTH_PORT = 47823
 export const MCP_OAUTH_REDIRECT_URL = `http://127.0.0.1:${MCP_OAUTH_PORT}/oauth/callback`
 
+/**
+ * The application's own registered OAuth clients, by catalog entry. A client supplied here is
+ * used for that sign-in only and is never written to the connection or the secret store.
+ */
+export interface AppOAuthClients {
+  /** The catalog entries this application can sign in for. */
+  ids(): string[]
+  get(catalogId: string): Promise<{ clientId: string; clientSecret?: string } | null>
+}
+
 /** Stable attachment key for a connected app's capability switch. */
 export const connectionCapabilityId = (id: string): string => `connected-apps/connection/${id}`