@xingular/harness 0.1.0 → 0.1.2

package/src/plugins/catalogue.ts

@@ -75,6 +75,7 @@ function fromDescriptor(descriptor: PluginDescriptor, source: PluginSource, atta
     required: descriptor.required ?? null,
     manage: descriptor.manage ?? (descriptor.tools?.length ? 'tools' : null),
     settings: (descriptor.settings ?? []).map((setting) => ({ ...setting, value: settingValue(setting, attachments?.settings[descriptor.id]) })),
+    connectorTemplates: descriptor.connectorTemplates ?? [],
     attachment: switchable ? describe(attachments!, descriptor.id, switchable.on) : null,
     contributions: [
       ...(descriptor.code ?? []).map((code) => contribution(descriptor.id, 'code', code.name, { description: code.description, state: on ? 'on' : 'off' })),
@@ -172,7 +173,7 @@ function foundContribution(plugin: string, item: Found, trusted: Trusted, input:
   return contribution(plugin, kind, name, { ...rest, description: description ?? '', path: item.path })
 }
 
-const empty = (id: string, title: string, description: string, source: PluginSource, path: string | null): Plugin => ({ id, title, description, version: null, source, path, runsCode: false, trust: 'none', code: null, install: null, extends: [], required: null, manage: 'files', settings: [], attachment: null, contributions: [] })
+const empty = (id: string, title: string, description: string, source: PluginSource, path: string | null): Plugin => ({ id, title, description, version: null, source, path, runsCode: false, trust: 'none', code: null, install: null, extends: [], required: null, manage: 'files', settings: [], connectorTemplates: [], attachment: null, contributions: [] })
 
 export function catalogue(input: CatalogueInput): Plugin[] {
   const plugins = new Map<string, Plugin>()
@@ -209,7 +210,7 @@ export function catalogue(input: CatalogueInput): Plugin[] {
         const install = item.project ? null : item.packageRoot.startsWith(`${input.packagesDir}/`) ? ({ kind: 'folder', source: item.packageRoot } as const) : item.source ? ({ kind: 'settings', source: item.source } as const) : null
         // Only parts that exist can be extended; a made-up name is dropped.
         const extended = manifest.extends.filter((part) => input.descriptors.some((descriptor) => descriptor.id === part))
-        plugin = { ...empty(id, manifest.name, manifest.description, item.project ? 'project' : 'package', item.packageRoot), version: manifest.version, install, extends: extended }
+        plugin = { ...empty(id, manifest.name, manifest.description, item.project ? 'project' : 'package', item.packageRoot), version: manifest.version, install, extends: extended, connectorTemplates: manifest.connectorTemplates }
       } else if (item.origin === 'home') plugin = empty(id, 'Home folder skills', 'Skills in the .agents folder of your home folder. Pi reads them for every account.', 'home', dirname(dirname(item.path)))
       else if (item.origin === 'project') plugin = empty(id, 'Project folder', 'Found in the working folder: its .pi and .agents folders, and the instruction files Pi reads on the way up from it.', 'project', input.cwd)
       else plugin = empty(id, 'Shared Pi folder', 'Extensions, skills, prompts and instruction files in the folder every account shares.', 'shared', input.sharedDir)

package/src/plugins/manifest.ts

@@ -1,8 +1,10 @@
 // What a package says about itself in its `package.json`: Pi's own fields, and under `harness`
 // which part of the harness it extends and the file of hooks the harness runs for it.
 import { basename, join } from 'node:path'
+import { z } from 'zod'
 
 import { readJsonOr, safeRelative } from '../core/fs'
+import type { ConnectorTemplate } from './types'
 
 export interface PackageManifest {
   name: string
@@ -12,6 +14,8 @@ export interface PackageManifest {
   extends: string[]
   /** The hooks file, inside the package, or `null` when it has none. */
   hooks: string | null
+  /** Data-only remote connector forms. Invalid templates are ignored; none can carry credentials. */
+  connectorTemplates: ConnectorTemplate[]
 }
 
 interface Raw {
@@ -21,6 +25,30 @@ interface Raw {
   harness?: unknown
 }
 
+const connectorTemplateSchema = z.object({
+  id: z.string().regex(/^[a-z0-9-]+$/),
+  name: z.string().min(1).max(120),
+  description: z.string().max(500),
+  url: z.string().url().startsWith('https://'),
+  auth: z.enum(['none', 'headers', 'oauth']),
+  oauthClient: z.enum(['dynamic', 'user']).nullable(),
+  oauthScopes: z.array(z.string().max(500)).max(30),
+  docsUrl: z.string().url().startsWith('https://').nullable(),
+  fields: z.array(z.object({
+    header: z.string().regex(/^[A-Za-z0-9_-]+$/),
+    label: z.string().min(1).max(120),
+    prefix: z.string().max(100),
+    help: z.string().max(500)
+  }).strict()).max(12),
+  setup: z.array(z.string().max(1000)).max(20),
+  notice: z.string().max(1000).nullable()
+}).strict().superRefine((template, context) => {
+  const oauth = template.auth === 'oauth'
+  const headers = template.auth === 'headers'
+  if (oauth !== (template.oauthClient !== null)) context.addIssue({ code: 'custom', message: 'OAuth templates must state a client type and other templates must not.', path: ['oauthClient'] })
+  if (headers !== (template.fields.length > 0)) context.addIssue({ code: 'custom', message: 'Header templates must declare input fields and other templates must not.', path: ['fields'] })
+})
+
 /** A path inside the package, or `null` for one that is missing, absolute, or climbs out of it. */
 function inside(path: unknown): string | null {
   if (typeof path !== 'string' || !path.trim()) return null
@@ -33,12 +61,16 @@ function inside(path: unknown): string | null {
 
 export function packageManifest(packageRoot: string): PackageManifest {
   const manifest = readJsonOr<Raw>(join(packageRoot, 'package.json'), {})
-  const own = (manifest.harness && typeof manifest.harness === 'object' && !Array.isArray(manifest.harness) ? manifest.harness : {}) as { extends?: unknown; hooks?: unknown }
+  const own = (manifest.harness && typeof manifest.harness === 'object' && !Array.isArray(manifest.harness) ? manifest.harness : {}) as { extends?: unknown; hooks?: unknown; connectors?: unknown }
   return {
     name: typeof manifest.name === 'string' && manifest.name ? manifest.name : basename(packageRoot),
     description: typeof manifest.description === 'string' ? manifest.description : '',
     version: typeof manifest.version === 'string' ? manifest.version : null,
     extends: (Array.isArray(own.extends) ? own.extends : typeof own.extends === 'string' ? [own.extends] : []).filter((id): id is string => typeof id === 'string' && !!id),
-    hooks: inside(own.hooks)
+    hooks: inside(own.hooks),
+    connectorTemplates: (Array.isArray(own.connectors) ? own.connectors : []).flatMap((value) => {
+      const parsed = connectorTemplateSchema.safeParse(value)
+      return parsed.success ? [parsed.data] : []
+    })
   }
 }

package/src/plugins/plugins.ts

@@ -78,6 +78,8 @@ export function packageFolders(directory: string | null): string[] {
 export interface LoadingInput extends ResolveInput {
   /** Who the session is for. Something switched off for this agent or project does not load. */
   caller?: AttachScope
+  /** The contributions frozen for a run. When present, this snapshot governs loading. */
+  contributions?: readonly string[]
 }
 
 /** Which code a person trusted: the working folder's as a whole, and each installed package's. */
@@ -142,8 +144,11 @@ export class Plugins {
       if (item.kind === 'hook') return !attached(choices, [pluginIdOf(item)], {}, true)
       return !attached(choices, foundIds(item), input.caller ?? {}, true)
     }
-    const detached = found.filter(off).map((item) => item.path)
-    const chosen = found.filter((item) => loads(item, trusted) && !detached.includes(item.path))
+    const allowed = (item: Found): boolean => input.contributions === undefined
+      ? !off(item)
+      : input.contributions.includes(foundIds(item)[0])
+    const detached = found.filter((item) => !allowed(item)).map((item) => item.path)
+    const chosen = found.filter((item) => loads(item, trusted) && allowed(item))
     const paths = (kind: Found['kind'], builtin: boolean): string[] => chosen.filter((item) => item.kind === kind && (item.origin === 'builtin') === builtin).map((item) => item.path)
     return {
       extensionPaths: paths('extension', false),
@@ -154,7 +159,7 @@ export class Plugins {
       hooks: chosen.filter((item) => item.kind === 'hook' && item.packageRoot).map((item) => ({ path: item.path, packageRoot: item.packageRoot!, hash: packageCodeState[item.packageRoot!]?.hash ?? '' })),
       found,
       detached,
-      resourceAllowed: (item) => !off(item),
+      resourceAllowed: allowed,
       projectCode: projectCodeState,
       packageCode: packageCodeState
     }

package/src/plugins/types.ts

@@ -65,6 +65,8 @@ export interface Plugin {
   manage: PluginManage | null
   /** Numbers a person can set on it, each with its current value. */
   settings: (PluginSetting & { value: number })[]
+  /** Declarative connector setup templates; listing one never creates or enables a connection. */
+  connectorTemplates: ConnectorTemplate[]
   /** Where the whole plugin is switched on and off, or `null` when only its parts are, or nothing is. */
   attachment: Attachment | null
   contributions: Contribution[]
@@ -80,6 +82,21 @@ export interface PluginSetting {
   max: number
 }
 
+/** A remote connector setup form. It contains no endpoint credentials or saved connection state. */
+export interface ConnectorTemplate {
+  id: string
+  name: string
+  description: string
+  url: string
+  auth: 'none' | 'headers' | 'oauth'
+  oauthClient: 'dynamic' | 'user' | null
+  oauthScopes: string[]
+  docsUrl: string | null
+  fields: { header: string; label: string; prefix: string; help: string }[]
+  setup: string[]
+  notice: string | null
+}
+
 /** What a part of the harness, or the embedding application, says about itself. Data only. */
 export interface PluginDescriptor {
   id: string
@@ -97,6 +114,8 @@ export interface PluginDescriptor {
   switchable?: { on: boolean }
   /** Numbers a person can set on it. */
   settings?: PluginSetting[]
+  /** Remote connector setup templates; users must add, configure and enable each connection. */
+  connectorTemplates?: ConnectorTemplate[]
   /** Code of its own that runs in a session. */
   code?: { name: string; description: string }[]
 }

package/src/prompt/compile.ts

@@ -405,10 +405,10 @@ function hostSection(host: HostSection, kept: boolean): Section | null {
 }
 
 /** Compiles the pack for a caller. It only reads the data root. */
-export function compile(env: HarnessEnv, context: CallerContext, launch: Launch = {}): ContextPack {
+export function compile(env: HarnessEnv, context: CallerContext, launch: Launch = {}, contributions?: readonly string[]): ContextPack {
   const { root } = env
   const wiki = store.wikiDir(root)
-  const active = registry.enabledFor(root, context.projectId ?? null, context.agentId ?? null)
+  const active = registry.enabledFor(root, context.projectId ?? null, context.agentId ?? null, contributions)
   const groups = toolGroups(context, launch)
   const contextProfile = profileFor(root, context)
   const keep = (id: string): boolean => id === 'references' || keeps(contextProfile, id)
@@ -573,8 +573,8 @@ function sameSection(left: Section | undefined, right: Section | undefined): boo
  * Recording the current pack does not mark an update delivered: the session saves that snapshot
  * only when it appends the corresponding context message.
  */
-export function sessionLaunch(env: HarnessEnv, context: CallerContext, launch: Launch, historyFile: string | null): { system: string; update: ContextUpdate | null } {
-  const pack = compile(env, context, launch)
+export function sessionLaunch(env: HarnessEnv, context: CallerContext, launch: Launch, historyFile: string | null, contributions?: readonly string[]): { system: string; update: ContextUpdate | null } {
+  const pack = compile(env, context, launch, contributions)
   const dynamic = [...BUILT_IN_DYNAMIC, ...(launch.sections ?? []).filter((host) => host.dynamic).map((host) => ({ id: host.id, order: host.order }))]
     .map((slot, index) => ({ ...slot, index }))
     .sort((left, right) => left.order - right.order || left.index - right.index)

package/src/server/methods.ts

@@ -10,6 +10,7 @@ import { HarnessError, invalid } from '../core/errors'
 import { projectsOrNone } from '../core/projects'
 import * as capabilities from '../capabilities/api'
 import { loadRun as loadCapabilitySnapshot } from '../capabilities/runSnapshot'
+import { capabilitySet } from '../capabilities/runSnapshot'
 import type { Harness } from '../harness'
 import * as blocks from '../memory/blocks'
 import { validateScopeIds } from '../mcp/connections'
@@ -255,6 +256,11 @@ export function methods(harness: Harness): Record<string, Handler> {
     'capabilities.detach': (params: Params) => capabilities.switchCapability(harness, { ...pluginScope(params), id: text(params, 'id'), scope: params.scope ?? null }, false),
     'capabilities.resolve': (params: Params) => capabilities.resolve(harness, { ...pluginScope(params), tools: Array.isArray(params.tools) ? params.tools.filter((item: unknown): item is string => typeof item === 'string') : [] }),
     'capabilities.run': (params: Params) => loadCapabilitySnapshot(root(), text(params, 'runId')),
+    'capabilities.intersect': (params: Params) => capabilities.toolIntersection(
+      capabilitySet(params.parent),
+      capabilitySet(params.assignee),
+      params.tools === undefined ? undefined : Array.isArray(params.tools) ? params.tools.filter((item: unknown): item is string => typeof item === 'string') : []
+    ),
 
     // ---- Runs --------------------------------------------------------------------------------------
     'runs.load': (params: Params) => snapshot(root(), text(params, 'runId')),

package/src/sessions/sessions.ts

@@ -83,15 +83,15 @@ export interface SessionsOptions {
   /** Chooses what a session loads. Without it Pi discovers extensions and skills on its own. */
   plugins?: Plugins
   /** Resolves the caller's capability set from the harness's stores. */
-  resolveCapabilities?: (caller: CallerContext, tools: readonly string[]) => Promise<CapabilitySet>
+  resolveCapabilities?: (caller: CallerContext, tools: readonly string[], cwd: string) => Promise<CapabilitySet>
   factory?: SessionFactory
 }
 
 /** The harness's own plugins a person switched on for this caller, with the numbers they set. */
-function firstPartyFor(root: string, caller: CallerContext): InlineExtension[] {
+function firstPartyFor(root: string, contributions: readonly string[]): InlineExtension[] {
   const choices = attachments.load(root)
-  const scope = { agentId: caller.agentId ?? null, projectId: caller.projectId ?? null }
-  return firstPartyExtensions((id) => attachments.attached(choices, [id], scope, FIRST_PARTY_PLUGINS.find((plugin) => plugin.id === id)?.switchable?.on ?? false), choices.settings)
+  const allowed = new Set(contributions)
+  return firstPartyExtensions((id) => FIRST_PARTY_PLUGINS.find((plugin) => plugin.id === id)?.code?.some((code) => allowed.has(`${id}/code/${code.name}`)) ?? false, choices.settings)
 }
 
 export class Sessions {
@@ -161,7 +161,7 @@ export class Sessions {
       ...(broker?.toolNames ?? [])
     ])]
     const available = this.options.resolveCapabilities
-      ? await this.options.resolveCapabilities(caller, requestedTools)
+      ? await this.options.resolveCapabilities(caller, requestedTools, input.cwd)
       : { version: 1 as const, tools: requestedTools, connectors: [], contributions: [] }
     const requested = input.capabilities ? parseCapabilitySet(input.capabilities) : available
     const capabilities: CapabilitySet = {
@@ -222,7 +222,7 @@ export class Sessions {
         connectionTools: (launch.connectionTools ?? []).filter((name) => capabilities.tools.includes(name)),
         toolGroups: launch.toolGroups?.map((group) => ({ ...group, tools: group.tools.filter((name) => capabilities.tools.includes(name)) })).filter((group) => group.tools.length > 0)
       }
-      ;({ system, update } = sessionLaunch(this.env, caller, effectiveLaunch, historyFile))
+      ;({ system, update } = sessionLaunch(this.env, caller, effectiveLaunch, historyFile, capabilities.contributions))
     } catch (error) {
       fail(error)
       throw error
@@ -239,7 +239,7 @@ export class Sessions {
     try {
       const tools: ToolSpec[] = [
         ...(broker ? broker.tools(session, { readOnly: typeof input.connections === 'object' && input.connections.readOnly === true }) : []),
-        ...memoryTools(this.options.env, caller),
+        ...memoryTools(this.options.env, caller, capabilities.contributions),
         askUserTool(run),
         pluginProposeTool(this.options.env, caller)
       ]
@@ -257,9 +257,9 @@ export class Sessions {
         preamble: input.preamble ?? null,
         automatic: input.automatic,
         account: context,
-        resources: registry.resources(root, caller.projectId ?? null, caller.agentId ?? null),
-        inline: [...firstPartyFor(root, caller), runLineageJoin(root, runId)],
-        ...(plugins ? { plugins: { loading: () => plugins.loading({ cwd: input.cwd, agentDir: context.configDir, install: true, caller: { agentId: caller.agentId ?? null, projectId: caller.projectId ?? null } }), loaded: (extensions) => plugins.loaded(extensions) } } : {}),
+        resources: registry.resources(root, caller.projectId ?? null, caller.agentId ?? null, capabilities.contributions),
+        inline: [...firstPartyFor(root, capabilities.contributions), runLineageJoin(root, runId)],
+        ...(plugins ? { plugins: { loading: () => plugins.loading({ cwd: input.cwd, agentDir: context.configDir, install: true, caller: { agentId: caller.agentId ?? null, projectId: caller.projectId ?? null }, contributions: capabilities.contributions }), loaded: (extensions) => plugins.loaded(extensions) } } : {}),
         system,
         update
       }

package/src/skills/registry.ts

@@ -31,6 +31,18 @@ export interface RegistryItem {
   builtin?: true
 }
 
+/** The capability id used when this registry item is shown in the plugin catalogue. */
+export function contributionId(item: Pick<RegistryItem, 'id' | 'builtin'>): string {
+  return `${item.builtin ? 'included' : 'yours'}/${item.id}`
+}
+
+/** Limits registry items to the contributions frozen for a run. `undefined` means no limit. */
+export function limitToContributions(items: readonly RegistryItem[], contributions?: readonly string[]): RegistryItem[] {
+  if (contributions === undefined) return [...items]
+  const allowed = new Set(contributions)
+  return items.filter((item) => allowed.has(contributionId(item)))
+}
+
 export interface SkillBundleInput {
   name: string
   files: { path: string; content: string; encoding: 'utf8' | 'base64' }[]
@@ -138,7 +150,8 @@ export const isItemId = (id: string): boolean => KINDS.some((kind) => id.startsW
  * Items active for a caller. A built-in is on until it is switched off; a person's own is off
  * until it is switched on, everywhere, for the caller's project, or for the calling agent.
  */
-export function enabledFor(root: string, projectId: string | null, agentId: string | null = null): RegistryItem[] {
+export function enabledFor(root: string, projectId: string | null, agentId: string | null = null, contributions?: readonly string[]): RegistryItem[] {
+  if (contributions !== undefined) return limitToContributions(list(root), contributions)
   const choices = attachments.load(root)
   return list(root).filter((item) => attachments.attached(choices, [item.id], { agentId, projectId }, !!item.builtin))
 }
@@ -160,8 +173,8 @@ export interface RegistryResources {
 }
 
 /** What a Pi session needs to load enabled items natively. Rule text reaches the model through the compiled prompt. */
-export function resources(root: string, projectId: string | null, agentId: string | null = null): RegistryResources {
-  const items = enabledFor(root, projectId, agentId)
+export function resources(root: string, projectId: string | null, agentId: string | null = null, contributions?: readonly string[]): RegistryResources {
+  const items = enabledFor(root, projectId, agentId, contributions)
   return {
     ids: items.map((item) => item.id),
     skillPaths: items.filter((item) => item.kind === 'skills').map((item) => item.path),

package/src/terminal/piExtension.ts

@@ -86,7 +86,8 @@ export default async function (pi: ExtensionAPI) {
           if (command?.type === 'interrupt') context?.abort()
           else if (command?.type === 'send') {
             if (context?.ui.getEditorText().trim()) throw new Error('The terminal contains a user draft.')
-            pi.sendUserMessage(command.text!)
+            // Pi 1.2 needs deliverAs while a run is busy; a message sent then waits for that run to finish.
+            pi.sendUserMessage(command.text!, context?.isIdle() === false ? { deliverAs: 'followUp' } : undefined)
           }
         })
         .catch(() => {
@@ -104,7 +105,8 @@ export default async function (pi: ExtensionAPI) {
     usage = emptyUsage()
     reasoningTokens = undefined
     costReported = false
-    await terminalCall('begin', { text: event.prompt })
+    // A run a plugin starts with a custom message has no user prompt to record; it still begins a turn.
+    await terminalCall('begin', { text: event.messageType === 'user' ? event.prompt : '' })
   })
   pi.on('message_end', async (event) => {
     if (event.message.role !== 'assistant') return

package/src/tools/memoryTools.ts

@@ -4,7 +4,7 @@ import type { CallerContext } from '../memory/caller'
 import { describeTool, WIKI_AGENT_TOOLS } from './definitions'
 import type { ToolSpec } from './types'
 
-export function memoryTools(env: DispatchEnv, context: CallerContext): ToolSpec[] {
+export function memoryTools(env: DispatchEnv, context: CallerContext, contributions?: readonly string[]): ToolSpec[] {
   return WIKI_AGENT_TOOLS.map((tool) => ({
     name: tool.name,
     label: tool.label,
@@ -12,7 +12,7 @@ export function memoryTools(env: DispatchEnv, context: CallerContext): ToolSpec[
     parameters: (Type) => Type.Unsafe(tool.parameters),
     execute: async (input) => {
       try {
-        return dispatch(env, context, tool.call, input) || 'Nothing found.'
+        return dispatch(env, context, tool.call, input, contributions) || 'Nothing found.'
       } catch (error) {
         // The model sees the reason and can adjust, rather than the run failing.
         return `The Wiki could not do that: ${error instanceof Error ? error.message : String(error)}`