@xingular/harness 0.1.7 → 1.1.1

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

@@ -0,0 +1,159 @@
+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", "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;
+    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;
+    }[];
+}
+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', '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,177 @@
+import { type CallerContext } from "../core/caller.js";
+import type { HarnessEnv } from "../core/env.js";
+import type { Materialised } from "../variant/materialise.js";
+export declare const REFERENCES_BUDGET = 12000;
+/** 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 guardrails: 40;
+    readonly memory: 45;
+    readonly references: 50;
+    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;
+}
+export interface Section {
+    /** `harness-identity`, `identity`, `role`, `system`, `guardrails`, `memory`, `references`, `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[];
+}
+/** 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;
+};
+/** 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;
+    references?: Reference[];
+    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;
+    /** Recorded with the pack: the application's name for who it is for. Defaults to `agent` or `session`. */
+    profile?: string;
+}
+/** How a run's final reply is shaped. Fixed text: it sits in the stable prefix of every pack. */
+export declare const REPORTING_GUIDANCE = "When you finish work, write the final reply for a person who did not watch you work.\n\n- Start with the answer or outcome in one or two sentences. If they asked a question, answer it first.\n- Keep it concise and use only headings or structure that help explain the outcome; do not force a fixed set of report headings.\n- When work involves files, identify the relevant paths and briefly state what changed or mattered. Use `path:line` references where useful, and a table (File | Change | Why) when there are three or more changed files.\n- Include blockers, risks, or next steps only when they are concrete and relevant.\n- Use **Need human inspection** only when a concrete verification requires a person because you could not perform or observe it. State what remains unverified, why you could not verify it, and the specific check the person should make. Do not use this for checks you ran or generic risks.\n- Name only checks actually run and their results; never claim a check you did not run.\n- Use a Markdown table when comparing options, listing several items with the same fields, or reporting the results of several checks. Use prose or bullets otherwise.\n- A one-line question gets a one-line answer.\n- If the person, the application, or the current mode asks for a different format, follow that.\n";
+export declare const HISTORY_GROUP: string[];
+export declare const WIKI_GROUP: string[];
+export declare const NATIVE_GROUP: string[];
+export declare const CONNECTION_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;
+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[];
+/** 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;
+/** 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, and selected references. 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 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;