@hivemagnus/ardent 0.0.0-stage → 1.0.2

package/dist/plugins.js

@@ -0,0 +1,115 @@
+import { createRequire } from 'node:module';
+import { isAbsolute, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { defineTool } from './tools.js';
+const pluginName = /^[a-z][a-z0-9-]{0,63}$/;
+const registered = [];
+/** Identity helper that type-checks a plugin definition. */
+export function definePlugin(plugin) {
+    return plugin;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function assertPlugin(plugin, source) {
+    if (!isRecord(plugin) || typeof plugin.name !== 'string' || !pluginName.test(plugin.name))
+        throw new Error(`Plugin ${source} must export an object with a lowercase name`);
+    for (const hook of ['registerTools', 'routes', 'jobHandlers', 'jobOwnership', 'peerTool'])
+        if (plugin[hook] !== undefined && typeof plugin[hook] !== 'function')
+            throw new Error(`Plugin ${plugin.name} hook ${hook} must be a function`);
+    if (plugin.cliCommands !== undefined) {
+        if (!isRecord(plugin.cliCommands))
+            throw new Error(`Plugin ${plugin.name} cliCommands must be an object`);
+        for (const [name, command] of Object.entries(plugin.cliCommands))
+            if (!pluginName.test(name) || !isRecord(command) || typeof command.run !== 'function')
+                throw new Error(`Plugin ${plugin.name} CLI command ${name} is invalid`);
+    }
+}
+function validate(plugin, source) {
+    assertPlugin(plugin, source);
+    return plugin;
+}
+/** Register a plugin programmatically (for embedders that construct Ardent themselves). */
+export function registerPlugin(plugin) {
+    const valid = validate(plugin, 'registerPlugin');
+    if (registered.some(item => item.name === valid.name))
+        throw new Error(`Duplicate plugin: ${valid.name}`);
+    registered.push(valid);
+}
+/** Programmatically registered plugins. */
+export function registeredPlugins() { return [...registered]; }
+/** Remove programmatic registrations (tests and embedders). */
+export function clearRegisteredPlugins() { registered.length = 0; }
+async function importSpecifier(specifier, profileDir) {
+    if (specifier.startsWith('file://'))
+        return import(specifier);
+    if (isAbsolute(specifier))
+        return import(pathToFileURL(specifier).href);
+    // Resolve a package from the profile directory first, so a plugin may be
+    // installed next to the profile rather than next to Ardent itself.
+    try {
+        const resolved = createRequire(join(profileDir, 'package.json')).resolve(specifier);
+        return await import(pathToFileURL(resolved).href);
+    }
+    catch (error) {
+        if (!(error && typeof error === 'object' && 'code' in error && error.code === 'MODULE_NOT_FOUND'))
+            throw error;
+        return import(specifier);
+    }
+}
+/**
+ * Load the plugins named by `config.plugins`, plus any registered
+ * programmatically. A module's default export (or named `plugin` export) may
+ * be one plugin or an array of plugins.
+ */
+export async function loadPlugins(config, profileDir) {
+    const plugins = [...registered];
+    for (const specifier of config.plugins) {
+        const module = await importSpecifier(specifier, profileDir);
+        if (!isRecord(module))
+            throw new Error(`Plugin ${specifier} did not load as a module`);
+        const exported = module.default ?? module.plugin;
+        for (const item of Array.isArray(exported) ? exported : [exported]) {
+            const plugin = validate(item, specifier);
+            if (plugins.some(existing => existing.name === plugin.name))
+                throw new Error(`Duplicate plugin: ${plugin.name}`);
+            plugins.push(plugin);
+        }
+    }
+    return plugins;
+}
+/**
+ * Context for offline job-definition validation (`ardent jobs definitions
+ * validate`). No runtime exists there, so `runtime` and `tools` throw; a
+ * plugin's `jobHandlers` must only touch them inside `run`.
+ */
+class ValidationContext {
+    config;
+    profileDir;
+    env;
+    defineTool = defineTool;
+    constructor(config, profileDir, env) {
+        this.config = config;
+        this.profileDir = profileDir;
+        this.env = env;
+    }
+    get runtime() { throw new Error('The Ardent runtime is unavailable during offline validation'); }
+    get tools() { throw new Error('The tool registry is unavailable during offline validation'); }
+}
+export function validationContext(config, profileDir, env) {
+    return new ValidationContext(config, profileDir, env);
+}
+export function pluginContext(runtime, env) {
+    return { runtime, config: runtime.config, profileDir: runtime.profileDir, env, tools: runtime.tools, defineTool };
+}
+/** Merge plugin job handlers into a base registry; a duplicate handler ID is an error. */
+export function pluginJobHandlers(plugins, ctx, base = {}) {
+    const registry = { ...base };
+    for (const plugin of plugins)
+        for (const [id, handler] of Object.entries(plugin.jobHandlers?.(ctx) ?? {})) {
+            if (id in registry)
+                throw new Error(`Duplicate job handler ${id} from plugin ${plugin.name}`);
+            registry[id] = handler;
+        }
+    return registry;
+}

package/dist/research.d.ts

@@ -0,0 +1,110 @@
+import { z } from 'zod';
+export declare const ResearchBriefSchema: z.ZodObject<{
+    question: z.ZodString;
+    scope: z.ZodString;
+    as_of: z.ZodString;
+    findings: z.ZodArray<z.ZodString>;
+    claims: z.ZodArray<z.ZodObject<{
+        text: z.ZodString;
+        source_ids: z.ZodArray<z.ZodString>;
+        qualification: z.ZodString;
+    }, z.core.$strip>>;
+    contrary_evidence: z.ZodArray<z.ZodString>;
+    coverage_gaps: z.ZodArray<z.ZodString>;
+    artifact_ids: z.ZodArray<z.ZodString>;
+    answer_markdown: z.ZodString;
+    source_assessments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        source_id: z.ZodString;
+        reporting_role: z.ZodEnum<{
+            unknown: "unknown";
+            original: "original";
+            secondary: "secondary";
+        }>;
+        basis: z.ZodString;
+    }, z.core.$strip>>>;
+    source_register: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        source_id: z.ZodString;
+        url: z.ZodString;
+        evidence_kind: z.ZodEnum<{
+            search_snippet: "search_snippet";
+            extracted_article: "extracted_article";
+        }>;
+        reporting_role: z.ZodEnum<{
+            unknown: "unknown";
+            original: "original";
+            secondary: "secondary";
+        }>;
+        role_basis: z.ZodNullable<z.ZodString>;
+        title: z.ZodString;
+        published_at: z.ZodNullable<z.ZodString>;
+        retrieved_at: z.ZodNullable<z.ZodString>;
+        content_sha256: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>>;
+    candidate_slate: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        source_id: z.ZodString;
+        headline: z.ZodString;
+        summary: z.ZodString;
+        why_positive: z.ZodString;
+        topic: z.ZodString;
+        location: z.ZodString;
+        scores: z.ZodObject<{
+            recency: z.ZodNumber;
+            reliability: z.ZodNumber;
+            impact: z.ZodNumber;
+            specificity: z.ZodNumber;
+            constructive_value: z.ZodNumber;
+            user_relevance: z.ZodNumber;
+        }, z.core.$strict>;
+    }, z.core.$strict>>>;
+    syndication_groups: z.ZodOptional<z.ZodArray<z.ZodArray<z.ZodString>>>;
+    team_result: z.ZodOptional<z.ZodObject<{
+        version: z.ZodLiteral<"1.0">;
+        mission_id: z.ZodString;
+        mission_revision: z.ZodNumber;
+        task_id: z.ZodString;
+        outcome: z.ZodEnum<{
+            unknown: "unknown";
+            failed: "failed";
+            completed: "completed";
+            input_required: "input_required";
+            partial: "partial";
+            cancelled: "cancelled";
+            blocked: "blocked";
+        }>;
+        summary: z.ZodString;
+        checks: z.ZodArray<z.ZodObject<{
+            criterion: z.ZodString;
+            status: z.ZodEnum<{
+                unknown: "unknown";
+                pass: "pass";
+                fail: "fail";
+            }>;
+            evidence: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
+        artifacts: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            reference: z.ZodString;
+            sha256: z.ZodString;
+        }, z.core.$strict>>;
+        uncertain_effects: z.ZodArray<z.ZodString>;
+        clarification: z.ZodOptional<z.ZodObject<{
+            missing_fact: z.ZodString;
+            choices: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                label: z.ZodString;
+            }, z.core.$strict>>;
+            blocked_task: z.ZodString;
+            intended_respondent: z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<"operator">]>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ResearchBrief = z.infer<typeof ResearchBriefSchema>;
+/** Correct observed read-only formatting slips, then run the full research and
+ * team schemas. An aliased URL must match that source ID's retained evidence. */
+export declare function repairObservedResearchFormat(text: string, sourceIds: ReadonlySet<string>, artifactIds: ReadonlySet<string>, sourceUrls: ReadonlySet<string>, sourceUrlById?: ReadonlyMap<string, string>): string | null;
+/** Wrap only single-string research arrays after all other fields and citations validate. */
+export declare function repairResearchArrayStrings(text: string, sourceIds: ReadonlySet<string>, artifactIds: ReadonlySet<string>): {
+    text: string;
+    fields: Array<'findings' | 'coverage_gaps'>;
+} | null;
+export declare function parseResearchBrief(text: string, sourceIds: ReadonlySet<string>, artifactIds: ReadonlySet<string>): ResearchBrief;

package/dist/research.js

@@ -0,0 +1,164 @@
+import { z } from 'zod';
+import { TeamResult } from './team-contract.js';
+export const ResearchBriefSchema = z.object({
+    question: z.string().min(1),
+    scope: z.string().min(1),
+    as_of: z.string().datetime({ offset: true }),
+    findings: z.array(z.string().min(1)).max(20),
+    claims: z.array(z.object({ text: z.string().min(1), source_ids: z.array(z.string().min(1)).min(1), qualification: z.string() })).max(50),
+    contrary_evidence: z.array(z.string()).max(20),
+    coverage_gaps: z.array(z.string()).max(20),
+    artifact_ids: z.array(z.string().regex(/^[a-f0-9]{64}$/)).max(20),
+    answer_markdown: z.string().min(1),
+    source_assessments: z.array(z.object({ source_id: z.string(), reporting_role: z.enum(['original', 'secondary', 'unknown']), basis: z.string().min(1).max(500) })).max(100).optional(),
+    source_register: z.array(z.object({ source_id: z.string(), url: z.string().url(), evidence_kind: z.enum(['search_snippet', 'extracted_article']), reporting_role: z.enum(['original', 'secondary', 'unknown']), role_basis: z.string().nullable(), title: z.string(), published_at: z.string().nullable(), retrieved_at: z.string().nullable(), content_sha256: z.string().nullable() })).max(100).optional(),
+    candidate_slate: z.array(z.object({ source_id: z.string().min(1), headline: z.string().trim().min(1).max(180),
+        summary: z.string().trim().min(1).max(600), why_positive: z.string().trim().min(1).max(240),
+        topic: z.string().trim().min(1).max(80), location: z.string().trim().min(1).max(100),
+        scores: z.object({ recency: z.number().int().min(1).max(5), reliability: z.number().int().min(1).max(5),
+            impact: z.number().int().min(1).max(5), specificity: z.number().int().min(1).max(5),
+            constructive_value: z.number().int().min(1).max(5), user_relevance: z.number().int().min(1).max(5) }).strict() }).strict()).min(1).max(20).optional(),
+    syndication_groups: z.array(z.array(z.string()).min(2)).max(50).optional(),
+    team_result: TeamResult.optional()
+}).strict();
+/** Correct observed read-only formatting slips, then run the full research and
+ * team schemas. An aliased URL must match that source ID's retained evidence. */
+export function repairObservedResearchFormat(text, sourceIds, artifactIds, sourceUrls, sourceUrlById) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    const object = z.record(z.string(), z.unknown()).safeParse(raw);
+    if (!object.success || Buffer.byteLength(text, 'utf8') > 64_000)
+        return null;
+    const candidate = { ...object.data };
+    let changed = false;
+    if (Array.isArray(candidate.source_register) && candidate.source_register.length <= 100) {
+        const normalized = [];
+        for (const entry of candidate.source_register) {
+            const source = z.record(z.string(), z.unknown()).safeParse(entry);
+            if (!source.success)
+                return null;
+            if (!('exact_url' in source.data)) {
+                normalized.push(entry);
+                continue;
+            }
+            const { exact_url, ...fields } = source.data;
+            if (typeof fields.source_id !== 'string' || typeof exact_url !== 'string' ||
+                sourceUrlById?.get(fields.source_id) !== exact_url ||
+                (fields.url !== undefined && fields.url !== exact_url))
+                return null;
+            normalized.push({ ...fields, url: exact_url });
+            changed = true;
+        }
+        candidate.source_register = normalized;
+    }
+    if (Array.isArray(candidate.findings) && candidate.findings.length <= 20) {
+        const finding = z.object({ source_url: z.string().url(), retrieved_at: z.string().datetime({ offset: true }),
+            publisher_date: z.string().max(500), event_date: z.string().max(500) }).strict();
+        const normalized = [];
+        for (const entry of candidate.findings) {
+            if (typeof entry === 'string') {
+                normalized.push(entry);
+                continue;
+            }
+            const parsed = finding.safeParse(entry);
+            if (!parsed.success || !sourceUrls.has(parsed.data.source_url))
+                return null;
+            normalized.push(JSON.stringify(parsed.data));
+            changed = true;
+        }
+        candidate.findings = normalized;
+    }
+    const team = z.record(z.string(), z.unknown()).safeParse(candidate.team_result);
+    if (team.success && Array.isArray(team.data.checks) && team.data.checks.length === 1) {
+        const check = z.record(z.string(), z.unknown()).safeParse(team.data.checks[0]);
+        if (check.success && typeof check.data.evidence === 'string') {
+            const reference = check.data.evidence;
+            if (!reference.startsWith('source:') || !sourceUrls.has(reference.slice(7)))
+                return null;
+            candidate.team_result = { ...team.data, checks: [{ ...check.data, evidence: [reference] }] };
+            changed = true;
+        }
+    }
+    if (!changed)
+        return null;
+    const corrected = JSON.stringify(candidate);
+    try {
+        parseResearchBrief(corrected, sourceIds, artifactIds);
+    }
+    catch {
+        return null;
+    }
+    return corrected;
+}
+/** Wrap only single-string research arrays after all other fields and citations validate. */
+export function repairResearchArrayStrings(text, sourceIds, artifactIds) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    const object = z.record(z.string(), z.unknown()).safeParse(raw);
+    if (!object.success)
+        return null;
+    const { coverage_gaps: gaps, ...other } = object.data;
+    if (typeof gaps !== 'string' || !gaps.trim() || Buffer.byteLength(gaps, 'utf8') > 2000)
+        return null;
+    const findings = other.findings;
+    if (typeof findings === 'string' && (!findings.trim() || Buffer.byteLength(findings, 'utf8') > 2000))
+        return null;
+    const fields = typeof findings === 'string'
+        ? ['findings', 'coverage_gaps'] : ['coverage_gaps'];
+    const normalized = typeof findings === 'string' ? { ...other, findings: [findings] } : other;
+    if (!ResearchBriefSchema.omit({ coverage_gaps: true }).safeParse(normalized).success)
+        return null;
+    const corrected = JSON.stringify({ ...normalized, coverage_gaps: [gaps] });
+    try {
+        parseResearchBrief(corrected, sourceIds, artifactIds);
+    }
+    catch {
+        return null;
+    }
+    return { text: corrected, fields };
+}
+export function parseResearchBrief(text, sourceIds, artifactIds) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        throw new Error('Research result is not JSON');
+    }
+    if (typeof value === 'object' && value !== null && !Array.isArray(value) && 'findings' in value && typeof value.findings === 'string') {
+        // A single finding is unambiguous; keep citation and claim validation strict.
+        value = { ...value, findings: value.findings.trim() ? [value.findings] : [] };
+    }
+    const brief = ResearchBriefSchema.parse(value);
+    for (const claim of brief.claims)
+        for (const id of claim.source_ids)
+            if (!sourceIds.has(id))
+                throw new Error(`Research claim cites unknown source ${id}`);
+    for (const source of brief.source_assessments ?? [])
+        if (!sourceIds.has(source.source_id))
+            throw new Error(`Research assessment cites unknown source ${source.source_id}`);
+    for (const source of brief.source_register ?? [])
+        if (!sourceIds.has(source.source_id))
+            throw new Error(`Research register cites unknown source ${source.source_id}`);
+    for (const candidate of brief.candidate_slate ?? [])
+        if (!sourceIds.has(candidate.source_id))
+            throw new Error(`Research candidate cites unknown source ${candidate.source_id}`);
+    for (const id of brief.artifact_ids)
+        if (!artifactIds.has(id))
+            throw new Error(`Research result cites unknown artifact ${id}`);
+    if (!sourceIds.size && brief.claims.length)
+        throw new Error('Research result contains claims without retrieved sources');
+    if (!sourceIds.size && (brief.findings.length || !brief.coverage_gaps.length))
+        throw new Error('Empty retrieval requires empty findings and an explicit coverage gap');
+    return brief;
+}

package/dist/runtime.d.ts

@@ -0,0 +1,33 @@
+import { type ArdentConfig } from './config.js';
+import { ArtifactStore } from './artifacts.js';
+import { type ResearchBrief } from './research.js';
+import { TaskStore, type Task } from './store.js';
+import { ToolRegistry } from './tools.js';
+import { type ArdentPlugin } from './plugins.js';
+export type RunResult = {
+    task: Task;
+    answer: string;
+    brief?: ResearchBrief;
+};
+export declare class ArdentRuntime {
+    #private;
+    readonly profileDir: string;
+    readonly config: ArdentConfig;
+    readonly store: TaskStore;
+    readonly artifacts: ArtifactStore;
+    readonly tools: ToolRegistry;
+    readonly recovered: {
+        queued: Task[];
+        interrupted: number;
+    };
+    get draining(): boolean;
+    get plugins(): readonly ArdentPlugin[];
+    constructor(profileDir: string, config: ArdentConfig, env?: NodeJS.ProcessEnv);
+    /** Install plugins once, before the runtime accepts work. Plugin tools join the shared registry. */
+    usePlugins(plugins: readonly ArdentPlugin[], env?: NodeJS.ProcessEnv): Promise<void>;
+    close(): void;
+    drain(timeoutMs?: number): Promise<boolean>;
+    accept(prompt: string, caller?: string, context?: 'direct' | 'peer' | 'scheduled', idempotencyKey?: string, sessionId?: string, originalDeadlineMs?: number, backendOverride?: 'llamacpp' | 'codex'): Task;
+    cancel(id: string): Task;
+    run(taskId: string, env?: NodeJS.ProcessEnv, onText?: (chunk: string, step: number) => void): Promise<RunResult>;
+}