@cogenta/agents 0.1.0

package/dist/tools/types.d.ts

@@ -0,0 +1,51 @@
+import type { z } from 'zod';
+export type ToolCost = 'low' | 'medium' | 'high';
+export interface ToolLogger {
+    info(message: string, fields?: Readonly<Record<string, unknown>>): void;
+    warn(message: string, fields?: Readonly<Record<string, unknown>>): void;
+    error(message: string, fields?: Readonly<Record<string, unknown>>): void;
+}
+/**
+ * What `execute`/`revert` receive — Contract C's `ctx.site`, `ctx.actor`,
+ * `ctx.logger` (`ctx.db` and other resource clients are added by task 5's
+ * concrete core tools, which are the first to actually need one; this stays
+ * the minimal shape every tool can rely on regardless of what it does).
+ */
+export interface ToolContext {
+    /** Mirrors `ResolvedConfig.site` (`@cogenta/core`'s config resolver) — the same shape, read-only from a tool's perspective. */
+    readonly site: {
+        readonly name: string;
+        readonly url?: string;
+        readonly locales: readonly string[];
+        readonly defaultLocale: string;
+    };
+    readonly actor: {
+        readonly id: string | null;
+        readonly roles: readonly string[];
+    };
+    readonly logger: ToolLogger;
+    /** The run's cancellation signal — set per call by the manifest, never by the tool definition itself. */
+    readonly signal: AbortSignal;
+}
+/**
+ * Contract C (`tools@1.0`, ADR-0020), reproduced as a type — this shape is
+ * frozen and any change to it is a major version with a migration note, not
+ * a routine edit.
+ */
+export interface ToolDefinition<Input = unknown, Output = unknown> {
+    readonly name: string;
+    readonly version: string;
+    readonly description: string;
+    readonly input: z.ZodType<Input>;
+    readonly output: z.ZodType<Output>;
+    readonly permissions: readonly string[];
+    readonly sideEffects: boolean;
+    readonly reversible: boolean;
+    readonly cost: ToolCost;
+    readonly rateLimit?: {
+        readonly perHour: number;
+    };
+    execute(input: Input, ctx: ToolContext): Promise<Output>;
+    revert?(receipt: Output, ctx: ToolContext): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/tools/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/tools/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAE5B,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAA;AAEhD,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,IAAI,CAAA;IACvE,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,IAAI,CAAA;IACvE,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,IAAI,CAAA;CACzE;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,+HAA+H;IAC/H,QAAQ,CAAC,IAAI,EAAE;QACb,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;QACrB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;QACrB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;QACnC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;KAC/B,CAAA;IACD,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,CAAA;IACjF,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;IAC3B,yGAAyG;IACzG,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;CAC7B;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc,CAAC,KAAK,GAAG,OAAO,EAAE,MAAM,GAAG,OAAO;IAC/D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;IAChC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;IAClC,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;IACvC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAA;IAC7B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAC5B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,QAAQ,CAAC,SAAS,CAAC,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;IACjD,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACxD,MAAM,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1D"}

package/dist/tools/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/tools/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/tools/types.ts"],"names":[],"mappings":""}

package/dist/trace/capture.d.ts

@@ -0,0 +1,19 @@
+import type { RunResult } from '../runtime/types.js';
+import type { TraceStore } from './types.js';
+export interface CaptureTraceOptions {
+    readonly agentName: string;
+    readonly store: TraceStore;
+    /** Fraction of runs actually persisted, `0..1` (default `1` — capture everything). The sampling half of "rétention et échantillonnage configurables dès le départ". */
+    readonly sampleRate?: number;
+    readonly random?: () => number;
+    readonly now?: () => number;
+    readonly newId?: () => string;
+}
+/**
+ * Wraps a call to `runAgentLoop` (or anything returning a `RunResult`) and,
+ * unless sampling skips it, persists the run as a `Trace`. The run's own
+ * result is always returned unchanged — capture is an observer, never a
+ * condition for the run succeeding or failing.
+ */
+export declare function captureTrace(run: () => Promise<RunResult>, options: CaptureTraceOptions): Promise<RunResult>;
+//# sourceMappingURL=capture.d.ts.map

package/dist/trace/capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture.d.ts","sourceRoot":"","sources":["../../src/trace/capture.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,KAAK,EAAS,UAAU,EAAE,MAAM,YAAY,CAAA;AAEnD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;IAC1B,uKAAuK;IACvK,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,MAAM,CAAA;IAC9B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,MAAM,CAAA;CAC9B;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,MAAM,OAAO,CAAC,SAAS,CAAC,EAC7B,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,SAAS,CAAC,CAyBpB"}

package/dist/trace/capture.js

@@ -0,0 +1,31 @@
+import { newId } from '@cogenta/core';
+/**
+ * Wraps a call to `runAgentLoop` (or anything returning a `RunResult`) and,
+ * unless sampling skips it, persists the run as a `Trace`. The run's own
+ * result is always returned unchanged — capture is an observer, never a
+ * condition for the run succeeding or failing.
+ */
+export async function captureTrace(run, options) {
+    const now = options.now ?? Date.now;
+    const random = options.random ?? Math.random;
+    const sampleRate = options.sampleRate ?? 1;
+    const generateId = options.newId ?? newId;
+    const startedAt = now();
+    const result = await run();
+    const finishedAt = now();
+    if (random() < sampleRate) {
+        const trace = {
+            id: generateId(),
+            agentName: options.agentName,
+            startedAt: new Date(startedAt).toISOString(),
+            finishedAt: new Date(finishedAt).toISOString(),
+            stopReason: result.stopReason,
+            usage: result.usage,
+            steps: result.steps,
+            messages: result.messages,
+        };
+        await options.store.save(trace);
+    }
+    return result;
+}
+//# sourceMappingURL=capture.js.map

package/dist/trace/capture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture.js","sourceRoot":"","sources":["../../src/trace/capture.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAcrC;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,GAA6B,EAC7B,OAA4B;IAE5B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAA;IACnC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAA;IAC5C,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,CAAC,CAAA;IAC1C,MAAM,UAAU,GAAG,OAAO,CAAC,KAAK,IAAI,KAAK,CAAA;IAEzC,MAAM,SAAS,GAAG,GAAG,EAAE,CAAA;IACvB,MAAM,MAAM,GAAG,MAAM,GAAG,EAAE,CAAA;IAC1B,MAAM,UAAU,GAAG,GAAG,EAAE,CAAA;IAExB,IAAI,MAAM,EAAE,GAAG,UAAU,EAAE,CAAC;QAC1B,MAAM,KAAK,GAAU;YACnB,EAAE,EAAE,UAAU,EAAE;YAChB,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,SAAS,EAAE,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE;YAC5C,UAAU,EAAE,IAAI,IAAI,CAAC,UAAU,CAAC,CAAC,WAAW,EAAE;YAC9C,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,QAAQ,EAAE,MAAM,CAAC,QAAQ;SAC1B,CAAA;QACD,MAAM,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IACjC,CAAC;IAED,OAAO,MAAM,CAAA;AACf,CAAC"}

package/dist/trace/file-store.d.ts

@@ -0,0 +1,12 @@
+import type { TraceStore } from './types.js';
+/**
+ * Durable without any external service — one JSON file per trace under
+ * `options.dir`, the same "real but local" tier `sqlite`/local storage
+ * already use elsewhere in this project (rule R1). Not meant for high
+ * concurrency or large-scale querying: this is a debugging/replay archive,
+ * not a database.
+ */
+export declare function createFileTraceStore(options: {
+    readonly dir: string;
+}): TraceStore;
+//# sourceMappingURL=file-store.d.ts.map

package/dist/trace/file-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-store.d.ts","sourceRoot":"","sources":["../../src/trace/file-store.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAqB,UAAU,EAAE,MAAM,YAAY,CAAA;AAQ/D;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,UAAU,CA0DlF"}

package/dist/trace/file-store.js

@@ -0,0 +1,78 @@
+import { mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { CogentaError } from '@cogenta/core';
+const DEFAULT_LIST_LIMIT = 100;
+function fileFor(dir, id) {
+    return join(dir, `${id}.json`);
+}
+/**
+ * Durable without any external service — one JSON file per trace under
+ * `options.dir`, the same "real but local" tier `sqlite`/local storage
+ * already use elsewhere in this project (rule R1). Not meant for high
+ * concurrency or large-scale querying: this is a debugging/replay archive,
+ * not a database.
+ */
+export function createFileTraceStore(options) {
+    const ready = mkdir(options.dir, { recursive: true });
+    async function readTrace(path) {
+        try {
+            const raw = await readFile(path, 'utf8');
+            return JSON.parse(raw);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return null;
+            throw new CogentaError({
+                code: 'INTERNAL',
+                message: `Could not read trace file "${path}".`,
+                hint: 'The file may be corrupted; consider removing it.',
+                cause: error,
+            });
+        }
+    }
+    return {
+        async save(trace) {
+            await ready;
+            await writeFile(fileFor(options.dir, trace.id), JSON.stringify(trace), 'utf8');
+        },
+        async get(id) {
+            await ready;
+            return readTrace(fileFor(options.dir, id));
+        },
+        async list(query = {}) {
+            await ready;
+            const filenames = await readdir(options.dir).catch(() => []);
+            const traces = [];
+            for (const filename of filenames) {
+                if (!filename.endsWith('.json'))
+                    continue;
+                const trace = await readTrace(join(options.dir, filename));
+                if (trace === null)
+                    continue;
+                if (query.agentName !== undefined && trace.agentName !== query.agentName)
+                    continue;
+                traces.push(trace);
+            }
+            traces.sort((a, b) => b.startedAt.localeCompare(a.startedAt));
+            return traces.slice(0, query.limit ?? DEFAULT_LIST_LIMIT);
+        },
+        async prune(olderThanMs, now = Date.now) {
+            await ready;
+            const cutoff = now() - olderThanMs;
+            const filenames = await readdir(options.dir).catch(() => []);
+            let removed = 0;
+            for (const filename of filenames) {
+                if (!filename.endsWith('.json'))
+                    continue;
+                const path = join(options.dir, filename);
+                const trace = await readTrace(path);
+                if (trace !== null && new Date(trace.startedAt).getTime() < cutoff) {
+                    await rm(path);
+                    removed += 1;
+                }
+            }
+            return removed;
+        },
+    };
+}
+//# sourceMappingURL=file-store.js.map

package/dist/trace/file-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-store.js","sourceRoot":"","sources":["../../src/trace/file-store.ts"],"names":[],"mappings":"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"}

package/dist/trace/memory-store.d.ts

@@ -0,0 +1,9 @@
+import type { TraceStore } from './types.js';
+/**
+ * The always-available tier (rule R1's "at least one implementation with no
+ * external service") — every process has memory, nothing to configure.
+ * Traces do not survive a restart, which is exactly why `createFileTraceStore`
+ * exists for anything that needs them to.
+ */
+export declare function createMemoryTraceStore(): TraceStore;
+//# sourceMappingURL=memory-store.d.ts.map

package/dist/trace/memory-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-store.d.ts","sourceRoot":"","sources":["../../src/trace/memory-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAqB,UAAU,EAAE,MAAM,YAAY,CAAA;AAI/D;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,UAAU,CA4BnD"}

package/dist/trace/memory-store.js

@@ -0,0 +1,36 @@
+const DEFAULT_LIST_LIMIT = 100;
+/**
+ * The always-available tier (rule R1's "at least one implementation with no
+ * external service") — every process has memory, nothing to configure.
+ * Traces do not survive a restart, which is exactly why `createFileTraceStore`
+ * exists for anything that needs them to.
+ */
+export function createMemoryTraceStore() {
+    const traces = new Map();
+    return {
+        async save(trace) {
+            traces.set(trace.id, trace);
+        },
+        async get(id) {
+            return traces.get(id) ?? null;
+        },
+        async list(query = {}) {
+            const all = [...traces.values()]
+                .filter((trace) => query.agentName === undefined || trace.agentName === query.agentName)
+                .sort((a, b) => b.startedAt.localeCompare(a.startedAt));
+            return all.slice(0, query.limit ?? DEFAULT_LIST_LIMIT);
+        },
+        async prune(olderThanMs, now = Date.now) {
+            const cutoff = now() - olderThanMs;
+            let removed = 0;
+            for (const trace of traces.values()) {
+                if (new Date(trace.startedAt).getTime() < cutoff) {
+                    traces.delete(trace.id);
+                    removed += 1;
+                }
+            }
+            return removed;
+        },
+    };
+}
+//# sourceMappingURL=memory-store.js.map

package/dist/trace/memory-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-store.js","sourceRoot":"","sources":["../../src/trace/memory-store.ts"],"names":[],"mappings":"AAEA,MAAM,kBAAkB,GAAG,GAAG,CAAA;AAE9B;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB;IACpC,MAAM,MAAM,GAAG,IAAI,GAAG,EAAiB,CAAA;IAEvC,OAAO;QACL,KAAK,CAAC,IAAI,CAAC,KAAK;YACd,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,CAAA;QAC7B,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,EAAE;YACV,OAAO,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,IAAI,CAAA;QAC/B,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,KAAK,GAAe,EAAE;YAC/B,MAAM,GAAG,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC;iBAC7B,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,SAAS,KAAK,SAAS,IAAI,KAAK,CAAC,SAAS,KAAK,KAAK,CAAC,SAAS,CAAC;iBACvF,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAA;YACzD,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,KAAK,IAAI,kBAAkB,CAAC,CAAA;QACxD,CAAC;QACD,KAAK,CAAC,KAAK,CAAC,WAAW,EAAE,GAAG,GAAG,IAAI,CAAC,GAAG;YACrC,MAAM,MAAM,GAAG,GAAG,EAAE,GAAG,WAAW,CAAA;YAClC,IAAI,OAAO,GAAG,CAAC,CAAA;YACf,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC;gBACpC,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,GAAG,MAAM,EAAE,CAAC;oBACjD,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;oBACvB,OAAO,IAAI,CAAC,CAAA;gBACd,CAAC;YACH,CAAC;YACD,OAAO,OAAO,CAAA;QAChB,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/trace/types.d.ts

@@ -0,0 +1,37 @@
+import type { ChatMessage, TokenUsage } from '../providers/types.js';
+import type { RunStopReason, StepRecord } from '../runtime/types.js';
+/**
+ * L4 task 7: a full record of one agent run, enough to inspect what
+ * happened and, later, to replay it (task 20's evaluation harness). Nothing
+ * here is new data — `runAgentLoop`'s own `RunResult` already carries every
+ * step, message, and usage figure; a trace is that result, timestamped and
+ * given an id worth storing.
+ */
+export interface Trace {
+    readonly id: string;
+    readonly agentName: string;
+    readonly startedAt: string;
+    readonly finishedAt: string;
+    readonly stopReason: RunStopReason;
+    readonly usage: TokenUsage;
+    readonly steps: readonly StepRecord[];
+    readonly messages: readonly ChatMessage[];
+}
+export interface TraceQuery {
+    readonly agentName?: string;
+    /** Most recent first; caps how many `list` returns (default implementation-defined, but never unbounded). */
+    readonly limit?: number;
+}
+export interface TraceStore {
+    save(trace: Trace): Promise<void>;
+    get(id: string): Promise<Trace | null>;
+    list(query?: TraceQuery): Promise<readonly Trace[]>;
+    /**
+     * The retention half of "rétention et échantillonnage configurables dès
+     * le départ" (L4's own pitfalls list, on trace volume) — removes every
+     * trace whose `startedAt` is older than `olderThanMs` ago, returns how
+     * many were removed.
+     */
+    prune(olderThanMs: number, now?: () => number): Promise<number>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/trace/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/trace/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AACpE,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAEpE;;;;;;GAMG;AACH,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAA;IAClC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;IAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,CAAA;IACrC,QAAQ,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,CAAA;CAC1C;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,6GAA6G;IAC7G,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACjC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,CAAA;IACtC,IAAI,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,KAAK,EAAE,CAAC,CAAA;IACnD;;;;;OAKG;IACH,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;CAChE"}

package/dist/trace/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/trace/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/trace/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@cogenta/agents",
+  "version": "0.1.0",
+  "description": "The agentic runtime: LLM provider abstraction, tool-calling, execution loop, permissions, memory, budgets, audit.",
+  "license": "MPL-2.0",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.11.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cogenta-cms/cogenta.git",
+    "directory": "packages/agents"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.typecheck.json",
+    "test": "vitest run --passWithNoTests",
+    "test:integration": "vitest run --config vitest.integration.config.ts --passWithNoTests"
+  },
+  "dependencies": {
+    "@cogenta/core": "workspace:*",
+    "@cogenta/render": "workspace:*",
+    "zod": "catalog:"
+  },
+  "devDependencies": {
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  }
+}