nexus-ai-pro 2.4.0 → 2.6.0

package/dist/agent/create-agent.js

@@ -8,6 +8,7 @@ const agentChannels = () => ({
     iterations: counter(),
     answer: lastValue(''),
     stopReason: lastValue(undefined),
+    clientTools: lastValue(undefined),
 });
 export function agentInput(goal) {
     return { messages: [{ role: 'user', content: goal }] };
@@ -20,16 +21,33 @@ export function createAgent(options) {
     const executor = new ToolExecutor(options.tools ?? []);
     const middleware = options.middleware ?? [];
     const approvals = options.interruptOn ?? {};
+    const toolsFor = async (context) => {
+        if (!options.toolSource)
+            return executor;
+        const supplied = await options.toolSource({
+            threadId: context.threadId,
+            ...(context.tenantId !== undefined ? { tenantId: context.tenantId } : {}),
+            ...(context.principal ? { principal: context.principal } : {}),
+            signal: context.signal,
+        });
+        return supplied.length ? new ToolExecutor([...supplied, ...executor.list()]) : executor;
+    };
     const graph = createGraph({ channels: agentChannels() })
         .addNode('model', async (context) => {
         const state = context.state;
+        const runTools = await toolsFor(context);
+        const clientTools = clientToolsOf(state, runTools);
+        if (clientTools.length > 0 && waitingOnClient(state.messages, clientTools)) {
+            return new Command({ update: { stopReason: 'client_tools' }, goto: END });
+        }
+        const offered = [...runTools.list(), ...clientTools];
         let request = {
             model: options.model ?? 'auto',
             messages: [
                 ...(options.systemPrompt ? [{ role: 'system', content: options.systemPrompt }] : []),
                 ...state.messages,
             ],
-            ...(options.tools?.length ? { tools: executor.list() } : {}),
+            ...(offered.length ? { tools: offered } : {}),
             ...(options.temperature === undefined ? {} : { temperature: options.temperature }),
             ...(options.maxTokens === undefined ? {} : { maxTokens: options.maxTokens }),
             ...(options.responseFormat ? { responseFormat: options.responseFormat } : {}),
@@ -88,9 +106,28 @@ export function createAgent(options) {
                 goto: END,
             });
         }
+        const forClient = new Set(clientTools.map((item) => item.name));
+        const ours = calls.filter((call) => !forClient.has(call.function.name));
+        for (const call of calls) {
+            if (!forClient.has(call.function.name))
+                continue;
+            const parsed = parseArguments(call.function.arguments);
+            context.tool({
+                phase: 'start',
+                id: call.id,
+                name: call.function.name,
+                args: parsed.ok ? parsed.args : call.function.arguments,
+            });
+        }
+        if (ours.length === 0) {
+            return new Command({
+                update: { messages: [assistant], iterations: 1, stopReason: 'client_tools' },
+                goto: END,
+            });
+        }
         return new Command({
             update: { messages: [assistant], iterations: 1 },
-            goto: calls.map((call) => new Send('tools', call)),
+            goto: ours.map((call) => new Send('tools', call)),
         });
     }, { ends: ['tools', END] })
         .addNode('tools', async (context) => {
@@ -100,7 +137,8 @@ export function createAgent(options) {
             return { messages: [toolMessage(call, { ok: false, error: parsed.error })] };
         }
         let args = parsed.args;
-        const definition = executor.get(call.function.name);
+        const runTools = await toolsFor(context);
+        const definition = runTools.get(call.function.name);
         const capabilities = capabilitiesOf(definition, args);
         const description = {
             id: call.id,
@@ -159,13 +197,14 @@ export function createAgent(options) {
                 if (recheck.decision === 'deny')
                     return { ok: false, error: `Permission denied: ${recheck.reason}` };
             }
-            return executor.execute(description.name, current.args, {
+            return runTools.execute(description.name, current.args, {
                 toolCallId: call.id,
                 threadId: context.threadId,
                 ...(context.tenantId !== undefined ? { tenantId: context.tenantId } : {}),
                 ...(context.principal ? { principal: context.principal } : {}),
                 signal: context.signal,
                 ...(context.store ? { store: context.store } : {}),
+                progress: (progress) => context.tool({ phase: 'progress', id: call.id, name: description.name, progress }),
             });
         };
         context.tool({ phase: 'start', id: call.id, name: description.name, args });
@@ -250,6 +289,25 @@ function parseArguments(raw) {
         return { ok: false, error: `Tool arguments are not valid JSON (${reason}); the tool was not run` };
     }
 }
+function clientToolsOf(state, runTools) {
+    return (state.clientTools ?? []).filter((item) => typeof item?.name === 'string' && item.name !== '' && !runTools.has(item.name));
+}
+function waitingOnClient(messages, clientTools) {
+    const names = new Set(clientTools.map((item) => item.name));
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        const message = messages[index];
+        if (message.role === 'user')
+            return false;
+        if (message.role !== 'assistant' || !message.toolCalls?.length)
+            continue;
+        const answered = new Set(messages
+            .slice(index + 1)
+            .filter((item) => item.role === 'tool')
+            .map((item) => item.toolCallId));
+        return message.toolCalls.some((call) => names.has(call.function.name) && !answered.has(call.id));
+    }
+    return false;
+}
 function hookContext(context, state, store) {
     return {
         state,

package/dist/agent/index.d.ts

@@ -1,6 +1,7 @@
 export { AgentLoop, type AgentModelClient as AgentLoopModelClient } from './loop.js';
 export { isToolOutput, tool, ToolExecutor, toolMessageContent, toolOutput } from './tool.js';
+export type { ToolBody } from './tool.js';
 export { limitToolCalls, redactMessages, type RedactOptions, summarizeHistory, type SummarizeOptions, } from './middleware/basic.js';
-export { agentAsTool, agentInput, type AgentApproval, type AgentApprovalPolicy, type AgentChannels, type AgentGraph, type AgentMiddleware, type AgentMiddlewareContext, type AgentModelCallContext, type AgentModelClient, type AgentState, type AgentStopReason, type AgentToolCall, type AgentToolResult, createAgent, type CreateAgentOptions, } from './create-agent.js';
+export { agentAsTool, agentInput, type AgentApproval, type AgentApprovalPolicy, type AgentChannels, type AgentGraph, type AgentMiddleware, type AgentMiddlewareContext, type AgentModelCallContext, type AgentModelClient, type AgentState, type AgentStopReason, type AgentToolCall, type AgentToolResult, type ClientToolDefinition, createAgent, type CreateAgentOptions, type ToolSourceContext, } from './create-agent.js';
 export type { AgentConfig, AgentResult, AgentStep, ToolExecutionResult } from '../types/agent.js';
 export type { ToolContext } from '../types/messages.js';

package/dist/agent/tool.d.ts

@@ -1,15 +1,30 @@
 import type { ContentPart, Message, ToolContext, ToolDefinition, ToolOutput } from '../types/messages.js';
 import type { ToolExecutionResult } from '../types/agent.js';
-/** Defines a tool the model can call, typing its arguments. */
+/** How a tool built with `tool()` runs: once, with `execute`, or reporting progress, with `stream`. */
+export type ToolBody<TArgs> = {
+    /** Runs the tool. In an agent, `context` says who the run is for and carries its signal and store. */
+    execute: (args: TArgs, context: ToolContext) => Promise<unknown> | unknown;
+    stream?: never;
+} | {
+    /**
+     * Runs the tool, yielding progress while it works and returning the result. See
+     * `ToolDefinition.stream`.
+     */
+    stream: (args: TArgs, context: ToolContext) => AsyncGenerator<unknown, unknown, undefined>;
+    execute?: never;
+};
+/**
+ * Defines a tool the model can call, typing its arguments. A tool given `stream` gets an `execute`
+ * too, which runs the stream and reports each yield to `context.progress`, so it works wherever a
+ * tool is executed.
+ */
 export declare function tool<TArgs extends Record<string, unknown> = Record<string, unknown>>(definition: {
     name: string;
     description: string;
     parameters: Record<string, unknown>;
-    /** Runs the tool. In an agent, `context` says who the run is for and carries its signal and store. */
-    execute: (args: TArgs, context: ToolContext) => Promise<unknown> | unknown;
     /** What the tool does to the world, for a permission policy; see `ToolDefinition.capabilities`. */
     capabilities?: readonly string[] | ((args: TArgs) => readonly string[]);
-}): ToolDefinition;
+} & ToolBody<TArgs>): ToolDefinition;
 /**
  * Builds a tool's result as content: text, images, and asset references, in order. A string becomes
  * a text part. Returned from `execute`, it is sent as the tool message itself, so an image a tool

package/dist/agent/tool.js

@@ -1,10 +1,19 @@
 export function tool(definition) {
     const capabilities = definition.capabilities;
+    const stream = definition.stream;
+    const execute = definition.execute;
     return {
         name: definition.name,
         description: definition.description,
         parameters: definition.parameters,
-        execute: async (args, context) => definition.execute(args, context ?? {}),
+        ...(stream
+            ? {
+                stream: (args, context) => stream(args, context ?? {}),
+                execute: async (args, context) => drain(stream(args, context ?? {}), context?.progress),
+            }
+            : {
+                execute: async (args, context) => execute(args, context ?? {}),
+            }),
         ...(capabilities === undefined
             ? {}
             : {
@@ -31,6 +40,18 @@ export function toolMessageContent(result) {
         return result.result.content;
     return JSON.stringify(result.ok ? (result.result ?? null) : { error: result.error });
 }
+async function drain(generator, progress) {
+    for (;;) {
+        const step = await generator.next();
+        if (step.done)
+            return step.value;
+        try {
+            progress?.(step.value);
+        }
+        catch {
+        }
+    }
+}
 export class ToolExecutor {
     tools = new Map();
     constructor(tools = []) {
@@ -56,11 +77,13 @@ export class ToolExecutor {
         if (!toolDefinition) {
             return { ok: false, error: `Tool "${name}" is not registered` };
         }
-        if (!toolDefinition.execute) {
-            return { ok: false, error: `Tool "${name}" does not have an execute function` };
+        if (!toolDefinition.execute && !toolDefinition.stream) {
+            return { ok: false, error: `Tool "${name}" does not have an execute or stream function` };
         }
         try {
-            const result = await toolDefinition.execute(args, context);
+            const result = toolDefinition.stream
+                ? await drain(toolDefinition.stream(args, context), context?.progress)
+                : await toolDefinition.execute(args, context);
             return { ok: true, result };
         }
         catch (err) {

package/dist/context-hub/hub.d.ts

@@ -2,6 +2,7 @@ import type { GateResult } from '../prompts/errors.js';
 import type { PromptRegistry } from '../prompts/registry.js';
 import type { PromptHistoryEntry, PromptLabel, PromptStore, PromptVersion, RenderedPrompt, RenderOptions } from '../types/prompts.js';
 import { type ContextDiff } from './diff.js';
+import { type ContextKeyring, type ContextSignature, type ContextSigner } from './signing.js';
 /** A prompt a bundle uses, pinned to one content version of the prompt registry. */
 export interface ContextPromptPin {
     /** The prompt's name in the registry. */
@@ -61,6 +62,8 @@ export interface ContextBundle extends ContextBundleDefinition {
     author?: string;
     /** The version that was newest before it. */
     parent?: string;
+    /** Signatures over its content and its pinned prompts' content. Not part of the version. */
+    signatures?: ContextSignature[];
 }
 /** Which bundle version is being used, as experiments and traces record it. */
 export interface ContextReference {
@@ -125,9 +128,33 @@ export interface ContextHubOptions {
     gates?: Record<string, readonly ContextPromotionGate[]>;
     /** Called after every recorded change. */
     onChange?: (entry: ContextHistoryEntry) => void | Promise<void>;
+    /**
+     * Signs every new version, over its content and its pinned prompts' content, so another hub can
+     * check where it came from. Signing a bundle that pins prompts needs `prompts`.
+     */
+    signer?: ContextSigner;
+    /**
+     * The keys whose signatures this hub trusts, for `verify()`, and for `requireSignature`. A signature
+     * by a key the keyring does not hold is kept, but never trusted.
+     */
+    keyring?: ContextKeyring;
+    /**
+     * Refuses any bundle without a valid signature by a key in `keyring`: on import, and whenever a
+     * version is served through `resolve()` or `renderPrompt()`.
+     */
+    requireSignature?: boolean;
     /** Replaces the system clock, for tests. */
     now?: () => Date;
 }
+/** What `ContextHub.verify()` found. */
+export interface ContextVerification {
+    /** Whether a key in the keyring signed exactly this content. */
+    trusted: boolean;
+    /** The digest the content has now. */
+    digest: string;
+    /** The signature that verified, when one did. */
+    signature?: ContextSignature;
+}
 /** Base class for context hub errors, each with a stable `code`. */
 export declare class ContextHubError extends Error {
     /** Stable code, such as `CONTEXT_NOT_FOUND`. */
@@ -160,6 +187,18 @@ export declare class ContextPromotionError extends ContextHubError {
     /** Every gate's verdict. */
     results: GateResult[]);
 }
+/** Raised when a bundle has no signature the hub trusts, or its signatures do not match its content. */
+export declare class ContextSignatureError extends ContextHubError {
+    /** The bundle. */
+    readonly bundle: string;
+    /** The version. */
+    readonly version: string;
+    constructor(
+    /** The bundle. */
+    bundle: string, 
+    /** The version. */
+    version: string, reason: string);
+}
 /** Raised when a bundle definition, a pin, or an import is invalid. */
 export declare class ContextDefinitionError extends ContextHubError {
     constructor(message: string);
@@ -182,6 +221,8 @@ export declare class ContextHub {
     /** Where versions, labels, and history live. */
     readonly store: PromptStore;
     private readonly now;
+    /** Versions already verified as trusted, which never change. */
+    private readonly trusted;
     constructor(options?: ContextHubOptions);
     /**
      * Commits a bundle and returns its version. Unchanged content returns the existing version and
@@ -193,8 +234,15 @@ export declare class ContextHub {
         author?: string;
         label?: string | readonly string[];
     }): Promise<ContextBundle>;
+    private commitSigned;
     /** A version by content version, label, or `latest`, the default. Throws `ContextNotFoundError` when there is none. */
     get(name: string, ref?: string): Promise<ContextBundle>;
+    /**
+     * Whether a key in the hub's keyring signed exactly this bundle's content, and its pinned prompts'
+     * content as the prompt registry holds them. A version's answer never changes, so it is checked
+     * once.
+     */
+    verify(bundle: ContextBundle): Promise<ContextVerification>;
     /** A version with the reference experiments and traces record for it. */
     resolve(name: string, ref?: string): Promise<{
         bundle: ContextBundle;
@@ -262,6 +310,11 @@ export declare class ContextHub {
         label?: string | readonly string[];
         by?: string;
     }): Promise<ContextBundle>;
+    /** Refuses a bundle without a trusted signature, when the hub requires one. */
+    private assertTrusted;
+    private check;
+    /** What a signature over this bundle covers, with its pinned prompts read from the registry. */
+    private signedContent;
     private read;
     private pointer;
     private record;

package/dist/context-hub/hub.js

@@ -1,6 +1,7 @@
 import { MemoryPromptStore } from '../prompts/memory.js';
 import { canonicalJson } from '../prompts/version.js';
 import { diffContexts } from './diff.js';
+import { contextDigest, signDigest, verifiedBy, } from './signing.js';
 export class ContextHubError extends Error {
     code;
     constructor(message, code) {
@@ -36,6 +37,16 @@ export class ContextPromotionError extends ContextHubError {
         this.name = 'ContextPromotionError';
     }
 }
+export class ContextSignatureError extends ContextHubError {
+    bundle;
+    version;
+    constructor(bundle, version, reason) {
+        super(`Context bundle "${bundle}" ${version}: ${reason}`, 'CONTEXT_SIGNATURE');
+        this.bundle = bundle;
+        this.version = version;
+        this.name = 'ContextSignatureError';
+    }
+}
 export class ContextDefinitionError extends ContextHubError {
     constructor(message) {
         super(message, 'CONTEXT_DEFINITION_ERROR');
@@ -63,12 +74,19 @@ export class ContextHub {
     options;
     store;
     now;
+    trusted = new Map();
     constructor(options = {}) {
         this.options = options;
+        if (options.requireSignature && !options.keyring) {
+            throw new TypeError('requireSignature needs a keyring of the keys the hub trusts');
+        }
         this.store = options.store ?? new MemoryPromptStore();
         this.now = options.now ?? (() => new Date());
     }
     async commit(definition, options = {}) {
+        return this.commitSigned(definition, options, []);
+    }
+    async commitSigned(definition, options, inherited) {
         validate(definition);
         if (this.options.prompts) {
             for (const [role, pin] of Object.entries(definition.prompts ?? {})) {
@@ -92,6 +110,13 @@ export class ContextHub {
                 ...(options.author === undefined ? {} : { author: options.author }),
                 ...(newest ? { parent: newest.version } : {}),
             };
+            const signatures = [...inherited];
+            if (this.options.signer) {
+                const digest = await contextDigest(await this.signedContent(definition));
+                signatures.push(await signDigest(this.options.signer, digest, this.now()));
+            }
+            if (signatures.length > 0)
+                stored.signatures = signatures;
             await this.store.saveVersion(toStored(stored));
             await this.record({ name: definition.name, action: 'commit', version: id, by: options.author });
         }
@@ -118,8 +143,19 @@ export class ContextHub {
             throw new ContextNotFoundError(name, ref);
         return found;
     }
+    async verify(bundle) {
+        const key = `${bundle.name}@${bundle.version}`;
+        let pending = this.trusted.get(key);
+        if (!pending) {
+            pending = this.check(bundle, await this.signedContent(bundle));
+            this.trusted.set(key, pending);
+            pending.catch(() => this.trusted.delete(key));
+        }
+        return pending;
+    }
     async resolve(name, ref = 'latest') {
         const bundle = await this.get(name, ref);
+        await this.assertTrusted(bundle);
         return {
             bundle,
             reference: {
@@ -133,6 +169,7 @@ export class ContextHub {
         const registry = this.options.prompts;
         if (!registry)
             throw new ContextDefinitionError('Rendering a pinned prompt needs the hub to have a prompt registry');
+        await this.assertTrusted(bundle);
         const pin = bundle.prompts?.[role];
         if (!pin)
             throw new ContextNotFoundError(bundle.name, `prompt role "${role}"`);
@@ -259,15 +296,52 @@ export class ContextHub {
                 throw new ContextDefinitionError(`Prompt ${prompt.name} was exported as ${version} but its content is ${committed.version}`);
             }
         }
-        const { version, createdAt: _createdAt, parent: _parent, message, author, ...definition } = exported.bundle;
+        const { version, createdAt: _createdAt, parent: _parent, message, author, signatures = [], ...definition } = exported.bundle;
         if ((await contextVersion(definition)) !== version) {
             throw new ContextDefinitionError(`Bundle ${definition.name} was exported as ${version} but its content has changed`);
         }
-        return this.commit(definition, {
+        const digest = await contextDigest(signedContentOf(definition, exportedPrompts(exported)));
+        const claims = signatures.filter((signature) => signature?.digest === digest);
+        if (this.options.requireSignature && this.options.keyring) {
+            const signed = await verifiedBy(this.options.keyring, digest, claims);
+            if (!signed) {
+                throw new ContextSignatureError(definition.name, version, signatures.length > 0
+                    ? 'no signature verifies against its content with a trusted key'
+                    : 'it is not signed, and this hub requires a signature');
+            }
+        }
+        return this.commitSigned(definition, {
             message: message ?? 'imported',
             ...((options.by ?? author) === undefined ? {} : { author: options.by ?? author }),
             ...(options.label === undefined ? {} : { label: options.label }),
-        });
+        }, claims);
+    }
+    async assertTrusted(bundle) {
+        if (!this.options.requireSignature)
+            return;
+        const verification = await this.verify(bundle);
+        if (!verification.trusted) {
+            throw new ContextSignatureError(bundle.name, bundle.version, bundle.signatures?.length
+                ? 'no signature verifies against its content with a trusted key'
+                : 'it is not signed, and this hub requires a signature');
+        }
+    }
+    async check(bundle, content) {
+        const digest = await contextDigest(content);
+        const signature = this.options.keyring
+            ? await verifiedBy(this.options.keyring, digest, bundle.signatures)
+            : undefined;
+        return { trusted: signature !== undefined, digest, ...(signature ? { signature } : {}) };
+    }
+    async signedContent(definition) {
+        const pins = Object.entries(definition.prompts ?? {});
+        if (pins.length > 0 && !this.options.prompts) {
+            throw new ContextDefinitionError(`Bundle "${definition.name}" pins prompts; signing or verifying it needs the hub to have a prompt registry`);
+        }
+        const prompts = [];
+        for (const [, pin] of pins)
+            prompts.push(await this.options.prompts.get(pin.name, pin.version));
+        return signedContentOf(definition, prompts);
     }
     async read(name, version) {
         const stored = await this.store.getVersion(name, version);
@@ -304,6 +378,37 @@ function validate(definition) {
         }
     }
 }
+function signedContentOf(definition, prompts) {
+    const byPin = new Map(prompts.map((prompt) => [`${prompt.name}@${prompt.version}`, prompt]));
+    const pinned = {};
+    for (const [role, pin] of Object.entries(definition.prompts ?? {})) {
+        const prompt = byPin.get(`${pin.name}@${pin.version}`);
+        if (!prompt)
+            throw new ContextDefinitionError(`Bundle "${definition.name}" pins ${role} to ${pin.name}@${pin.version}, which is not at hand`);
+        pinned[role] = {
+            name: prompt.name,
+            messages: prompt.messages,
+            partials: prompt.partials,
+            config: prompt.config,
+            defaults: prompt.defaults,
+        };
+    }
+    return {
+        bundle: {
+            name: definition.name,
+            description: definition.description,
+            prompts: definition.prompts,
+            instructions: definition.instructions,
+            tools: definition.tools,
+            skills: definition.skills,
+            config: definition.config,
+        },
+        prompts: pinned,
+    };
+}
+function exportedPrompts(exported) {
+    return exported.prompts;
+}
 function toStored(bundle) {
     return { ...bundle, messages: [], variables: [] };
 }

package/dist/context-hub/index.d.ts

@@ -4,8 +4,9 @@ import type { Dataset, DatasetExample, Evaluator, Experiment } from '../types/ev
 import type { ToolDefinition } from '../types/messages.js';
 import type { ContextBundle, ContextPromotionGate } from './hub.js';
 export { type ContextChange, type ContextDiff, diffContexts, formatContextDiff } from './diff.js';
-export { type ContextBundle, type ContextBundleDefinition, type ContextBundleExport, ContextConflictError, ContextDefinitionError, type ContextHistoryEntry, ContextHub, ContextHubError, type ContextHubOptions, type ContextLabel, ContextNotFoundError, type ContextPromotionContext, ContextPromotionError, type ContextPromotionGate, type ContextPromotionResult, type ContextPromptPin, type ContextReference, type ContextSkill, type ContextTool, contextVersion, } from './hub.js';
+export { type ContextBundle, type ContextBundleDefinition, type ContextBundleExport, ContextConflictError, ContextDefinitionError, type ContextHistoryEntry, ContextHub, ContextHubError, type ContextHubOptions, type ContextLabel, ContextNotFoundError, type ContextPromotionContext, ContextPromotionError, type ContextPromotionGate, ContextSignatureError, type ContextVerification, type ContextPromotionResult, type ContextPromptPin, type ContextReference, type ContextSkill, type ContextTool, contextVersion, } from './hub.js';
 export type { ExperimentGateOptions } from '../prompts/gates.js';
+export { type ContextCryptoKey, type ContextJsonWebKey, type ContextKeyring, type ContextSignature, type ContextSignedContent, type ContextSigner, type ContextSigningKey, contextDigest, ed25519Keyring, ed25519Signer, generateContextKey, } from './signing.js';
 /**
  * A bundle's instructions joined into one system text, in the order the bundle lists them, or only
  * the ones named in `include`, in that order.

package/dist/context-hub/index.js

@@ -1,7 +1,8 @@
 import { fingerprintOf } from '../evaluate/cache.js';
 import { experimentVerdict } from '../prompts/gates.js';
 export { diffContexts, formatContextDiff } from './diff.js';
-export { ContextConflictError, ContextDefinitionError, ContextHub, ContextHubError, ContextNotFoundError, ContextPromotionError, contextVersion, } from './hub.js';
+export { ContextConflictError, ContextDefinitionError, ContextHub, ContextHubError, ContextNotFoundError, ContextPromotionError, ContextSignatureError, contextVersion, } from './hub.js';
+export { contextDigest, ed25519Keyring, ed25519Signer, generateContextKey, } from './signing.js';
 export function contextInstructions(bundle, options = {}) {
     const names = options.include ?? Object.keys(bundle.instructions ?? {});
     return names

package/dist/context-hub/signing.d.ts

@@ -0,0 +1,95 @@
+import type { PromptDefinition } from '../types/prompts.js';
+/** A JSON Web Key, as Web Crypto exports one. */
+export interface ContextJsonWebKey {
+    /** The key type: `OKP` for Ed25519. */
+    kty?: string;
+    /** The curve: `Ed25519`. */
+    crv?: string;
+    /** The public key, in base64url. */
+    x?: string;
+    /** The private key, in base64url, on a private key only. */
+    d?: string;
+    /** Anything else the exporter wrote. */
+    [field: string]: unknown;
+}
+/** A Web Crypto key, as `crypto.subtle` returns one. Any runtime's `CryptoKey` is one. */
+export interface ContextCryptoKey {
+    /** Its algorithm. */
+    readonly algorithm: unknown;
+    /** What it may do. */
+    readonly usages: readonly string[];
+}
+/** One signature on a bundle version. Stored with it, and carried by its export. */
+export interface ContextSignature {
+    /** The id of the key that signed, which a keyring looks up. */
+    keyId: string;
+    /** Always `Ed25519`. */
+    algorithm: 'Ed25519';
+    /**
+     * What was signed: `sha256:` and the full SHA-256, in hex, of the bundle's content and the content
+     * of every prompt it pins. A bundle's version is only the first 12 hex digits, enough to name a
+     * version but not to stand behind a signature.
+     */
+    digest: string;
+    /** The signature over the digest, in base64url. */
+    signature: string;
+    /** ISO-8601 time it was signed. */
+    signedAt: string;
+}
+/** Signs bundle digests with a private key, under a key id. */
+export interface ContextSigner {
+    /** The key's id, recorded on each signature so a keyring finds the public key. */
+    keyId: string;
+    /** Signs bytes. */
+    sign(data: Uint8Array): Promise<Uint8Array> | Uint8Array;
+}
+/** Verifies signatures by key id. A signature by a key the keyring does not hold never verifies. */
+export interface ContextKeyring {
+    /** Whether `signature` is `keyId`'s signature over `data`. */
+    verify(keyId: string, data: Uint8Array, signature: Uint8Array): Promise<boolean> | boolean;
+}
+/** A new signing key, with both halves as JSON Web Keys to keep in a secret store. */
+export interface ContextSigningKey {
+    /** The key's id. */
+    keyId: string;
+    /** Signs with the new key. */
+    signer: ContextSigner;
+    /** The public half, for every keyring that should trust it. */
+    publicKey: ContextJsonWebKey;
+    /** The private half. Keep it where the signer runs, and nowhere else. */
+    privateKey: ContextJsonWebKey;
+}
+/**
+ * Creates an Ed25519 signing key through Web Crypto, so on any runtime. The key id defaults to the
+ * first 16 hex digits of the public key's SHA-256, which is stable for the key and names nothing
+ * else.
+ */
+export declare function generateContextKey(keyId?: string): Promise<ContextSigningKey>;
+/** A signer from an Ed25519 private key, as a JSON Web Key or a Web Crypto key. */
+export declare function ed25519Signer(keyId: string, privateKey: ContextJsonWebKey | ContextCryptoKey): Promise<ContextSigner>;
+/** A keyring of trusted Ed25519 public keys, by key id. */
+export declare function ed25519Keyring(keys: Record<string, ContextJsonWebKey | ContextCryptoKey>): Promise<ContextKeyring>;
+/** What a bundle signature covers: the bundle's versioned content, and its pinned prompts' content. */
+export interface ContextSignedContent {
+    /** The bundle's name and the content its version covers. */
+    bundle: {
+        name: string;
+        description?: string;
+        prompts?: Record<string, {
+            name: string;
+            version: string;
+        }>;
+        instructions?: Record<string, string>;
+        tools?: unknown;
+        skills?: unknown;
+        config?: Record<string, unknown>;
+    };
+    /** Each pinned prompt's content, by role: what its own version covers. */
+    prompts: Record<string, Pick<PromptDefinition, 'name' | 'messages' | 'partials' | 'config' | 'defaults'>>;
+}
+/** The digest a signature covers, as `sha256:` and 64 hex digits. */
+export declare function contextDigest(content: ContextSignedContent): Promise<string>;
+/** Signs a digest. */
+export declare function signDigest(signer: ContextSigner, digest: string, at: Date): Promise<ContextSignature>;
+/** The first signature that is a trusted key's signature over exactly this digest, if any. */
+export declare function verifiedBy(keyring: ContextKeyring, digest: string, signatures?: readonly ContextSignature[]): Promise<ContextSignature | undefined>;