@xingular/harness 2.0.0 → 2.0.1-unstable

package/dist/sdk/plugins/surfaces.js

@@ -0,0 +1,11 @@
+/** A short badge for a list row: `better in the app`, or nothing. */
+export function surfaceBadge(surfaces) {
+    if (!surfaces)
+        return '';
+    return surfaces.terminal === 'unavailable' ? 'app only' : 'better in the app';
+}
+/** The plugin's description, followed by what the host adds and what the terminal does instead. */
+export function describePlugin(plugin) {
+    const description = plugin.description || 'No description.';
+    return plugin.surfaces ? `${description} ${plugin.surfaces.note}` : description;
+}

package/dist/sdk/plugins/trust.d.ts

@@ -0,0 +1,44 @@
+import type { Bus } from "../core/bus.js";
+import type { Found } from "./discover.js";
+export interface ProjectCode {
+    /** SHA-256 over every file's name and contents. */
+    hash: string;
+    /** The files, named from the working folder where they are inside it. */
+    files: string[];
+}
+/** The code the working folder brings, or `null` when it brings none. */
+export declare function projectCode(found: readonly Found[], cwd: string): ProjectCode | null;
+/**
+ * Each package a person installed that brings code, by its folder: the whole package is hashed,
+ * so a changed skill or manifest asks again as well. A working folder's packages are part of
+ * `projectCode`.
+ */
+export declare function packageCode(found: readonly Found[]): Map<string, ProjectCode>;
+export interface TrustRecord {
+    hash: string;
+    /** The working folder it was trusted in. */
+    folder: string;
+    files: string[];
+    trustedAt: string;
+}
+export declare class Trust {
+    private readonly bus;
+    private readonly path;
+    constructor(stateDir: string, bus: Bus);
+    private read;
+    list(): TrustRecord[];
+    /** Whether the packages that loaded before trust was asked per package were taken over as trusted. */
+    get adopted(): boolean;
+    /**
+     * Trusts the packages present the first time this runs, so nothing that loaded before stops.
+     * It happens once; a package installed later, or one of these after a change, waits for a person.
+     */
+    adopt(codes: readonly {
+        code: ProjectCode;
+        folder: string;
+    }[]): void;
+    has(hash: string): boolean;
+    private save;
+    grant(code: ProjectCode, folder: string): void;
+    revoke(hash: string): void;
+}

package/dist/sdk/plugins/trust.js

@@ -0,0 +1,120 @@
+// Code a person did not write into the shared folder by hand loads only after they trusted it:
+// a working folder's own (its `.pi/extensions`, or a package its settings name), and every
+// installed package. Trust belongs to the code, not the folder: it is a hash of the files, so a
+// copy of the same code elsewhere is trusted too and a changed file asks again.
+import { createHash } from 'node:crypto';
+import { chmodSync, lstatSync, readdirSync, readFileSync } from 'node:fs';
+import { basename, dirname, join, relative, sep } from 'node:path';
+import { now, readJsonOr, writeJson } from "../core/fs.js";
+import { compareText } from "../core/text.js";
+// Dependencies and version control are left out: the hash says whether the code a person
+// read has changed, and is not a seal on everything that code can import.
+const SKIPPED = new Set(['node_modules', '.git']);
+const MAX_FILES = 5000;
+function walk(path, into) {
+    if (into.length >= MAX_FILES)
+        return;
+    let meta;
+    try {
+        meta = lstatSync(path);
+    }
+    catch {
+        return;
+    }
+    if (meta.isSymbolicLink())
+        return;
+    if (meta.isFile()) {
+        into.push(path);
+        return;
+    }
+    if (!meta.isDirectory())
+        return;
+    for (const name of readdirSync(path).sort(compareText))
+        if (!SKIPPED.has(name))
+            walk(join(path, name), into);
+}
+/** The folder or file that holds one extension: its package, its own folder, or the file. */
+const unit = (item) => item.packageRoot ?? (basename(item.path).startsWith('index.') ? dirname(item.path) : item.path);
+/** A hash over the files of some folders and files, each named from `base` where it is inside it. */
+function hashOf(units, base) {
+    const paths = [];
+    for (const path of [...units].sort(compareText))
+        walk(path, paths);
+    const name = (path) => {
+        const within = relative(base, path);
+        return within && !within.startsWith('..') ? within.split(sep).join('/') : path;
+    };
+    const hash = createHash('sha256');
+    const files = [];
+    for (const path of [...new Set(paths)].sort(compareText)) {
+        let contents;
+        try {
+            contents = readFileSync(path);
+        }
+        catch {
+            continue;
+        }
+        files.push(name(path));
+        hash.update(`${name(path)}\0${contents.length}\0`).update(contents);
+    }
+    return { hash: hash.digest('hex'), files };
+}
+/** The code the working folder brings, or `null` when it brings none. */
+export function projectCode(found, cwd) {
+    const units = [...new Set(found.filter((item) => item.project && item.kind === 'extension' && item.enabled).map(unit))];
+    return units.length ? hashOf(units, cwd) : null;
+}
+/**
+ * Each package a person installed that brings code, by its folder: the whole package is hashed,
+ * so a changed skill or manifest asks again as well. A working folder's packages are part of
+ * `projectCode`.
+ */
+export function packageCode(found) {
+    const roots = [...new Set(found.filter((item) => !item.project && (item.kind === 'extension' || item.kind === 'hook') && item.packageRoot).map((item) => item.packageRoot))];
+    return new Map(roots.map((root) => [root, hashOf([root], root)]));
+}
+export class Trust {
+    bus;
+    path;
+    constructor(stateDir, bus) {
+        this.bus = bus;
+        this.path = join(stateDir, 'plugin-trust.json');
+    }
+    read() {
+        return readJsonOr(this.path, {});
+    }
+    list() {
+        const stored = this.read();
+        return Array.isArray(stored.trusted) ? stored.trusted.filter((record) => typeof record?.hash === 'string') : [];
+    }
+    /** Whether the packages that loaded before trust was asked per package were taken over as trusted. */
+    get adopted() {
+        return this.read().adopted === true;
+    }
+    /**
+     * Trusts the packages present the first time this runs, so nothing that loaded before stops.
+     * It happens once; a package installed later, or one of these after a change, waits for a person.
+     */
+    adopt(codes) {
+        const records = this.list();
+        for (const { code, folder } of codes)
+            if (!records.some((record) => record.hash === code.hash))
+                records.push({ hash: code.hash, folder, files: code.files, trustedAt: now() });
+        writeJson(this.path, { trusted: records, adopted: true });
+        chmodSync(this.path, 0o600);
+    }
+    has(hash) {
+        return this.list().some((record) => record.hash === hash);
+    }
+    save(records) {
+        writeJson(this.path, { trusted: records, ...(this.adopted ? { adopted: true } : {}) });
+        chmodSync(this.path, 0o600);
+        this.bus.emit({ type: 'plugins.changed' });
+    }
+    grant(code, folder) {
+        this.save([...this.list().filter((record) => record.hash !== code.hash), { hash: code.hash, folder, files: code.files, trustedAt: now() }]);
+    }
+    revoke(hash) {
+        this.save(this.list().filter((record) => record.hash !== hash));
+    }
+}

package/dist/sdk/plugins/types.d.ts

@@ -0,0 +1,174 @@
+import type { Attachment } from "./attachments.js";
+import type { Registered } from "./plugins.js";
+import type { ProjectCode } from "./trust.js";
+export declare const CONTRIBUTION_KINDS: readonly ["instruction", "skill", "command", "agent", "tool", "connection", "code", "theme"];
+export type ContributionKind = (typeof CONTRIBUTION_KINDS)[number];
+/**
+ * Where a plugin comes from: the harness itself, the embedding application, Pi, a person's own
+ * registry, the folder every account shares, an installed package, the working folder, or the
+ * home folder.
+ */
+export declare const PLUGIN_SOURCES: readonly ["builtin", "application", "pi", "yours", "shared", "package", "project", "home"];
+export type PluginSource = (typeof PLUGIN_SOURCES)[number];
+/** `untrusted` is code that is found and does not load until a person trusts it. */
+export type ContributionState = 'on' | 'off' | 'untrusted';
+export interface Contribution {
+    /** `<plugin id>/<kind>/<name>`. */
+    id: string;
+    kind: ContributionKind;
+    name: string;
+    description: string;
+    path: string | null;
+    state: ContributionState;
+    /** Who it is switched on for, in words: "Everywhere", a project's name, "2 agents". */
+    scope: string | null;
+    /** Where it is switched on and off, or `null` when it cannot be switched on its own. */
+    attachment: Attachment | null;
+    /** What a code contribution registered the last time a session loaded it. */
+    registered: Registered | null;
+    /** What went wrong the last time it ran, for code the harness runs itself. */
+    problem: string | null;
+    /** Code the harness runs itself after a change, for everyone, outside any session. */
+    background: boolean;
+}
+/** Where a person changes a plugin today. */
+export type PluginManage = 'registry' | 'tools' | 'connections' | 'files';
+export interface Plugin {
+    id: string;
+    title: string;
+    description: string;
+    version: string | null;
+    source: PluginSource;
+    path: string | null;
+    runsCode: boolean;
+    trust: 'none' | 'trusted' | 'untrusted';
+    /** The code a person is asked to trust, for a working folder's own. */
+    code: ProjectCode | null;
+    /**
+     * How a person installed it, when it can be removed here: named in the settings every account
+     * shares (`source` is the name there), or a folder kept with their data (`source` is its path).
+     */
+    install: {
+        kind: 'settings' | 'folder';
+        source: string;
+    } | null;
+    /** The parts it adds to, by plugin id: a package that says it extends Memory, the Wiki or History. */
+    extends: string[];
+    /** Why it cannot be removed, or `null` when it can. */
+    required: string | null;
+    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;
+    /** Where it works best, for a plugin that works better in a host. */
+    surfaces?: PluginSurfaces | null;
+    contributions: Contribution[];
+}
+/** A number a person can set on a plugin, such as a limit. */
+export interface PluginSetting {
+    key: string;
+    label: string;
+    description: string;
+    default: number;
+    min: number;
+    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;
+    title: string;
+    description: string;
+    /** Why it cannot be removed. */
+    required?: string;
+    manage?: PluginManage;
+    tools?: {
+        name: string;
+        description?: string;
+    }[];
+    /** The prompt sections it writes. */
+    sections?: {
+        id: string;
+        name: string;
+        description?: string;
+    }[];
+    /** The tool groups whose paragraph in the tools section it writes. */
+    toolGroups?: string[];
+    /** It ships with the harness and a person may switch it. `on` is its state until they do. */
+    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;
+    }[];
+    /** Where it works best, when that is not everywhere alike (PROP-0039). Never a category. */
+    surfaces?: PluginSurfaces;
+}
+/**
+ * A plugin that works better in a host such as a desktop application: an add-on there. The
+ * capability is the same in both; the host adds presentation or a native backend the terminal
+ * cannot have. `terminal` says what the terminal offers instead (INV-PAR-3).
+ */
+export interface PluginSurfaces {
+    preferred: 'host';
+    terminal: 'fallback' | 'unavailable';
+    /** One sentence for a person: what the host adds, and what the terminal does instead. */
+    note: string;
+}
+export type Delivery = 'system' | 'context' | 'tool' | 'on-demand' | 'code' | 'background';
+/** One thing that reaches a caller. */
+export interface InventoryItem {
+    pluginId: string;
+    contributionId: string | null;
+    kind: ContributionKind;
+    name: string;
+    /** `system` is the stable prefix, `context` an update sent with a request, `on-demand` text a tool loads, `background` code the harness runs after a change. */
+    delivery: Delivery;
+    /** Characters it adds to what the model is told, when that is known. */
+    chars: number | null;
+    /** Its text was cut to fit a budget. */
+    cut: boolean;
+}
+export interface Inventory {
+    /** The plugins the items belong to. */
+    plugins: Plugin[];
+    /** Every other plugin, with nothing reaching this caller: what could still be switched on for it. */
+    others: Plugin[];
+    items: InventoryItem[];
+    /** Prompt sections, tool groups and tools that no plugin accounts for. */
+    unattributed: {
+        kind: 'section' | 'toolGroup' | 'tool';
+        id: string;
+    }[];
+    systemChars: number;
+    contextChars: number;
+}

package/dist/sdk/plugins/types.js

@@ -0,0 +1,7 @@
+export const CONTRIBUTION_KINDS = ['instruction', 'skill', 'command', 'agent', 'tool', 'connection', 'code', 'theme'];
+/**
+ * Where a plugin comes from: the harness itself, the embedding application, Pi, a person's own
+ * registry, the folder every account shares, an installed package, the working folder, or the
+ * home folder.
+ */
+export const PLUGIN_SOURCES = ['builtin', 'application', 'pi', 'yours', 'shared', 'package', 'project', 'home'];

package/dist/sdk/prompt/compile.d.ts

@@ -0,0 +1,245 @@
+import { type CallerContext } from "../core/caller.js";
+import type { HarnessEnv } from "../core/env.js";
+import type { Materialised } from "../variant/materialise.js";
+import { type SkillFile } from "../tools/defaultSkills.js";
+import type { TodoItem } from "../sessions/contracts.js";
+import type { SessionState } from "../sessions/sessionState.js";
+import { type StandardSession } from "./standard.js";
+import { REPORTING_GUIDANCE } from "./reporting.js";
+export declare const REQUIRED_SKILLS_BUDGET = 12000;
+export declare const REFERENCES_BUDGET = 12000;
+/** An approval is a control the person clicks; the model never asks for permission in a message. */
+export declare const APPROVAL_GUIDANCE = "Approvals: when a call needs a person, the Harness pauses that exact call and shows them Allow and Deny. Never ask for permission in a message, never end your turn to wait for an answer, and never call a task blocked on approval before trying: a denial arrives as the tool result, and you continue from it.";
+/** Where the harness's own sections sit; an application's sections are placed among them by `order`. */
+export declare const SECTION_ORDER: {
+    readonly harnessIdentity: 5;
+    readonly system: 25;
+    readonly sessionState: 30;
+    readonly guardrails: 40;
+    readonly memory: 45;
+    readonly references: 50;
+    readonly requiredSkills: 52;
+    readonly subagents: 64;
+    readonly scripts: 66;
+    readonly wiki: 80;
+    readonly tools: 90;
+    readonly reporting: 95;
+};
+/** Where a section's text came from. */
+export interface Source {
+    id: string;
+    kind: string;
+    revision?: string | null;
+    /** Characters this source contributed inside its section, when the compiler measured them. */
+    chars?: number;
+}
+export interface Section {
+    /** `harness-identity`, `identity`, `role`, `system`, `session-state`, `guardrails`, `memory`, `references`, `required-skills`, `subagents`, `scripts`, `wiki`, `tools`, or an application's own. */
+    id: string;
+    title: string;
+    body: string;
+    sources: Source[];
+    budget: number;
+    /** Characters in `body`. */
+    size: number;
+    cut: boolean;
+}
+/** One group of the tool manifest. */
+export interface ToolGroup {
+    group: string;
+    tools: string[];
+}
+export interface ContextPack {
+    runId: string | null;
+    /** Who the pack is for, in the application's own words; `agent` or `session` when it gives none. */
+    profile: string;
+    sections: Section[];
+    /** The tools the pack describes, by group. */
+    toolGroups: ToolGroup[];
+    /** The variant the session ran, when it ran one. */
+    variant?: {
+        scope: string | null;
+        fingerprint: string;
+    } | null;
+    compiledAt: string;
+    delivery?: Delivery;
+}
+export interface Delivery {
+    systemSectionIds: string[];
+    updatedSectionIds: string[];
+    /**
+     * What each delivered section occupied, measured when it was rendered. Absent on packs recorded
+     * before the compiler measured them; a reader then falls back to the section's own size.
+     */
+    sizes?: {
+        system: Record<string, number>;
+        update: Record<string, number>;
+        /** Characters that belong to no section: the product heading and the context-update trailer. */
+        systemFraming: number;
+        /** Characters of the update message that are not a section, including a withdrawn one. */
+        updateFraming: number;
+    };
+}
+/** A section the embedding application writes. */
+export interface HostSection {
+    id: string;
+    title: string;
+    /** `null` declares the slot without filling it, so a withdrawn dynamic section is announced. */
+    body: string | null;
+    budget: number;
+    /** Appended when the body is cut. */
+    pointer?: string;
+    /** Position among the sections; the harness's own are in `SECTION_ORDER`. */
+    order: number;
+    /** Changing state: delivered as a context update, never in the system prompt. */
+    dynamic?: boolean;
+    /** Text placed before the body. */
+    pinned?: {
+        text: string;
+        pointer?: string;
+    } | null;
+}
+/** A group of tools the application provides, with the paragraph that explains it. */
+export interface HostToolGroup {
+    group: string;
+    tools: string[];
+    guidance: string;
+    order: number;
+}
+/** One selected reference: a Wiki note, or a line the application writes about something it selected. */
+export type Reference = {
+    kind: 'note';
+    path: string;
+    label?: string;
+} | {
+    kind: 'line';
+    id: string;
+    label: string;
+    text: string;
+};
+/** A skill the person named in the message: required for this request only. */
+export interface RequiredSkill {
+    name: string;
+    label?: string;
+}
+/** One skill's text as the required-skills section and the terminal deliver it. */
+export interface RequiredSkillText extends RequiredSkill, Partial<Omit<SkillFile, 'name'>> {
+    body: string;
+}
+/** What the compiler needs beyond the caller. */
+export interface Launch {
+    /** The paragraph about connected apps, when the session has that broker. */
+    connections?: string | null;
+    /** The tools the Connections group lists. */
+    connectionTools?: string[];
+    /** The tools switched on for the caller. The pack only describes tools the caller can call. */
+    tools?: string[] | null;
+    /** The current session name and this run's todo, delivered as a request-scoped update. */
+    sessionState?: SessionState;
+    references?: Reference[];
+    /** Skills the message named as required for this request. Delivered as a request-scoped update. */
+    requiredSkills?: RequiredSkill[];
+    sections?: HostSection[];
+    toolGroups?: HostToolGroup[];
+    /** Appended to the tools section when it is cut. */
+    toolsPointer?: string;
+    /** Suppresses tool guidance for a run that deliberately has no callable tools. */
+    hideToolGuidance?: boolean;
+    /**
+     * A person's own interactive session: adds the standard role, working folder and connections
+     * paragraph (prompt/standard.ts), so the terminal and every host word them alike.
+     */
+    standard?: StandardSession | null;
+    /** Recorded with the pack: the application's name for who it is for. Defaults to `agent` or `session`. */
+    profile?: string;
+    /** The model the session runs, named in the identity line when the host knows it. */
+    model?: string | null;
+}
+/** How a run's final reply is shaped. Fixed text: it sits in the stable prefix of every pack. */
+export { REPORTING_GUIDANCE };
+export declare const HISTORY_GROUP: string[];
+export declare const WIKI_GROUP: string[];
+export declare const NATIVE_GROUP: string[];
+export declare const CONNECTION_TOOLS: string[];
+export declare const ANNOTATION_TOOLS: string[];
+/** Cuts `text` to `budget` characters at a paragraph (or line) boundary and appends `pointer`. */
+export declare function fit(text: string, budget: number, pointer: string): {
+    body: string;
+    cut: boolean;
+};
+/** At most `limit` characters, with an ellipsis when it was cut. */
+export declare function clip(text: string, limit: number): string;
+/** A bounded, request-scoped checkpoint reintroduced after context compaction. */
+export declare function renderCompactionCheckpoint(input: {
+    goal: string;
+    todo: readonly TodoItem[];
+    planInstructions?: string | null;
+}): string | null;
+export interface OrderedGroup extends ToolGroup {
+    order: number;
+    guidance: string | null;
+}
+/**
+ * The caller's tools by group, in a fixed order. History and the Wiki are always there; the rest
+ * follows the switches in `launch.tools` and what the application provides.
+ */
+export declare function toolGroups(context: CallerContext, launch: Launch, dataRoot?: string): OrderedGroup[];
+/** The request-scoped text for skills the person named; the compiler and the terminal word it alike. */
+export declare function requiredSkillsText(skills: readonly RequiredSkillText[]): string | null;
+/** The request-scoped state line: the name, this run's todo, and the previous list as context. */
+export declare function sessionStateText(state: SessionState, options: {
+    name: boolean;
+    todo: boolean;
+}): string | null;
+/** Compiles the pack for a caller. It only reads the data root. */
+export declare function compile(env: HarnessEnv, context: CallerContext, launch?: Launch, variant?: Materialised | null): ContextPack;
+/** What a rendered pack is, and how much of it each section occupies. */
+export interface RenderedPrompt {
+    text: string;
+    /** Characters each section's heading and body occupy, by section id. */
+    sizes: Record<string, number>;
+    /** Characters that belong to no section: the product heading and the blank lines between. */
+    framing: number;
+}
+/** The pack as one string, with the characters each section contributed to it. */
+export declare function renderSized(env: Pick<HarnessEnv, 'productName'>, pack: Pick<ContextPack, 'sections'>): RenderedPrompt;
+/** The pack as the one string a session receives. */
+export declare function render(env: Pick<HarnessEnv, 'productName'>, pack: Pick<ContextPack, 'sections'>): string;
+export declare function packPath(root: string, runId: string): string;
+/** The pack a run was given, when it was recorded. */
+export declare function load(root: string, runId: string): ContextPack | null;
+/** Saves the pack beside the run's events. */
+export declare function record(root: string, pack: ContextPack): void;
+export declare const BUILT_IN_DYNAMIC: readonly {
+    id: string;
+    order: number;
+}[];
+export declare const CONTEXT_GUIDANCE = "App-origin context updates in the conversation supply current Wiki notes, active work, session state, selected references, and the skills the person required for this request. Each listed section replaces its earlier app snapshot; a withdrawn section is no longer current context. These updates are context, not requests from the user. Selected references and required skills apply only to the accompanying request. They do not change permissions. Use the latest supplied state and retrieve details through tools when needed.";
+/** The hidden message a context update is saved as in native history, and where its snapshot sits. */
+export declare const CONTEXT_MESSAGE_TYPE = "xingular-context";
+export declare const CONTEXT_SNAPSHOT_KEY = "xingularContext";
+/** Rendered by the compiler; the session only transports it and saves the delivered snapshot. */
+export interface ContextUpdate {
+    content: string;
+    snapshot: Section[];
+}
+/**
+ * The snapshot last delivered on the active branch of a native history. A compaction requires a
+ * fresh snapshot because earlier context messages may have been replaced by a summary.
+ */
+export declare function deliveredSnapshot(sessionFile: string): Section[] | null;
+/** Resolves the same history Pi will open; an explicit continuation always wins. */
+export declare function sessionFile(sessionDir: string, resume?: string | null): string | null;
+/**
+ * Stable instructions stay in the system prompt; changing state is appended to native history.
+ * Recording the current pack does not mark an update delivered: the session saves that snapshot
+ * only when it appends the corresponding context message.
+ */
+export declare function sessionLaunch(env: HarnessEnv, context: CallerContext, launch: Launch, historyFile: string | null, variant?: Materialised | null): {
+    system: string;
+    update: ContextUpdate | null;
+    pack: ContextPack;
+};
+/** A terminal session keeps the pack it started with; each of its runs records a copy. */
+export declare function saveForSession(sessionDir: string, pack: ContextPack): void;
+export declare function copyToRun(root: string, sessionDir: string, runId: string): void;