@xingular/harness 2.0.0 → 2.0.1-unstable

package/src/tools/pluginPropose.ts

@@ -1,41 +0,0 @@
-// Proposing a plugin: how an agent offers a person a new skill, instruction, or piece of code
-// that extends memory, the Wiki or history. It only proposes. A person accepts it, switches it
-// on and trusts its code; no tool does any of those for them.
-import { actorOf, type CallerContext } from '../memory/caller'
-import type { DispatchEnv } from '../memory/dispatch'
-import * as store from '../memory/store'
-import { EXTENDABLE, parkPluginProposal } from '../plugins/proposal'
-import type { ToolSpec } from './types'
-
-export const PLUGIN_PROPOSE = 'plugin_propose'
-
-const text = (value: unknown): string => (typeof value === 'string' ? value : '')
-
-export function pluginProposeTool(env: DispatchEnv, caller: CallerContext): ToolSpec {
-  return {
-    name: PLUGIN_PROPOSE,
-    label: 'Propose a plugin',
-    description:
-      'Propose a plugin for the user to review: a bundle of files that changes how agents work. Nothing is saved until the user accepts it, and its code never runs until they also switch it on and trust it. ' +
-      'Files by folder: skills/<name>/SKILL.md (a procedure, with name and description front matter), prompts/<name>.md (a slash command), extensions/<name>.ts (a Pi extension), ' +
-      'and hooks.mjs for code the harness runs after a change: `export default function (harness) { harness.on("memory.saved", async (event, ctx) => { await ctx.call("<connected app name>", "<tool>", { text: event.body }) }) }`. ' +
-      'Hook events: memory.saved, memory.block.changed, wiki.page.saved (each has id, title, body, actor) and history.run.ended (runId, status, goal). ' +
-      'ctx.call reaches only a connected-app tool the user marked to run without asking; put no key or password in a file. Do not include package.json.',
-    parameters: (Type) =>
-      Type.Object({
-        name: Type.String({ description: 'A short name, such as memory-to-docs' }),
-        description: Type.String({ description: 'One line the user reads first: what it does' }),
-        extends: Type.Optional(Type.Array(Type.String({ description: `One of ${EXTENDABLE.join(', ')}` }))),
-        reason: Type.Optional(Type.String({ description: 'Why you are proposing it' })),
-        files: Type.Array(Type.Object({ path: Type.String({ description: 'A path inside the plugin, such as hooks.mjs' }), content: Type.String() }), { maxItems: 40 })
-      }),
-    execute: async (input) => {
-      const files = (Array.isArray(input.files) ? input.files : []).map((file) => ({ path: text((file as { path?: unknown }).path), content: text((file as { content?: unknown }).content) }))
-      const extended = (Array.isArray(input.extends) ? input.extends : []).filter((part): part is string => typeof part === 'string')
-      const from = caller.agentName ? `${caller.agentName} (${actorOf(caller)})` : actorOf(caller)
-      const slug = parkPluginProposal(store.wikiDir(env.root), from, { name: text(input.name), description: text(input.description), extends: extended, reason: text(input.reason), files })
-      env.bus?.emit({ type: 'wiki.changed' })
-      return `The plugin "${slug}" is waiting in the Inbox. It is saved only if the user accepts it, and it does nothing until they switch it on${files.some((file) => file.path.startsWith('extensions/') || /^hooks\.m?js$/.test(file.path)) ? ' and trust its code' : ''}.`
-    }
-  }
-}

package/src/tools/registryWrite.test.ts

@@ -1,101 +0,0 @@
-import { mkdtempSync, readFileSync } from 'node:fs'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-import { afterEach, describe, expect, it } from 'vitest'
-
-import { memorySecretStore } from '../accounts/secrets'
-import { createHarness, type Harness } from '../harness'
-import * as attachments from '../plugins/attachments'
-import * as registry from '../skills/registry'
-import * as store from '../memory/store'
-import { registryTools } from './registryWrite'
-import type { ToolSession, ToolSpec } from './types'
-
-const open: Harness[] = []
-afterEach(async () => {
-  for (const harness of open.splice(0)) await harness.close()
-})
-
-function setup() {
-  const harness = createHarness({
-    dataRoot: mkdtempSync(join(tmpdir(), 'registry-write-data-')),
-    stateDir: mkdtempSync(join(tmpdir(), 'registry-write-state-')),
-    secrets: memorySecretStore()
-  })
-  open.push(harness)
-  /** Runs one of the tools as the given agent would see it. */
-  const call = (agentId: string, name: string, input: Record<string, unknown>) => {
-    const session = { caller: { agentId, agentName: 'Helper', actor: 'Chat', runId: 'run-1' }, allow: [], depth: 0, cwd: harness.env.root, capabilities: { version: 1, tools: [], connectors: [], contributions: [] } } as unknown as ToolSession
-    const tool = (registryTools({ harness })(session) as ToolSpec[]).find((candidate) => candidate.name === name)!
-    return tool.execute(input)
-  }
-  return { harness, root: harness.env.root, call }
-}
-
-describe('registry_write', () => {
-  it('writes a new skill on for the calling agent only, and records who wrote it', async () => {
-    const { root, call } = setup()
-    const reply = await call('agent-1', 'registry_write', { kind: 'skill', name: 'Release Notes', description: 'Write notes', body: 'Use short bullets.' })
-    expect(reply).toContain('on for you only')
-    expect(registry.list(root).some((item) => item.id === 'skills/release-notes')).toBe(true)
-    expect(registry.enabledFor(root, null, 'agent-1').map((item) => item.id)).toContain('skills/release-notes')
-    expect(registry.enabledFor(root, null, 'agent-2').map((item) => item.id)).not.toContain('skills/release-notes')
-    expect(readFileSync(join(store.wikiDir(root), 'log.md'), 'utf8')).toContain('Helper (Chat)')
-  })
-
-  it('leaves an item others already use unchanged and sends the new text to the Inbox', async () => {
-    const { root, call } = setup()
-    await call('agent-1', 'registry_write', { kind: 'rule', name: 'Be brief', description: 'Keep answers short', body: 'Short answers.' })
-    const choices = attachments.load(root)
-    attachments.set(choices, ['rules/be-brief'], {}, true, false)
-    attachments.save(root, choices)
-    const path = registry.list(root).find((item) => item.id === 'rules/be-brief')!.path
-    const before = readFileSync(path, 'utf8')
-
-    const reply = await call('agent-2', 'registry_write', { kind: 'rule', name: 'Be brief', description: 'Keep answers short', body: 'Different text.' })
-    expect(reply).toContain('Inbox')
-    expect(readFileSync(path, 'utf8')).toBe(before)
-  })
-
-  it('refuses a body that looks like a credential', async () => {
-    const { call } = setup()
-    await expect(call('agent-1', 'registry_write', { kind: 'prompt', name: 'Leak', description: 'x', body: 'key sk-ant-abc123' })).rejects.toThrow(/credential/)
-  })
-
-  it('rejects an unknown kind', async () => {
-    const { call } = setup()
-    await expect(call('agent-1', 'registry_write', { kind: 'page', name: 'x', description: 'x', body: 'x' })).rejects.toThrow(/skill, prompt, or rule/)
-  })
-})
-
-describe('plugin_write', () => {
-  const skillOnly = { name: 'Notes Helper', description: 'Adds a note skill', files: [{ path: 'skills/notes/SKILL.md', content: '---\nname: notes\ndescription: Notes\n---\n\nTake notes.' }] }
-
-  it('writes a plugin that is on for the calling agent only', async () => {
-    const { root, call } = setup()
-    const reply = await call('agent-1', 'plugin_write', skillOnly)
-    expect(reply).toContain('on for you only')
-    const choices = attachments.load(root)
-    expect(attachments.attached(choices, ['package:notes-helper'], { agentId: 'agent-1' }, false)).toBe(true)
-    expect(attachments.attached(choices, ['package:notes-helper'], { agentId: 'agent-2' }, false)).toBe(false)
-  })
-
-  it('trusts the code of a plugin that runs code, and only once it is written', async () => {
-    const { harness, call } = setup()
-    expect(harness.plugins.trust.list()).toEqual([])
-    const reply = await call('agent-1', 'plugin_write', {
-      name: 'Memory Mirror',
-      description: 'Mirrors saved facts',
-      extends: ['memory'],
-      files: [{ path: 'hooks.mjs', content: 'export default function () {}' }]
-    })
-    expect(reply).toContain('trusted')
-    expect(harness.plugins.trust.list()).toHaveLength(1)
-  })
-
-  it('refuses a plugin folder that already exists', async () => {
-    const { call } = setup()
-    await call('agent-1', 'plugin_write', skillOnly)
-    await expect(call('agent-1', 'plugin_write', skillOnly)).rejects.toThrow(/already a plugin folder/)
-  })
-})

package/src/tools/registryWrite.ts

@@ -1,182 +0,0 @@
-// Writing skills, rules, prompts and plugins directly, for the agent that wrote them. Nothing
-// goes through the Inbox first, but every write is recorded there, and a plugin's code runs only
-// once it is trusted. A change that would alter an item other people already use goes to the
-// Inbox instead, as before.
-import { join, resolve } from 'node:path'
-
-import { invalid } from '../core/errors'
-import type { Harness } from '../harness'
-import { actorOf, type CallerContext } from '../memory/caller'
-import { enqueueCuration } from '../memory/curation'
-import { inbox } from '../memory/operations'
-import { parkRegistryProposal } from '../memory/proposals'
-import { looksSecret } from '../memory/secrets'
-import * as store from '../memory/store'
-import { reindexQuietly } from '../memory/wikiIndex'
-import { attach, ensureAdopted, loadingFor, trust } from '../plugins/api'
-import * as attachments from '../plugins/attachments'
-import type { PluginDescriptor } from '../plugins/types'
-import { acceptPluginProposal, checkPluginProposal } from '../plugins/proposal'
-import * as registry from '../skills/registry'
-import type { ToolProvider, ToolSpec } from './types'
-
-export const REGISTRY_WRITE = 'registry_write'
-export const PLUGIN_WRITE = 'plugin_write'
-
-const MAX_BODY_BYTES = 64 * 1024
-const text = (value: unknown): string => (typeof value === 'string' ? value : '')
-
-/** The tools as a plugin, for an application that provides them. */
-export const REGISTRY_WRITE_PLUGIN: PluginDescriptor = {
-  id: 'registry-write',
-  title: 'Skills and plugins',
-  description: 'Lets an agent write a skill, rule, prompt or plugin directly. A new item is on only for the agent that wrote it. A plugin is switched on for that agent and its code is trusted only after it is written; an item already in use by others goes to the Inbox.',
-  manage: 'tools',
-  tools: [
-    { name: REGISTRY_WRITE, description: 'Write a skill, rule or prompt' },
-    { name: PLUGIN_WRITE, description: 'Write a plugin' }
-  ]
-}
-
-export interface RegistryToolOptions {
-  harness: Harness
-}
-
-/** The `registry_write` and `plugin_write` tools. Only the names a session allows are registered. */
-export function registryTools(options: RegistryToolOptions): ToolProvider {
-  return ({ caller }) => [registryWriteTool(options.harness, caller), pluginWriteTool(options.harness, caller)]
-}
-
-function actorLabel(caller: CallerContext): string {
-  return caller.agentName ? `${caller.agentName} (${actorOf(caller)})` : actorOf(caller)
-}
-
-function requireAgent(caller: CallerContext): string {
-  if (!caller.agentId) throw invalid('Only an agent can write skills, rules, prompts, or plugins.')
-  return caller.agentId
-}
-
-/**
- * Whether an existing item belongs to this agent alone: switched on for no one else, nowhere
- * wider, and not built in. Anything else is someone else's to review.
- */
-function ownedByCaller(choices: attachments.Attachments, id: string, agentId: string, builtin: boolean): boolean {
-  const where = attachments.describe(choices, id, builtin)
-  if (where.global || where.on.projectIds.length) return false
-  return where.on.agentIds.length === 1 && where.on.agentIds[0] === agentId
-}
-
-function registryWriteTool(harness: Harness, caller: CallerContext): ToolSpec {
-  return {
-    name: REGISTRY_WRITE,
-    label: caller.vaultAccess ? 'Propose a skill, rule or prompt' : 'Write a skill, rule or prompt',
-    description: caller.vaultAccess ? 'Submit a bounded text skill, rule or prompt for curator review. It stays inactive until reviewed; permissions and code trust remain unchanged.' :
-      'Write a skill, rule or prompt directly. It is on only for you until the user switches it on for others. ' +
-      'An item that others already use, or that is built in, is not changed: your text goes to the Inbox for the user to review. ' +
-      'A rule reaches every future prompt of the agents it is on for, so write one only when it should always apply.',
-    parameters: (Type) =>
-      Type.Object({
-        kind: Type.String({ description: 'skill, prompt, or rule' }),
-        name: Type.String({ description: 'A short name, such as release-notes' }),
-        description: Type.String({ description: 'One line the user reads first' }),
-        body: Type.String({ description: 'The text itself, as Markdown' }),
-        reason: Type.Optional(Type.String({ description: 'Why you are writing it' }))
-      }),
-    execute: async (input) => {
-      const agentId = requireAgent(caller)
-      const kind = text(input.kind)
-      const name = text(input.name).trim()
-      const description = text(input.description).trim()
-      const body = text(input.body)
-      const reason = text(input.reason).trim()
-      if (!['skill', 'prompt', 'rule'].includes(kind)) throw invalid('kind must be skill, prompt, or rule.')
-      if (!name || !body.trim()) throw invalid('A skill, prompt, or rule needs a name and a body.')
-      if (Buffer.byteLength(body, 'utf8') > MAX_BODY_BYTES) throw invalid('The body is larger than 64 KiB.')
-      if (looksSecret(body)) throw invalid('The text looks like a credential, so it was not saved.')
-
-      if (caller.vaultAccess === 'self' || caller.vaultAccess === 'propose' || caller.vaultAccess === 'curator') {
-        const job = enqueueCuration(harness.env.root, { kind: 'registry', proposal: { kind, name, description, body, reason }, caller })
-        harness.bus.emit({ type: 'wiki.changed' })
-        return `Submitted proposal ${job.id} for curator review. Nothing has been activated.`
-      }
-
-      const { root } = harness.env
-      const wiki = store.wikiDir(root)
-      const id = `${kind}s/${store.slug(name)}`
-      const existing = registry.list(root).find((item) => item.id === id)
-      const choices = attachments.load(root)
-      if (existing && !ownedByCaller(choices, id, agentId, !!existing.builtin)) {
-        const parked = parkRegistryProposal(wiki, { kind: 'agent', runId: caller.runId ?? null, actor: actorLabel(caller) }, { kind, name, description, body, reason })
-        harness.bus.emit({ type: 'wiki.changed' })
-        return `The ${kind} change (${parked}) is in the Wiki Inbox: "${id}" is already used by others, so the user reviews it before it changes.`
-      }
-
-      registry.writeItem(root, kind, name, description, body, reason || `Written by ${actorLabel(caller)}`, actorLabel(caller))
-      attachments.set(choices, [id], { agentId }, true, false)
-      attachments.save(root, choices)
-      reindexQuietly(root)
-      harness.bus.emit({ type: 'plugins.changed' })
-      inbox(wiki, 'applied', `Wrote ${kind} "${name}"`, `${reason || 'Written by an agent.'}\n\nBy ${actorLabel(caller)}. It is on only for that agent.`, [], null)
-      return `Saved the ${kind} "${id}". It is on for you only; the user can switch it on for everyone.`
-    }
-  }
-}
-
-function pluginWriteTool(harness: Harness, caller: CallerContext): ToolSpec {
-  return {
-    name: PLUGIN_WRITE,
-    label: caller.vaultAccess ? 'Propose a plugin' : 'Write a plugin',
-    description: caller.vaultAccess ? 'Submit a plugin bundle for curator and user review. It remains inactive and untrusted; executable code requires an explicit user trust decision. Include at most 40 bounded files; never include credentials.' :
-      'Write a plugin directly: a bundle of files that changes how agents work. It is switched on for you only. ' +
-      'If it contains code (extensions/ or hooks.mjs), that code is trusted and runs in your sessions; nobody else runs it. ' +
-      'Files by folder: skills/<name>/SKILL.md, prompts/<name>.md, extensions/<name>.ts, and hooks.mjs. Do not include package.json. Put no key or password in a file.',
-    parameters: (Type) =>
-      Type.Object({
-        name: Type.String({ description: 'A short name, such as memory-to-docs' }),
-        description: Type.String({ description: 'One line the user reads first' }),
-        extends: Type.Optional(Type.Array(Type.String({ description: 'memory, wiki, or history' }))),
-        reason: Type.Optional(Type.String({ description: 'Why you are writing it' })),
-        files: Type.Array(Type.Object({ path: Type.String({ description: 'A path inside the plugin' }), content: Type.String() }), { maxItems: 40 })
-      }),
-    execute: async (input) => {
-      const agentId = requireAgent(caller)
-      const files = (Array.isArray(input.files) ? input.files : []).map((file) => ({ path: text((file as { path?: unknown }).path), content: text((file as { content?: unknown }).content) }))
-      const proposal = {
-        name: text(input.name),
-        description: text(input.description),
-        extends: (Array.isArray(input.extends) ? input.extends : []).filter((part): part is string => typeof part === 'string'),
-        reason: text(input.reason),
-        files
-      }
-      const checked = checkPluginProposal(proposal)
-      if (caller.vaultAccess === 'self' || caller.vaultAccess === 'propose' || caller.vaultAccess === 'curator') {
-        const job = enqueueCuration(harness.env.root, { kind: 'plugin', proposal, caller })
-        harness.bus.emit({ type: 'wiki.changed' })
-        return `Submitted proposal ${job.id}. Executable code requires user review and trust.`
-      }
-      const { root } = harness.env
-      // Trust the packages that were there first, so the new one is not adopted with them.
-      await ensureAdopted(harness)
-      acceptPluginProposal(root, proposal)
-
-      let note = ''
-      try {
-        if (checked.runsCode) {
-          const loading = await loadingFor(harness, { agentId })
-          const folder = resolve(join(root, 'plugins', checked.slug))
-          const found = Object.entries(loading?.packageCode ?? {}).find(([dir]) => resolve(dir) === folder)
-          if (!found) throw new Error('its code was not found after it was saved')
-          await trust(harness, { agentId, hash: found[1].hash })
-        }
-        await attach(harness, { id: `package:${checked.slug}`, scope: { agentId } }, true)
-      } catch (error) {
-        note = ` It is saved but not switched on: ${error instanceof Error ? error.message : String(error)}. The user can switch it on in Plugins.`
-      }
-      harness.bus.emit({ type: 'plugins.changed' })
-      inbox(store.wikiDir(root), 'applied', `Wrote plugin "${checked.slug}"`, `${proposal.reason || 'Written by an agent.'}\n\nBy ${actorLabel(caller)}.${checked.runsCode ? ' Its code runs only for that agent.' : ''}`, [], null)
-      return note
-        ? `The plugin "${checked.slug}" was written.${note}`
-        : `The plugin "${checked.slug}" was written and is on for you only.${checked.runsCode ? ' Its code is trusted for your sessions.' : ''}`
-    }
-  }
-}

package/src/tools/spawnSubagent.ts

@@ -1,47 +0,0 @@
-import { HarnessError, invalid } from '../core/errors'
-import type { Subagents } from '../sessions/subagentService'
-import { SPAWN_SUBAGENT, WAIT_SUBAGENTS, SUBAGENT_RECEIPT, type SubagentReceipt, type SubagentResult } from '../sessions/subagents'
-import type { ToolResult, ToolSpec } from './types'
-
-export { SPAWN_SUBAGENT, SUBAGENT_RELATION, DEFAULT_SUBAGENT_DEPTH, MAX_SUBAGENT_DEPTH, subagentDepth, subagentReport, type SubagentOptions } from '../sessions/subagents'
-
-function reported(parentRunId: string, results: SubagentResult[], spawned?: string[]): ToolResult {
-  const included: SubagentResult[] = []
-  let length = 0
-  for (const result of results) {
-    if (length + result.text.length > 24_000 && included.length) break
-    included.push(result)
-    length += result.text.length + 300
-  }
-  const receipt: SubagentReceipt = { version: 1, ownerRunId: parentRunId, ...(spawned ? { spawned } : {}), delivered: included.map((result) => result.runId) }
-  return { text: JSON.stringify({ results: included, ...(results.length > included.length ? { remaining: results.slice(included.length).map((result) => result.runId) } : {}) }), details: { [SUBAGENT_RECEIPT]: receipt } }
-}
-
-export function subagentTools(service: Subagents, parentRunId: string): ToolSpec[] {
-  const execute = (fn: (input: Record<string, unknown>) => Promise<ToolResult>): ToolSpec['execute'] => async (input) => {
-    try { return await fn(input) } catch (error) {
-      if (error instanceof HarnessError) return error.message
-      throw error
-    }
-  }
-  return [{
-    name: SPAWN_SUBAGENT,
-    label: 'Start a subagent',
-    description: 'Start a fresh child run of yourself for independent work. Give a complete brief: the child has no conversation history and no more capabilities than you. Returns its run ID immediately by default so you can continue working. Results arrive automatically before you finish. Use wait_subagents to join selected children, or wait: true for an inline result. Stopping you stops your children.',
-    parameters: (Type) => Type.Object({ brief: Type.String(), tools: Type.Optional(Type.Array(Type.String())), wait: Type.Optional(Type.Boolean({ description: 'Wait for the child and return its result; default false' })) }),
-    execute: execute(async (input) => {
-      const child = await service.spawn({ parentRunId, brief: input.brief as string, tools: input.tools as string[] | undefined, wait: input.wait as boolean | undefined })
-      if (input.wait === true) return reported(parentRunId, service.results({ parentRunId, runIds: [child.runId] }), [child.runId])
-      return { text: JSON.stringify(child), details: { [SUBAGENT_RECEIPT]: { version: 1, ownerRunId: parentRunId, spawned: [child.runId] } satisfies SubagentReceipt } }
-    })
-  }, {
-    name: WAIT_SUBAGENTS,
-    label: 'Wait for subagents',
-    description: 'Wait for all selected direct subagents to settle and return their results, including failures. Omit runIds to select your current children. Do useful independent work before waiting; results also arrive automatically before your final reply.',
-    parameters: (Type) => Type.Object({ runIds: Type.Optional(Type.Array(Type.String())) }),
-    execute: execute(async (input) => {
-      if (input.runIds !== undefined && !Array.isArray(input.runIds)) throw invalid('runIds must be an array of child run IDs.')
-      return reported(parentRunId, await service.wait({ parentRunId, runIds: input.runIds as string[] | undefined }))
-    })
-  }]
-}

package/src/tools/types.ts

@@ -1,41 +0,0 @@
-// A tool as the harness holds it: described without Pi imports, so a provider can be written
-// against this package alone. The session turns each one into a Pi tool.
-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
-  /** Native-history metadata; never interpreted as model instructions. */
-  details?: Record<string, unknown>
-  image?: { data: string; mimeType: string }
-  /** References to content stored by the provider; bytes never enter the run-event stream. */
-  attachments?: ToolAttachmentRef[]
-}
-
-export interface ToolSpec {
-  name: string
-  label: string
-  description: string
-  /** Builds the TypeBox parameter schema. */
-  parameters: (type: typeof import('typebox').Type) => unknown
-  execute: (input: Record<string, unknown>) => Promise<string | ToolResult>
-}
-
-/** What a tool provider is told about the session it is building tools for. */
-export interface ToolSession {
-  run: ActiveRun
-  caller: CallerContext
-  /** The tool names switched on for this session. */
-  allow: readonly string[]
-  /** Hops from the user to this session (0 when the user started it). */
-  depth: number
-  /** The session's working folder. */
-  cwd: string
-  /** The capability set frozen when this run started. */
-  capabilities: CapabilitySet
-}
-
-/** Builds the tools a session may be given. Only those named in `allow` are registered. */
-export type ToolProvider = (session: ToolSession) => ToolSpec[] | Promise<ToolSpec[]>

package/src/web/safeRequest.ts

@@ -1,171 +0,0 @@
-// Reads a web address on behalf of an agent without reaching the machine's own network. The
-// address is checked before a request and again when the connection is made, so a name that
-// resolves to a private address, or changes between the check and the connection, is refused.
-import { lookup as dnsLookup, type LookupAddress } from 'node:dns'
-import { request as httpRequest, type IncomingMessage } from 'node:http'
-import { request as httpsRequest } from 'node:https'
-import { isIP, type LookupFunction } from 'node:net'
-
-export interface WebResponse {
-  status: number
-  contentType: string
-  body: Buffer
-  /** The body reached the byte limit and was cut short. */
-  truncated: boolean
-  /** The address finally read, after any redirects. */
-  url: URL
-}
-
-export interface WebRequestOptions {
-  headers?: Record<string, string>
-  /** Longest a single read may stay silent, and the most time the whole request may take. */
-  timeoutMs: number
-  maxBytes: number
-  maxRedirects?: number
-}
-
-/** Makes one read. Tests replace it; the default is `safeRequest`. */
-export type WebRequest = (url: URL, options: WebRequestOptions) => Promise<WebResponse>
-
-const USER_AGENT = 'Mozilla/5.0 (compatible; XingularHarness/0.1; +web tools)'
-const REDIRECT_CODES = new Set([301, 302, 303, 307, 308])
-
-/** Only plain web addresses: no other scheme, and no username or password in the address. */
-export function webAddress(input: string): URL {
-  let url: URL
-  try {
-    url = new URL(input.trim())
-  } catch {
-    throw new Error('That is not a web address.')
-  }
-  if (url.protocol !== 'http:' && url.protocol !== 'https:') throw new Error('Only http and https addresses can be read.')
-  if (url.username || url.password) throw new Error('Addresses with a username or password cannot be read.')
-  if (!url.hostname) throw new Error('That address has no host name.')
-  return url
-}
-
-/** Whether an address belongs to this machine, a private network, or is otherwise not public. */
-export function isPublicAddress(address: string): boolean {
-  const mapped = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/i.exec(address)
-  if (mapped) return isPublicIpv4(mapped[1])
-  if (address.includes(':')) return isPublicIpv6(address.toLowerCase())
-  return isPublicIpv4(address)
-}
-
-function isPublicIpv4(address: string): boolean {
-  const parts = address.split('.').map(Number)
-  if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) return false
-  const [a, b, c] = parts
-  if (a === 0 || a === 10 || a === 127 || a >= 224) return false
-  if (a === 100 && b >= 64 && b <= 127) return false
-  if (a === 169 && b === 254) return false
-  if (a === 172 && b >= 16 && b <= 31) return false
-  if (a === 192 && b === 168) return false
-  if (a === 192 && b === 0 && c === 0) return false
-  if (a === 198 && (b === 18 || b === 19)) return false
-  return true
-}
-
-function isPublicIpv6(address: string): boolean {
-  // Global unicast only (2000::/3), without documentation (2001:db8::/32), Teredo (2001::/32) or 6to4 (2002::/16), which carry IPv4 addresses.
-  const first = parseInt(address.split(':')[0] || '0', 16)
-  if (Number.isNaN(first) || first < 0x2000 || first > 0x3fff) return false
-  if (/^2001:db8(:|$)/.test(address) || /^2001:0{0,4}:/.test(address) || /^2002(:|$)/.test(address)) return false
-  return true
-}
-
-type LookupCallback = (error: NodeJS.ErrnoException | null, address: string | LookupAddress[], family?: number) => void
-
-/** A DNS lookup that refuses any address that is not public. It runs when the connection is made. */
-function publicLookupImpl(hostname: string, options: { all?: boolean }, callback: LookupCallback): void {
-  dnsLookup(hostname, { all: true, verbatim: true }, (error, addresses) => {
-    if (error) return callback(error, '', 4)
-    if (addresses.some((entry) => !isPublicAddress(entry.address))) {
-      return callback(Object.assign(new Error(`${hostname} is not a public address.`), { code: 'EPRIVATE' }), '', 4)
-    }
-    if (options.all) return callback(null, addresses)
-    callback(null, addresses[0].address, addresses[0].family)
-  })
-}
-
-export const publicLookup = publicLookupImpl as unknown as LookupFunction
-
-/**
- * A literal address is never looked up, so it is checked here. A name is checked by the lookup
- * at connection time.
- */
-function assertReachable(url: URL): void {
-  const host = url.hostname.replace(/^\[|\]$/g, '')
-  if (isIP(host) && !isPublicAddress(host)) throw Object.assign(new Error(`${host} is not a public address.`), { code: 'EPRIVATE' })
-}
-
-/** Reads a web address, following redirects one at a time, each checked the same way. */
-export const safeRequest: WebRequest = async (start, options) => {
-  let url = start
-  for (let hop = 0; ; hop += 1) {
-    assertReachable(url)
-    const response = await readOnce(url, options)
-    if (REDIRECT_CODES.has(response.status) && response.location) {
-      if (hop >= (options.maxRedirects ?? 5)) throw new Error('The address redirected too many times.')
-      url = webAddress(new URL(response.location, url).toString())
-      continue
-    }
-    return { status: response.status, contentType: response.contentType, body: response.body, truncated: response.truncated, url }
-  }
-}
-
-function readOnce(url: URL, options: WebRequestOptions): Promise<WebResponse & { location?: string }> {
-  return new Promise((resolve, reject) => {
-    const start = (url.protocol === 'https:' ? httpsRequest : httpRequest) as typeof httpRequest
-    let settled = false
-    const finish = (value: WebResponse & { location?: string }): void => {
-      if (settled) return
-      settled = true
-      clearTimeout(total)
-      resolve(value)
-    }
-    const fail = (error: Error): void => {
-      if (settled) return
-      settled = true
-      clearTimeout(total)
-      reject(error)
-    }
-    const request = start(url, {
-      method: 'GET',
-      headers: { 'user-agent': USER_AGENT, accept: 'text/html,text/plain,application/json;q=0.9,*/*;q=0.5', ...options.headers },
-      lookup: publicLookup,
-      timeout: options.timeoutMs
-    }, (response: IncomingMessage) => {
-      const status = response.statusCode ?? 0
-      const location = response.headers.location
-      if (REDIRECT_CODES.has(status) && location) {
-        response.resume()
-        finish({ status, contentType: '', body: Buffer.alloc(0), truncated: false, url, location })
-        return
-      }
-      const chunks: Buffer[] = []
-      let size = 0
-      let truncated = false
-      const done = (): void => finish({ status, contentType: String(response.headers['content-type'] ?? ''), body: Buffer.concat(chunks), truncated, url })
-      response.on('data', (chunk: Buffer) => {
-        const room = options.maxBytes - size
-        const kept = chunk.length > room ? chunk.subarray(0, Math.max(room, 0)) : chunk
-        chunks.push(kept)
-        size += kept.length
-        if (kept.length < chunk.length) {
-          truncated = true
-          response.destroy()
-          done()
-        }
-      })
-      response.on('error', (error) => (truncated ? done() : fail(error)))
-      response.on('end', done)
-      response.on('close', done)
-    })
-    // The whole request is capped as well as each silent stretch, so a slow trickle cannot hold a turn open.
-    const total = setTimeout(() => request.destroy(new Error('The address took too long to answer.')), options.timeoutMs * 3)
-    request.on('timeout', () => request.destroy(new Error('The address took too long to answer.')))
-    request.on('error', fail)
-    request.end()
-  })
-}

package/src/web/text.ts

@@ -1,53 +0,0 @@
-// Turns a fetched page into the readable text an agent can use. This is a plain reduction, not a
-// browser: scripts, styles and markup go, block boundaries become line breaks, entities decode.
-const ENTITIES: Record<string, string> = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ', mdash: '—', ndash: '–', hellip: '…', copy: '©' }
-
-export function decodeEntities(text: string): string {
-  return text.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (match, name: string) => {
-    if (name[0] === '#') {
-      const code = name[1] === 'x' || name[1] === 'X' ? parseInt(name.slice(2), 16) : parseInt(name.slice(1), 10)
-      return Number.isFinite(code) && code > 0 && code <= 0x10ffff ? String.fromCodePoint(code) : match
-    }
-    return ENTITIES[name.toLowerCase()] ?? match
-  })
-}
-
-export function pageTitle(html: string): string {
-  const match = /<title[^>]*>([\s\S]*?)<\/title>/i.exec(html)
-  return match ? decodeEntities(match[1]).replace(/\s+/g, ' ').trim() : ''
-}
-
-const BLOCK_TAGS = /<\/?(?:p|div|br|li|ul|ol|h[1-6]|tr|table|section|article|header|footer|nav|main|blockquote|pre|hr|dt|dd|figure|figcaption)\b[^>]*>/gi
-
-/** Readable text of an HTML page, with at most `limit` characters. */
-export function htmlToText(html: string, limit: number): { text: string; truncated: boolean } {
-  const plain = html
-    .replace(/<!--[\s\S]*?-->/g, ' ')
-    .replace(/<(script|style|noscript|template|svg|iframe|head|title)\b[^>]*>[\s\S]*?<\/\1\s*>/gi, ' ')
-    .replace(BLOCK_TAGS, '\n')
-    .replace(/<[^>]+>/g, ' ')
-  const lines = decodeEntities(plain)
-    .split('\n')
-    .map((line) => line.replace(/\s+/g, ' ').trim())
-  const text = lines.reduce<string[]>((kept, line) => {
-    // One blank line between paragraphs at most.
-    if (!line && (!kept.length || !kept[kept.length - 1])) return kept
-    kept.push(line)
-    return kept
-  }, []).join('\n').trim()
-  return text.length > limit ? { text: text.slice(0, limit), truncated: true } : { text, truncated: false }
-}
-
-/** Text of a plain-text or JSON body, with at most `limit` characters. */
-export function plainText(body: string, limit: number): { text: string; truncated: boolean } {
-  const text = body.trim()
-  return text.length > limit ? { text: text.slice(0, limit), truncated: true } : { text, truncated: false }
-}
-
-export function isHtmlType(contentType: string): boolean {
-  return /^(?:text\/html|application\/xhtml\+xml)\b/i.test(contentType)
-}
-
-export function isTextType(contentType: string): boolean {
-  return /^(?:text\/|application\/(?:json|xml|xhtml\+xml|ld\+json)\b)/i.test(contentType) || contentType === ''
-}