@hivemagnus/ardent 0.0.0-stage → 1.0.2

package/dist/job-news-handlers.js

@@ -0,0 +1,153 @@
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+import { registerNewsTools } from './news.js';
+import { ToolRegistry } from './tools.js';
+const DiscoverySource = z.object({ id: z.string().regex(/^[a-z][a-z0-9_]{1,40}$/),
+    query: z.string().trim().min(3).max(300), category: z.enum(['news', 'general']).default('news'),
+    time_range: z.enum(['day', 'week', 'month', 'year', 'all']).default('day'), language: z.string().regex(/^[a-z]{2}(?:-[A-Z]{2})?$/).default('en'),
+    limit: z.number().int().min(1).max(12), max_articles: z.number().int().min(1).max(5),
+    allow_hosts: z.array(z.string().regex(/^[a-z0-9.-]+\.[a-z]{2,}$/)).max(8).default([]),
+    include_title_terms: z.array(z.string().trim().min(2).max(80)).min(1).max(32).optional() }).strict();
+export const BoundedNewsInput = z.object({
+    query: z.string().trim().min(3).max(300),
+    category: z.enum(['news', 'general']).default('news'),
+    time_range: z.enum(['day', 'week', 'month']).default('day'),
+    language: z.string().regex(/^[a-z]{2}(?:-[A-Z]{2})?$/).default('en'),
+    limit: z.number().int().min(1).max(10).default(8),
+    max_articles: z.number().int().min(1).max(5).default(3),
+    purpose: z.string().regex(/^[a-z][a-z0-9_]{0,63}$/).default('news_packet'),
+    /** Retry an empty packet after transient read-only failures until the final attempt. */
+    retry_empty: z.boolean().default(false),
+    fallback_searches: z.array(z.object({ query: z.string().trim().min(3).max(300),
+        category: z.enum(['news', 'general']) }).strict()).min(1).max(2).optional(),
+    discovery_sources: z.array(DiscoverySource).min(1).max(12).optional(),
+    /** Hosts treated as first-party publishers in source provenance. */
+    publisher_hosts: z.array(z.string().regex(/^[a-z0-9.-]+\.[a-z]{2,}$/)).max(32).default([])
+}).strict().superRefine((value, context) => {
+    const discoveryIds = value.discovery_sources?.map(item => item.id) ?? [];
+    if (new Set(discoveryIds).size !== discoveryIds.length)
+        context.addIssue({ code: z.ZodIssueCode.custom, path: ['discovery_sources'], message: 'Duplicate discovery source' });
+});
+const Article = z.object({ url: z.string().url(), source_url: z.string().url(), source_id: z.string(),
+    title: z.string(), published_at: z.string().nullable(), retrieved_at: z.string(),
+    content_sha256: z.string().regex(/^[a-f0-9]{64}$/), warning: z.string() }).passthrough();
+const Packet = z.object({ status: z.enum(['ok', 'partial', 'empty']),
+    articles: z.array(Article).max(5), failures: z.array(z.object({ url: z.string(), error: z.string() })).max(10),
+    coverage: z.object({ discovered: z.number().int(), title_prefiltered: z.number().int().optional(),
+        extracted: z.number().int() }),
+    search: z.object({ retrieved_at: z.string(), unresponsive_engines: z.array(z.unknown()) }).passthrough(),
+    artifact: z.object({ id: z.string().regex(/^[a-f0-9]{64}$/) }).passthrough() }).passthrough();
+const hash = (value) => createHash('sha256').update(value).digest('hex');
+/** Bounded first-party retrieval. A packet is source evidence, never claim verification or delivery. */
+export function boundedNewsHandler(runtime, env) {
+    return { input: BoundedNewsInput, effect: 'external', run: async ({ job, input, signal, attempt }) => {
+            if (job.delivery.kind !== 'none')
+                throw new Error('News source packet cannot deliver directly');
+            const request = BoundedNewsInput.parse(input);
+            const tools = new ToolRegistry();
+            registerNewsTools(tools, runtime.config, runtime.artifacts, env);
+            const discoverySources = request.discovery_sources ?? [{ id: 'default', query: request.query,
+                    category: request.category, time_range: request.time_range, language: request.language,
+                    limit: request.limit, max_articles: request.max_articles, allow_hosts: [] },
+                ...(request.fallback_searches ?? []).map((item, index) => ({ id: `fallback_${index + 1}`,
+                    query: item.query, category: item.category, time_range: request.time_range,
+                    language: request.language, limit: request.limit, max_articles: request.max_articles, allow_hosts: [] }))];
+            const packets = [];
+            const discoveryFailures = [];
+            for (const source of discoverySources) {
+                if (source.id.startsWith('fallback_') && packets.some(item => item.packet.articles.length > 0))
+                    break;
+                const result = await tools.call('news_collect', {
+                    query: source.query, category: source.category, time_range: source.time_range,
+                    language: source.language, limit: source.limit, max_articles: source.max_articles,
+                    ...('include_title_terms' in source && source.include_title_terms
+                        ? { include_title_terms: source.include_title_terms } : {})
+                }, 'scheduled', signal);
+                if (!result.ok) {
+                    if (result.effect === 'unknown')
+                        return { state: 'unknown',
+                            receipt: { effect_status: 'unknown', evidence: { code: result.code,
+                                    message: result.message.slice(0, 200), discovery_source_id: source.id,
+                                    prior_discovery_packet_ids: packets.map(item => item.packet.artifact.id),
+                                    discovery_effect: 'unknown', delivery: 'not_attempted' } } };
+                    discoveryFailures.push({ source_id: source.id, code: result.code,
+                        message: result.message.slice(0, 200) });
+                    continue;
+                }
+                packets.push({ source, packet: Packet.parse(result.value) });
+            }
+            if (!packets.length)
+                return { state: 'retry',
+                    receipt: { effect_status: 'none', evidence: { discovery_failures: discoveryFailures } } };
+            const first = packets[0]?.packet ?? null;
+            const allowed = (host, domains) => !domains.length ||
+                domains.some(domain => host === domain || host.endsWith(`.${domain}`));
+            const publisher = (host) => request.publisher_hosts
+                .some(domain => host === domain || host.endsWith(`.${domain}`));
+            const sources = packets.flatMap(({ source, packet }) => packet.articles.filter(article => allowed(new URL(article.url).hostname, source.allow_hosts) &&
+                allowed(new URL(article.source_url).hostname, source.allow_hosts)).map(article => ({
+                source_id: article.source_id, discovery_source_id: source.id, url: article.url,
+                publisher: new URL(article.source_url).hostname, publisher_url: article.source_url,
+                published_at: article.published_at, retrieved_at: article.retrieved_at,
+                extraction: 'extracted', content_sha256: article.content_sha256,
+                reporting_role: 'unknown',
+                provenance: publisher(new URL(article.source_url).hostname)
+                    ? 'publisher-search' : 'secondary-reporting',
+                claim_verification: 'unverified', title_sha256: hash(article.title)
+            })));
+            const failures = packets.flatMap(({ source, packet }) => packet.failures.map(item => ({
+                discovery_source_id: source.id, url: item.url, error: item.error.slice(0, 200)
+            }))).slice(0, 10);
+            const discoveryPackets = packets.map(({ source, packet }) => ({ source_id: source.id,
+                artifact_id: packet.artifact.id, status: packet.status,
+                filtered_articles: packet.articles.length - packet.articles.filter(article => allowed(new URL(article.url).hostname, source.allow_hosts) &&
+                    allowed(new URL(article.source_url).hostname, source.allow_hosts)).length,
+                coverage: packet.coverage, unresponsive_engines: packet.search.unresponsive_engines.length }));
+            const coverage = { discovered: packets.reduce((sum, item) => sum + item.packet.coverage.discovered, 0),
+                extracted: packets.reduce((sum, item) => sum + item.packet.coverage.extracted, 0) };
+            const unresponsiveEngines = packets.reduce((sum, item) => sum + item.packet.search.unresponsive_engines.length, 0);
+            // A transient, definitely read-only outage must not seal an empty morning
+            // packet on the first attempt. Unknown tool effects return above and are
+            // never retried. The final attempt still retains the honest partial packet.
+            if (request.retry_empty && !sources.length &&
+                (unresponsiveEngines || failures.length || discoveryFailures.length) && attempt < job.policy.max_attempts) {
+                return { state: 'retry', receipt: { effect_status: 'none', evidence: {
+                            reason: 'No extracted article after transient read-only retrieval failures',
+                            prior_discovery_packet_ids: packets.map(item => item.packet.artifact.id),
+                            discovery_failures: discoveryFailures, failures, unresponsive_engines: unresponsiveEngines,
+                            coverage, delivery: 'not_attempted'
+                        } } };
+            }
+            const searchedAt = packets.map(item => item.packet.search.retrieved_at).sort().at(-1) ?? null;
+            if (!first)
+                throw new Error('News packet is unavailable');
+            // Retain every attempted search and its failure detail, including empty
+            // discovery. The digest-bound packet must match the combined source receipt.
+            const packet = packets.length === 1 ? first : { ...first,
+                articles: packets.flatMap(item => item.packet.articles).slice(0, 5),
+                discovery_packets: discoveryPackets, discovery_failures: discoveryFailures,
+                searches: packets.map(item => ({ source_id: item.source.id, query: item.packet.search.query,
+                    retrieved_at: item.packet.search.retrieved_at, status: item.packet.search.status,
+                    unresponsive_engines: item.packet.search.unresponsive_engines })), failures, coverage };
+            const artifact = packets.length === 1 ? first.artifact
+                : await runtime.artifacts.put('news-source-packet.json', 'application/json', Buffer.from(JSON.stringify(packet)));
+            return { state: 'completed', receipt: { effect_status: 'confirmed', evidence: {
+                        purpose: request.purpose, source_packet_id: artifact.id,
+                        status: discoveryFailures.length || failures.length || unresponsiveEngines ? 'partial' : sources.length ? 'ok' : 'empty',
+                        searched_at: searchedAt, sources, failures,
+                        unresponsive_engines: unresponsiveEngines,
+                        discovery_packets: discoveryPackets, discovery_failures: discoveryFailures,
+                        coverage_gaps: sources.length ? [] : ['No retained articles; inspect discovery engine failures and empty search coverage'],
+                        coverage, delivery: 'not_attempted',
+                        warning: 'Publisher extraction and search rank do not verify claims or independent reporting.'
+                    } } };
+        } };
+}
+/** Built-in scheduled job handlers available to every profile. */
+export function builtinJobHandlers(runtime, env) {
+    return { 'news.collect': boundedNewsHandler(runtime, env) };
+}
+/** Validation-only registry (no runtime) for `ardent jobs definitions validate`. */
+export const BUILTIN_JOB_VALIDATION_REGISTRY = {
+    'news.collect': { input: BoundedNewsInput, effect: 'external', run: () => Promise.reject(new Error('Validation-only handler')) }
+};

package/dist/job-ownership.d.ts

@@ -0,0 +1,9 @@
+import type { JobDefinition, OwnershipCheck } from './job-engine.js';
+/**
+ * Default ownership policy: an enabled job explicitly assigned to Ardent may
+ * run. Deployments that migrate schedules from another scheduler can add a
+ * stricter check through a plugin (`ArdentPlugin.jobOwnership`).
+ */
+export declare function assertJobOwnership(job: JobDefinition): Promise<void>;
+/** Combine the default policy with optional extra checks; every check must pass. */
+export declare function composeOwnershipChecks(extra?: readonly OwnershipCheck[]): OwnershipCheck;

package/dist/job-ownership.js

@@ -0,0 +1,17 @@
+/**
+ * Default ownership policy: an enabled job explicitly assigned to Ardent may
+ * run. Deployments that migrate schedules from another scheduler can add a
+ * stricter check through a plugin (`ArdentPlugin.jobOwnership`).
+ */
+export async function assertJobOwnership(job) {
+    if (!job.enabled || job.owner !== 'ardent')
+        throw new Error('Job is not assigned to Ardent');
+}
+/** Combine the default policy with optional extra checks; every check must pass. */
+export function composeOwnershipChecks(extra = []) {
+    return async (job, now) => {
+        await assertJobOwnership(job);
+        for (const check of extra)
+            await check(job, now);
+    };
+}

package/dist/json-schema.d.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+export type JsonSchemaTarget = 'openapi-3.0' | 'draft-7';
+/**
+ * JSON Schema for a request-side Zod schema: tool parameters, API request
+ * bodies, configuration, and model output contracts. Fields with defaults are
+ * optional because callers may omit them, and refinements and transforms
+ * describe what a caller sends. Nested schemas are inlined (no $ref).
+ */
+export declare function toJsonSchema(schema: z.ZodType, target?: JsonSchemaTarget): Record<string, unknown>;

package/dist/json-schema.js

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+/**
+ * JSON Schema for a request-side Zod schema: tool parameters, API request
+ * bodies, configuration, and model output contracts. Fields with defaults are
+ * optional because callers may omit them, and refinements and transforms
+ * describe what a caller sends. Nested schemas are inlined (no $ref).
+ */
+export function toJsonSchema(schema, target = 'draft-7') {
+    return z.toJSONSchema(schema, {
+        target, io: 'input', reused: 'inline', unrepresentable: 'any',
+        // Zod 4 emits oneOf for discriminated unions. Keep anyOf (equivalent for
+        // exclusive variants) because some function-calling schema dialects reject oneOf.
+        override: ({ jsonSchema }) => {
+            if (jsonSchema.oneOf) {
+                jsonSchema.anyOf = jsonSchema.oneOf;
+                delete jsonSchema.oneOf;
+            }
+        },
+    });
+}

package/dist/llamacpp.d.ts

@@ -0,0 +1,49 @@
+import type { ArdentConfig } from './config.js';
+import type { BackendEventSink } from './backend-events.js';
+export type ChatMessage = {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string | null;
+    tool_call_id?: string;
+    tool_calls?: ModelToolCall[];
+};
+export type ModelToolCall = {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+};
+export type ModelReply = {
+    content: string;
+    reasoning?: string;
+    toolCalls: ModelToolCall[];
+    usage?: {
+        promptTokens?: number;
+        completionTokens?: number;
+    };
+};
+export type LlamaCapabilities = {
+    modelListed: boolean | null;
+    contextTokens: number | null;
+    supportsTools: boolean | null;
+    supportsReasoningEffort: boolean | null;
+    sampling: {
+        temperature: number | null;
+        topP: number | null;
+    };
+    reasoningFormat: string | null;
+    chatFormat: string | null;
+};
+export declare function llamaEndpoint(base: string, operation: 'chat/completions' | 'chat/completions/input_tokens' | 'models'): URL;
+export declare function sseData(stream: ReadableStream<Uint8Array>): AsyncGenerator<string>;
+export declare class NativeLlmBackend {
+    #private;
+    readonly config: ArdentConfig['providers']['llamacpp'];
+    readonly env: NodeJS.ProcessEnv;
+    constructor(config: ArdentConfig['providers']['llamacpp'], env?: NodeJS.ProcessEnv);
+    discover(): Promise<LlamaCapabilities>;
+    countInputTokens(messages: ChatMessage[], tools: object[], signal: AbortSignal): Promise<number | null>;
+    complete(messages: ChatMessage[], tools: object[], signal: AbortSignal, stream?: boolean, onText?: (chunk: string) => void, onEvent?: BackendEventSink): Promise<ModelReply>;
+}
+export { NativeLlmBackend as LlamaCppBackend };

package/dist/llamacpp.js

@@ -0,0 +1,216 @@
+import { z } from 'zod';
+import { setTimeout as delay } from 'node:timers/promises';
+import { resolveReference } from './config.js';
+export function llamaEndpoint(base, operation) {
+    const url = new URL(base);
+    const path = url.pathname.replace(/\/$/, '');
+    url.pathname = `${path}${path.endsWith('/v1') ? '' : '/v1'}/${operation}`;
+    return url;
+}
+const ToolCall = z.object({ id: z.string().min(1), type: z.literal('function'), function: z.object({ name: z.string().min(1), arguments: z.string() }) });
+const FullResponse = z.object({ choices: z.array(z.object({ message: z.object({ content: z.string().nullable().optional(), reasoning_content: z.string().optional(), tool_calls: z.array(ToolCall).optional() }) })).min(1), usage: z.object({ prompt_tokens: z.number().optional(), completion_tokens: z.number().optional() }).optional() });
+const Delta = z.object({ choices: z.array(z.object({ delta: z.object({ content: z.string().nullable().optional(), reasoning_content: z.string().nullable().optional(), tool_calls: z.array(z.object({ index: z.number().int().nonnegative(), id: z.string().optional(), type: z.literal('function').optional(), function: z.object({ name: z.string().optional(), arguments: z.string().optional() }).optional() })).optional() }) })), usage: z.object({ prompt_tokens: z.number().optional(), completion_tokens: z.number().optional() }).nullable().optional() });
+const Models = z.object({ data: z.array(z.object({ id: z.string(), aliases: z.array(z.string()).optional(), meta: z.object({ n_ctx: z.number().int().positive().optional() }).passthrough().optional() }).passthrough()) }).passthrough();
+const Props = z.object({ model_alias: z.string().optional(), default_generation_settings: z.object({ n_ctx: z.number().int().positive().optional(), params: z.object({ temperature: z.number().optional(), top_p: z.number().optional(), reasoning_format: z.string().optional(), chat_format: z.string().optional() }).passthrough().optional() }).passthrough().optional(), chat_template_caps: z.object({ supports_tools: z.boolean().optional(), supports_tool_calls: z.boolean().optional(), supports_reasoning_effort: z.boolean().optional() }).passthrough().optional() }).passthrough();
+function readUsage(value) {
+    return { ...(value.prompt_tokens === undefined ? {} : { promptTokens: value.prompt_tokens }), ...(value.completion_tokens === undefined ? {} : { completionTokens: value.completion_tokens }) };
+}
+export async function* sseData(stream) {
+    const reader = stream.getReader();
+    const decoder = new TextDecoder();
+    let pending = '';
+    try {
+        while (true) {
+            const part = await reader.read();
+            if (part.done)
+                break;
+            pending = (pending + decoder.decode(part.value, { stream: true })).replace(/\r\n/g, '\n');
+            let boundary;
+            while ((boundary = pending.indexOf('\n\n')) >= 0) {
+                const event = pending.slice(0, boundary);
+                pending = pending.slice(boundary + 2);
+                const lines = event.split('\n').filter(line => line.startsWith('data:'));
+                if (lines.length)
+                    yield lines.map(line => line.slice(5).trimStart()).join('\n');
+            }
+        }
+        pending += decoder.decode();
+        if (pending.trim())
+            throw new Error('Incomplete SSE event');
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+export class NativeLlmBackend {
+    config;
+    env;
+    #discovery;
+    constructor(config, env = process.env) {
+        this.config = config;
+        this.env = env;
+    }
+    discover() {
+        this.#discovery ??= this.#discover();
+        return this.#discovery;
+    }
+    async countInputTokens(messages, tools, signal) {
+        const base = resolveReference(this.config.base_url, this.env);
+        const model = resolveReference(this.config.model, this.env);
+        if (!base || !model)
+            throw new Error('llama.cpp endpoint/model is unconfigured');
+        const token = this.env[this.config.api_key_env];
+        try {
+            const response = await fetch(llamaEndpoint(base, 'chat/completions/input_tokens'), {
+                method: 'POST', redirect: 'manual', signal: AbortSignal.any([signal, AbortSignal.timeout(5000)]),
+                headers: { 'Content-Type': 'application/json', ...(token ? { Authorization: `Bearer ${token}` } : {}) },
+                body: JSON.stringify({ model, messages, tools })
+            });
+            if (response.status === 404 || response.status === 405)
+                return null;
+            if (!response.ok)
+                throw new Error(`llama.cpp token count HTTP ${response.status}`);
+            return z.object({ input_tokens: z.number().int().nonnegative() }).parse(await response.json()).input_tokens;
+        }
+        catch (error) {
+            if (signal.aborted)
+                throw error;
+            return null; // Older servers lack token counting; the bounded local estimator remains active.
+        }
+    }
+    async #discover() {
+        const base = resolveReference(this.config.base_url, this.env);
+        const model = resolveReference(this.config.model, this.env);
+        if (!base || !model)
+            throw new Error('llama.cpp endpoint/model is unconfigured');
+        const token = this.env[this.config.api_key_env];
+        const headers = token ? { Authorization: `Bearer ${token}` } : {};
+        const get = async (url) => {
+            const response = await fetch(url, { headers, redirect: 'manual', signal: AbortSignal.timeout(2000) });
+            if (!response.ok)
+                throw new Error(`HTTP ${response.status}`);
+            return await response.json();
+        };
+        const root = new URL(base);
+        root.pathname = root.pathname.replace(/\/v1\/?$/, '/');
+        root.search = '';
+        root.hash = '';
+        const [modelsRaw, propsRaw] = await Promise.allSettled([get(llamaEndpoint(base, 'models')), get(new URL('props', root))]);
+        const models = modelsRaw.status === 'fulfilled' ? Models.safeParse(modelsRaw.value) : undefined;
+        const props = propsRaw.status === 'fulfilled' ? Props.safeParse(propsRaw.value) : undefined;
+        const entries = models?.success ? models.data.data : undefined;
+        const selected = entries?.find(item => item.id === model || item.aliases?.includes(model));
+        const settings = props?.success ? props.data.default_generation_settings : undefined;
+        const caps = props?.success ? props.data.chat_template_caps : undefined;
+        return { modelListed: entries ? Boolean(selected) : null, contextTokens: this.config.context_window_tokens ?? selected?.meta?.n_ctx ?? settings?.n_ctx ?? null,
+            supportsTools: caps?.supports_tools === false || caps?.supports_tool_calls === false ? false : caps?.supports_tools && caps.supports_tool_calls ? true : null,
+            supportsReasoningEffort: caps?.supports_reasoning_effort ?? null,
+            sampling: { temperature: settings?.params?.temperature ?? null, topP: settings?.params?.top_p ?? null },
+            reasoningFormat: settings?.params?.reasoning_format ?? null, chatFormat: settings?.params?.chat_format ?? null };
+    }
+    async complete(messages, tools, signal, stream = true, onText, onEvent) {
+        const base = resolveReference(this.config.base_url, this.env);
+        const model = resolveReference(this.config.model, this.env);
+        if (!base || !model)
+            throw new Error('llama.cpp endpoint/model is unconfigured');
+        const endpoint = llamaEndpoint(base, 'chat/completions');
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.config.request_timeout_seconds * 1000);
+        const abort = () => controller.abort();
+        signal.addEventListener('abort', abort, { once: true });
+        try {
+            if (signal.aborted)
+                controller.abort();
+            const token = this.env[this.config.api_key_env];
+            const capabilities = this.config.reasoning_effort ? await this.discover() : undefined;
+            if (this.config.reasoning_effort && capabilities?.supportsReasoningEffort !== true)
+                throw new Error('llama.cpp reasoning effort is not advertised by the current chat template');
+            if (tools.length && capabilities?.supportsTools === false)
+                throw new Error('llama.cpp chat template does not support tools');
+            onEvent?.({ kind: 'started', backend: 'llamacpp' });
+            let response;
+            for (let attempt = 0; attempt < 2; attempt++) {
+                try {
+                    response = await fetch(endpoint, { method: 'POST', headers: { 'Content-Type': 'application/json', Accept: stream ? 'text/event-stream' : 'application/json', ...(token ? { Authorization: `Bearer ${token}` } : {}) }, body: JSON.stringify({ model, messages, tools, stream, max_tokens: this.config.max_output_tokens ?? 4096, ...(this.config.reasoning_effort ? { reasoning_effort: this.config.reasoning_effort } : {}), ...(stream ? { stream_options: { include_usage: true } } : {}) }), redirect: 'manual', signal: controller.signal });
+                }
+                catch (error) {
+                    if (attempt || controller.signal.aborted || signal.aborted)
+                        throw error;
+                    await delay(200, undefined, { signal: controller.signal });
+                    continue;
+                }
+                if (attempt === 0 && (response.status === 429 || response.status === 503)) {
+                    await response.body?.cancel();
+                    const retryAfter = Number(response.headers.get('retry-after'));
+                    const waitMs = Number.isFinite(retryAfter) && retryAfter > 0 ? Math.min(2000, retryAfter * 1000) : 200;
+                    await delay(waitMs, undefined, { signal: controller.signal });
+                    continue;
+                }
+                break;
+            }
+            if (!response)
+                throw new Error('llama.cpp transport failed before response');
+            if (!response.ok)
+                throw new Error(`llama.cpp HTTP ${response.status}`);
+            if (!stream) {
+                const raw = await response.json();
+                const parsed = FullResponse.parse(raw);
+                const message = parsed.choices[0]?.message;
+                if (!message)
+                    throw new Error('llama.cpp returned no message');
+                if (message.content) {
+                    onText?.(message.content);
+                    onEvent?.({ kind: 'text_delta', backend: 'llamacpp', text: message.content });
+                }
+                const reply = { content: message.content ?? '', ...(message.reasoning_content ? { reasoning: message.reasoning_content } : {}), toolCalls: message.tool_calls ?? [], ...(parsed.usage ? { usage: readUsage(parsed.usage) } : {}) };
+                onEvent?.({ kind: 'completed', backend: 'llamacpp', output_chars: reply.content.length, tool_calls: reply.toolCalls.length, reasoning_chars: reply.reasoning?.length ?? 0, usage: reply.usage ?? null });
+                return reply;
+            }
+            if (!response.body)
+                throw new Error('llama.cpp returned no SSE stream');
+            let content = '';
+            let reasoning = '';
+            let usage;
+            let done = false;
+            const calls = new Map();
+            for await (const data of sseData(response.body)) {
+                if (data === '[DONE]') {
+                    done = true;
+                    break;
+                }
+                const raw = JSON.parse(data);
+                const event = Delta.parse(raw);
+                if (event.usage)
+                    usage = readUsage(event.usage);
+                for (const choice of event.choices) {
+                    content += choice.delta.content ?? '';
+                    if (choice.delta.content) {
+                        onText?.(choice.delta.content);
+                        onEvent?.({ kind: 'text_delta', backend: 'llamacpp', text: choice.delta.content });
+                    }
+                    reasoning += choice.delta.reasoning_content ?? '';
+                    for (const call of choice.delta.tool_calls ?? []) {
+                        const prior = calls.get(call.index) ?? { id: '', name: '', arguments: '' };
+                        if (call.id)
+                            prior.id = call.id;
+                        if (call.function?.name)
+                            prior.name += call.function.name;
+                        if (call.function?.arguments)
+                            prior.arguments += call.function.arguments;
+                        calls.set(call.index, prior);
+                    }
+                }
+            }
+            if (!done)
+                throw new Error('llama.cpp SSE stream ended before [DONE]');
+            const toolCalls = [...calls.entries()].sort(([a], [b]) => a - b).map(([, value]) => ToolCall.parse({ id: value.id, type: 'function', function: { name: value.name, arguments: value.arguments } }));
+            onEvent?.({ kind: 'completed', backend: 'llamacpp', output_chars: content.length, tool_calls: toolCalls.length, reasoning_chars: reasoning.length, usage: usage ?? null });
+            return { content, ...(reasoning ? { reasoning } : {}), toolCalls, ...(usage ? { usage } : {}) };
+        }
+        finally {
+            clearTimeout(timer);
+            signal.removeEventListener('abort', abort);
+        }
+    }
+}
+export { NativeLlmBackend as LlamaCppBackend };

package/dist/magnus-control.d.ts

@@ -0,0 +1,3 @@
+import { type ToolRegistry } from './tools.js';
+/** Optional read-only Magnus Control tools. The base URL and token come from the environment only. */
+export declare function registerMagnusControlTools(registry: ToolRegistry, env: NodeJS.ProcessEnv): void;

package/dist/magnus-control.js

@@ -0,0 +1,99 @@
+import { z } from 'zod';
+import { defineTool } from './tools.js';
+import { magnusFleetReadinessTool } from './magnus-readiness.js';
+import { magnusNodeDependencyImpactTool } from './magnus-node-dependency-impact.js';
+import { readOwnedApi } from './owner-read.js';
+import { magnusOwnerReadTools } from './magnus-owner-reads.js';
+const id = z.string().regex(/^[A-Za-z0-9_-]{1,128}$/);
+const node = z.object({ id: z.string(), name: z.string(), hostname: z.string().nullable().optional(), status: z.string() }).passthrough();
+const count = z.number().int().nonnegative();
+const anomalySummary = z.object({
+    totalActive: count,
+    byNode: z.array(z.object({ nodeId: id, nodeName: z.string().max(160), count, metrics: z.array(z.string().max(80)).max(16) }).passthrough()).max(100),
+    bySeverity: z.object({ info: count, warning: count, critical: count }).passthrough()
+}).passthrough();
+const commandStatus = z.object({
+    id, nodeId: id,
+    status: z.enum(['PENDING', 'QUEUED', 'RUNNING', 'COMPLETED', 'FAILED', 'TIMEOUT', 'CANCELLED']),
+    createdAt: z.string().datetime(), startedAt: z.string().datetime().nullable(), completedAt: z.string().datetime().nullable(),
+    result: z.object({ exitCode: z.number().int(), durationMs: count, truncated: z.boolean() }).passthrough().nullable()
+}).passthrough();
+// The owning agent reports health with its 30-second heartbeat. This matches
+// the Control API's default stale-node threshold, but is a tool-local label:
+// an operator may configure a different server-side threshold.
+const HEALTH_FRESHNESS_LIMIT_MS = 120_000;
+const HEALTH_FUTURE_SKEW_MS = 5_000;
+/** Optional read-only Magnus Control tools. The base URL and token come from the environment only. */
+export function registerMagnusControlTools(registry, env) {
+    registry.register(magnusFleetReadinessTool(env));
+    registry.register(magnusNodeDependencyImpactTool(env));
+    for (const tool of magnusOwnerReadTools(env))
+        registry.register(tool);
+    registry.register(defineTool({
+        name: 'magnus_fleet_inventory', description: 'Read bounded fleet inventory from the owning Magnus Control API. Observations do not authorize commands or remediation.',
+        input: z.object({}).strict(),
+        output: z.object({ source: z.string().url(), source_date: z.string().datetime().nullable(), observed_at: z.string().datetime(), nodes: z.array(z.object({ id: z.string(), name: z.string(), hostname: z.string().nullable(), status: z.string() }).strict()).max(100) }).strict(),
+        effect: 'read', contexts: ['direct', 'peer'], timeoutMs: 15_000,
+        handler: async (_input, signal) => {
+            const { value, source, sourceDate } = await readOwnedApi('ARDENT_MAGNUS_API_URL', 'ARDENT_MAGNUS_READ_TOKEN', '/api/v1/nodes', env, signal);
+            const nodes = z.array(node).max(100).parse(value);
+            return { source, source_date: sourceDate, observed_at: new Date().toISOString(), nodes: nodes.map(item => ({ id: item.id, name: item.name, hostname: item.hostname ?? null, status: item.status })) };
+        }
+    }));
+    registry.register(defineTool({
+        name: 'magnus_node_health', description: 'Read the latest retained Magnus health snapshot for one inventory node with an explicit freshness label. A stale snapshot is historical evidence, not current health. This does not authorize a node command.',
+        input: z.object({ node_id: id }).strict(),
+        output: z.object({ source: z.string().url(), source_date: z.string().datetime().nullable(), observed_at: z.string().datetime(), node_id: id,
+            snapshot_at: z.string().datetime().nullable(), snapshot_age_ms: z.number().int().nullable(),
+            snapshot_freshness: z.enum(['fresh', 'stale', 'future', 'missing']), freshness_limit_ms: z.literal(HEALTH_FRESHNESS_LIMIT_MS),
+            cpu_usage_percent: z.number().nullable(), memory_percent: z.number().nullable() }).strict(),
+        effect: 'read', contexts: ['direct', 'peer'], timeoutMs: 15_000,
+        handler: async ({ node_id }, signal) => {
+            const { value, source, sourceDate } = await readOwnedApi('ARDENT_MAGNUS_API_URL', 'ARDENT_MAGNUS_READ_TOKEN', `/api/v1/nodes/${node_id}/health`, env, signal);
+            const data = z.object({ nodeId: z.string().optional(), timestamp: z.string().datetime().optional(), cpuUsagePercent: z.number().nullable().optional(), memoryPercent: z.number().nullable().optional() }).passthrough().parse(value);
+            if (data.nodeId && data.nodeId !== node_id)
+                throw Object.assign(new Error('Health snapshot node identity differs from the request'), { code: 'SOURCE_IDENTITY_MISMATCH' });
+            const observedAt = Date.now();
+            const snapshotAgeMs = data.timestamp ? observedAt - Date.parse(data.timestamp) : null;
+            const snapshotFreshness = snapshotAgeMs === null ? 'missing' : snapshotAgeMs < -HEALTH_FUTURE_SKEW_MS ? 'future'
+                : snapshotAgeMs > HEALTH_FRESHNESS_LIMIT_MS ? 'stale' : 'fresh';
+            return { source, source_date: sourceDate, observed_at: new Date(observedAt).toISOString(), node_id,
+                snapshot_at: data.timestamp ?? null, snapshot_age_ms: snapshotAgeMs,
+                snapshot_freshness: snapshotFreshness, freshness_limit_ms: HEALTH_FRESHNESS_LIMIT_MS,
+                cpu_usage_percent: data.cpuUsagePercent ?? null, memory_percent: data.memoryPercent ?? null };
+        }
+    }));
+    registry.register(defineTool({
+        name: 'magnus_anomaly_summary', description: 'Read bounded active fleet anomaly counts and affected nodes from Magnus. This is an observation, not remediation authority.',
+        input: z.object({}).strict(),
+        output: z.object({ source: z.string().url(), source_date: z.string().datetime().nullable(), observed_at: z.string().datetime(),
+            total_active: count, by_severity: z.object({ info: count, warning: count, critical: count }).strict(),
+            nodes: z.array(z.object({ node_id: id, node_name: z.string().max(160), count, metrics: z.array(z.string().max(80)).max(16) }).strict()).max(100) }).strict(),
+        effect: 'read', contexts: ['direct', 'peer'], timeoutMs: 15_000,
+        handler: async (_input, signal) => {
+            const { value, source, sourceDate } = await readOwnedApi('ARDENT_MAGNUS_API_URL', 'ARDENT_MAGNUS_READ_TOKEN', '/api/v1/anomalies/summary', env, signal);
+            const data = anomalySummary.parse(value);
+            return { source, source_date: sourceDate, observed_at: new Date().toISOString(), total_active: data.totalActive,
+                by_severity: { info: data.bySeverity.info, warning: data.bySeverity.warning, critical: data.bySeverity.critical },
+                nodes: data.byNode.map(item => ({ node_id: item.nodeId, node_name: item.nodeName, count: item.count, metrics: item.metrics })) };
+        }
+    }));
+    registry.register(defineTool({
+        name: 'magnus_command_status', description: 'Read one Magnus command lifecycle status by exact ID. Command text, arguments, environment, and output are excluded.',
+        input: z.object({ command_id: id }).strict(),
+        output: z.object({ source: z.string().url(), source_date: z.string().datetime().nullable(), observed_at: z.string().datetime(),
+            command_id: id, node_id: id, status: commandStatus.shape.status,
+            created_at: z.string().datetime(), started_at: z.string().datetime().nullable(), completed_at: z.string().datetime().nullable(),
+            exit_code: z.number().int().nullable(), duration_ms: count.nullable(), result_truncated: z.boolean().nullable() }).strict(),
+        effect: 'read', contexts: ['direct', 'peer'], timeoutMs: 15_000,
+        handler: async ({ command_id }, signal) => {
+            const { value, source, sourceDate } = await readOwnedApi('ARDENT_MAGNUS_API_URL', 'ARDENT_MAGNUS_READ_TOKEN', `/api/v1/commands/${command_id}`, env, signal);
+            const data = commandStatus.parse(value);
+            if (data.id !== command_id)
+                throw Object.assign(new Error('Command identity differs from the request'), { code: 'SOURCE_IDENTITY_MISMATCH' });
+            return { source, source_date: sourceDate, observed_at: new Date().toISOString(), command_id: data.id, node_id: data.nodeId,
+                status: data.status, created_at: data.createdAt, started_at: data.startedAt, completed_at: data.completedAt,
+                exit_code: data.result?.exitCode ?? null, duration_ms: data.result?.durationMs ?? null, result_truncated: data.result?.truncated ?? null };
+        }
+    }));
+}

package/dist/magnus-node-dependency-impact.d.ts

@@ -0,0 +1 @@
+export declare function magnusNodeDependencyImpactTool(env: NodeJS.ProcessEnv): import("./tools.js").Tool;