operon-agents 0.1.0-alpha.0

package/dist/cron/session-store.d.ts

@@ -0,0 +1,14 @@
+import type { CronTask } from "./types.ts";
+export type SessionCronTaskInit = Omit<CronTask, "id" | "createdAt">;
+export declare class SessionCronStore {
+    private readonly tasks;
+    add(init: SessionCronTaskInit, nowMs: number): CronTask;
+    adopt(task: CronTask): void;
+    markFired(id: string, lastFiredAt: number): CronTask | undefined;
+    get(id: string): CronTask | undefined;
+    list(): readonly CronTask[];
+    remove(ids: readonly string[]): readonly string[];
+    clear(): void;
+    private generateUniqueId;
+}
+//# sourceMappingURL=session-store.d.ts.map

package/dist/cron/session-store.js

@@ -0,0 +1,50 @@
+import { randomBytes } from "node:crypto";
+const ID_REGEX = /^[0-9a-f]{8}$/;
+const MAX_ID_ATTEMPTS = 8;
+export class SessionCronStore {
+    tasks = new Map();
+    add(init, nowMs) {
+        const id = this.generateUniqueId();
+        const task = { ...init, id, createdAt: nowMs };
+        this.tasks.set(id, task);
+        return task;
+    }
+    adopt(task) {
+        this.tasks.set(task.id, task);
+    }
+    markFired(id, lastFiredAt) {
+        const existing = this.tasks.get(id);
+        if (existing === undefined)
+            return undefined;
+        const updated = { ...existing, lastFiredAt };
+        this.tasks.set(id, updated);
+        return updated;
+    }
+    get(id) {
+        return this.tasks.get(id);
+    }
+    list() {
+        return Array.from(this.tasks.values());
+    }
+    remove(ids) {
+        const removed = [];
+        for (const id of ids)
+            if (this.tasks.delete(id))
+                removed.push(id);
+        return removed;
+    }
+    clear() {
+        this.tasks.clear();
+    }
+    generateUniqueId() {
+        for (let attempt = 0; attempt < MAX_ID_ATTEMPTS; attempt++) {
+            const candidate = randomBytes(4).toString("hex");
+            if (!ID_REGEX.test(candidate))
+                continue;
+            if (!this.tasks.has(candidate))
+                return candidate;
+        }
+        throw new Error(`SessionCronStore: failed to generate a unique 8-hex id after ${MAX_ID_ATTEMPTS} attempts`);
+    }
+}
+//# sourceMappingURL=session-store.js.map

package/dist/cron/time-format.d.ts

@@ -0,0 +1,2 @@
+export declare function formatLocalIsoWithOffset(ms: number): string;
+//# sourceMappingURL=time-format.d.ts.map

package/dist/cron/time-format.js

@@ -0,0 +1,12 @@
+export function formatLocalIsoWithOffset(ms) {
+    const date = new Date(ms);
+    const offsetMin = -date.getTimezoneOffset();
+    const sign = offsetMin >= 0 ? "+" : "-";
+    const absOffset = Math.abs(offsetMin);
+    const offset = `${sign}${pad(Math.floor(absOffset / 60))}:${pad(absOffset % 60)}`;
+    return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}T${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}.${String(date.getMilliseconds()).padStart(3, "0")}${offset}`;
+}
+function pad(n) {
+    return String(n).padStart(2, "0");
+}
+//# sourceMappingURL=time-format.js.map

package/dist/cron/tools.d.ts

@@ -0,0 +1,7 @@
+import { type Tool } from "operon-agents-core";
+import type { CronManager } from "./manager.ts";
+export declare const MAX_CRON_JOBS_PER_SESSION = 50;
+export declare function cronCreateTool(manager: CronManager): Tool;
+export declare function cronDeleteTool(manager: CronManager): Tool;
+export declare function cronListTool(manager: CronManager): Tool;
+//# sourceMappingURL=tools.d.ts.map

package/dist/cron/tools.js

@@ -0,0 +1,161 @@
+import { z } from "zod";
+import { ToolAccesses, defineTool, globApproval } from "operon-agents-core";
+import { computeNextCronRun, cronToHuman, hasFireWithinYears, parseCronExpression, } from "./cron-expr.js";
+import { jitteredNextCronRunMs, oneShotJitteredNextCronRunMs } from "./jitter.js";
+import { formatLocalIsoWithOffset } from "./time-format.js";
+export const MAX_CRON_JOBS_PER_SESSION = 50;
+const MAX_PROMPT_BYTES = 8 * 1024;
+const ONE_SHOT_MAX_FUTURE_MS = 350 * 24 * 60 * 60 * 1000;
+const ID_PATTERN = /^[0-9a-f]{8}$/;
+const PROMPT_PREVIEW_BYTES = 200;
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+function text(s, isError = false) {
+    return { content: [{ type: "text", text: s }], isError };
+}
+export function cronCreateTool(manager) {
+    return defineTool({
+        name: "CronCreate",
+        description: 'Schedule a prompt to be re-injected into this session at a future time. `cron` is a 5-field local-time expression ("M H DoM Mon DoW"). recurring=true (default) fires on every match until deleted or auto-expired after 7 days; recurring=false fires once then auto-deletes.',
+        params: z.object({
+            cron: z.string().describe('5-field cron expression in local time, e.g. "*/5 * * * *" (every 5 min) or "30 14 28 2 *".'),
+            prompt: z.string().min(1).max(MAX_PROMPT_BYTES).describe("The prompt to enqueue at each fire time."),
+            recurring: z.boolean().optional().default(true).describe("true = repeat until deleted/expired; false = fire once."),
+        }),
+        resolve: (args) => {
+            const normalizedCron = args.cron.trim().split(/\s+/).join(" ");
+            let parsed;
+            try {
+                parsed = parseCronExpression(normalizedCron);
+            }
+            catch (err) {
+                return errorPlan("CronCreate", `Invalid cron expression: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            const nowAtPrepare = manager.clocks.wallNow();
+            if (!hasFireWithinYears(parsed, 5, nowAtPrepare)) {
+                return errorPlan("CronCreate", `Cron expression ${JSON.stringify(normalizedCron)} has no fire within 5 years; refusing to schedule.`);
+            }
+            if (manager.store.list().length >= MAX_CRON_JOBS_PER_SESSION) {
+                return errorPlan("CronCreate", `Cron job cap reached (max ${MAX_CRON_JOBS_PER_SESSION} per session).`);
+            }
+            const byteLen = Buffer.byteLength(args.prompt, "utf8");
+            if (byteLen > MAX_PROMPT_BYTES) {
+                return errorPlan("CronCreate", `Prompt exceeds ${MAX_PROMPT_BYTES} bytes (got ${byteLen}).`);
+            }
+            const recurring = args.recurring !== false;
+            if (!recurring) {
+                const firstFire = computeNextCronRun(parsed, nowAtPrepare);
+                if (firstFire !== null && firstFire - nowAtPrepare > ONE_SHOT_MAX_FUTURE_MS) {
+                    return errorPlan("CronCreate", `One-shot cron ${JSON.stringify(normalizedCron)} would not fire until ${formatLocalIsoWithOffset(firstFire)} (more than a year out). The pinned day/month has already passed this year — pick a future date or use wildcards.`);
+                }
+            }
+            return {
+                ...globApproval("CronCreate", JSON.stringify({ cron: normalizedCron, prompt: args.prompt, recurring })),
+                accesses: ToolAccesses.none(),
+                display: { title: recurring ? `Schedule cron ${normalizedCron}` : `Schedule one-shot ${normalizedCron}` },
+                run: async () => {
+                    const nowMs = manager.clocks.wallNow();
+                    if (manager.store.list().length >= MAX_CRON_JOBS_PER_SESSION) {
+                        return text(`Cron job cap reached (max ${MAX_CRON_JOBS_PER_SESSION} per session).`, true);
+                    }
+                    const task = manager.addTask({ cron: normalizedCron, prompt: args.prompt, recurring });
+                    const ideal = computeNextCronRun(parsed, nowMs);
+                    const nextFireAt = ideal === null ? null : recurring ? jitteredNextCronRunMs(task, parsed, ideal) : oneShotJitteredNextCronRunMs(task, ideal);
+                    return text([
+                        `id: ${task.id}`,
+                        `cron: ${normalizedCron}`,
+                        `humanSchedule: ${cronToHuman(parsed)}`,
+                        `recurring: ${String(recurring)}`,
+                        `nextFireAt: ${nextFireAt === null ? "null" : formatLocalIsoWithOffset(nextFireAt)}`,
+                    ].join("\n"));
+                },
+            };
+        },
+    });
+}
+export function cronDeleteTool(manager) {
+    return defineTool({
+        name: "CronDelete",
+        description: "Cancel a scheduled cron job by its 8-hex id (from CronCreate / CronList).",
+        params: z.object({ id: z.string().describe("The 8-hex cron job id.") }),
+        resolve: (args) => {
+            if (!ID_PATTERN.test(args.id)) {
+                return errorPlan("CronDelete", `Invalid cron job id ${JSON.stringify(args.id)} — must be 8 lowercase hex characters.`);
+            }
+            return {
+                ...globApproval("CronDelete", args.id),
+                accesses: ToolAccesses.none(),
+                display: { title: `Delete cron ${args.id}` },
+                run: async () => {
+                    const removed = manager.removeTasks([args.id]);
+                    if (removed.length === 0)
+                        return text(`No cron job with id ${args.id}.`, true);
+                    return text(`Deleted cron job ${args.id}.`);
+                },
+            };
+        },
+    });
+}
+function previewPrompt(prompt) {
+    const buf = Buffer.from(prompt, "utf8");
+    if (buf.byteLength <= PROMPT_PREVIEW_BYTES)
+        return prompt;
+    let end = PROMPT_PREVIEW_BYTES;
+    while (end > 0 && (buf[end] & 0b1100_0000) === 0b1000_0000)
+        end--;
+    return `${buf.subarray(0, end).toString("utf8")}…(truncated)`;
+}
+export function cronListTool(manager) {
+    return defineTool({
+        name: "CronList",
+        description: "List the cron jobs scheduled in this session (id, expression, human schedule, next fire, recurring, age, stale).",
+        params: z.object({}),
+        resolve: () => ({
+            ...globApproval("CronList", "list"),
+            accesses: ToolAccesses.none(),
+            display: { title: "List cron jobs" },
+            run: async () => {
+                const tasks = manager.store.list();
+                const nowMs = manager.clocks.wallNow();
+                const header = `cron_jobs: ${tasks.length}`;
+                if (tasks.length === 0)
+                    return text(`${header}\nNo cron jobs scheduled.`);
+                return text(`${header}\n${tasks.map((t) => renderRecord(manager, t, nowMs)).join("\n---\n")}`);
+            },
+        }),
+    });
+}
+function renderRecord(manager, task, nowMs) {
+    const recurring = task.recurring !== false;
+    const ageMs = nowMs - task.createdAt;
+    const ageDays = Number.isFinite(ageMs) ? ageMs / MS_PER_DAY : 0;
+    const stale = manager.isStale(task);
+    let humanSchedule = task.cron;
+    let nextFireAtIso = "null";
+    try {
+        humanSchedule = cronToHuman(parseCronExpression(task.cron));
+        const nextFireMs = manager.getNextFireForTask(task.id);
+        if (nextFireMs !== null)
+            nextFireAtIso = formatLocalIsoWithOffset(nextFireMs);
+    }
+    catch {
+        /* malformed cron — leave raw + null */
+    }
+    return [
+        `id: ${task.id}`,
+        `cron: ${task.cron}`,
+        `humanSchedule: ${humanSchedule}`,
+        `prompt: ${JSON.stringify(previewPrompt(task.prompt))}`,
+        `nextFireAt: ${nextFireAtIso}`,
+        `recurring: ${String(recurring)}`,
+        `ageDays: ${ageDays.toFixed(2)}`,
+        `stale: ${String(stale)}`,
+    ].join("\n");
+}
+function errorPlan(tool, message) {
+    return {
+        approvalRule: tool,
+        accesses: ToolAccesses.none(),
+        run: async () => text(message, true),
+    };
+}
+//# sourceMappingURL=tools.js.map

package/dist/cron/types.d.ts

@@ -0,0 +1,9 @@
+export interface CronTask {
+    readonly id: string;
+    readonly cron: string;
+    readonly prompt: string;
+    readonly createdAt: number;
+    readonly recurring?: boolean;
+    readonly lastFiredAt?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/cron/types.js

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

package/dist/extensions/index.d.ts

@@ -0,0 +1,23 @@
+import type { Capability } from "operon-agents-core";
+import type { ExtensionDefinition, ExtensionHost } from "./types.ts";
+export { ExtensionRuntime } from "./runtime.ts";
+export { ExtensionLoader, createExtensionLoader } from "./loader.ts";
+export { ServiceRegistry, ServiceUnavailableError, deadServiceHandle } from "./services.ts";
+export { HarnessExtensionManager, stageDefinition } from "./manager.ts";
+export type { ExtensionHostBridge, StagingOptions, HeldSession, StagedDefinition } from "./manager.ts";
+export type { ServiceOptions, ServiceUnavailableReason } from "./services.ts";
+export type { ExtensionManifest, ExtensionFileState, ExtensionFileStatus, ExtensionAttachTarget } from "./loader.ts";
+export type { ExtensionActions, ExtensionAPI, ExtensionCommand, ExtensionCommandResult, ExtensionRecordEntry, ExtensionSteerOptions, ExtensionDefinition, ExtensionHostContext, ExtensionEventContext, ExtensionEventMap, ExtensionEventName, ExtensionHandler, ExtensionHost, ExtensionModelRequestEvent, ExtensionModelRequestResult, ExtensionModelResponseEvent, ExtensionResultMap, ExtensionRunSettledEvent, ExtensionRunSettledResult, ExtensionRunStartEvent, ExtensionRunStartResult, ExtensionSessionContext, ExtensionSetupContext, ExtensionSessionEndEvent, ExtensionSessionStartEvent, ExtensionState, ExtensionToolSpec, ExtensionStepEndEvent, ExtensionStepEndResult, ExtensionStepStartEvent, ExtensionStepStartResult, ExtensionToolAuthorizeEvent, ExtensionToolAuthorizeResult, ExtensionToolCallEvent, ExtensionToolCallResult, ExtensionToolResultEvent, ExtensionCompactionBeforeEvent, ExtensionCompactionBeforeResult, ExtensionProviderHeadersEvent, ExtensionProviderHeadersResult, ExtensionProviderPayloadEvent, ExtensionProviderPayloadResult, ExtensionProviderResponseEvent, ProviderHeaders, HarnessSessionHandle, ModelProvider, SessionEndReason, SessionStartReason, } from "./types.ts";
+/**
+ * Build one isolated, session-scoped runtime for programmatic extensions.
+ *
+ * Every decision point in the extension contract is a `LoopHooks` slot — that is the only
+ * channel where a handler's return value can reach the loop. Observation does NOT come through
+ * here: observation goes through `api.onEvent`, which passes the session's event stream straight
+ * through (with fault isolation and teardown), rather than through this hook table.
+ */
+export declare function extensionsCapability(definitions: readonly ExtensionDefinition[], options?: {
+    readonly host?: ExtensionHost;
+    readonly params?: Readonly<Record<string, unknown>>;
+}): Capability;
+//# sourceMappingURL=index.d.ts.map

package/dist/extensions/index.js

@@ -0,0 +1,41 @@
+import { ExtensionRuntime } from "./runtime.js";
+export { ExtensionRuntime } from "./runtime.js";
+export { ExtensionLoader, createExtensionLoader } from "./loader.js";
+export { ServiceRegistry, ServiceUnavailableError, deadServiceHandle } from "./services.js";
+export { HarnessExtensionManager, stageDefinition } from "./manager.js";
+/**
+ * Build one isolated, session-scoped runtime for programmatic extensions.
+ *
+ * Every decision point in the extension contract is a `LoopHooks` slot — that is the only
+ * channel where a handler's return value can reach the loop. Observation does NOT come through
+ * here: observation goes through `api.onEvent`, which passes the session's event stream straight
+ * through (with fault isolation and teardown), rather than through this hook table.
+ */
+export function extensionsCapability(definitions, options = {}) {
+    const runtime = new ExtensionRuntime(definitions, options.host, options.params);
+    return {
+        name: "extensions",
+        service: runtime,
+        toolProviders: [{ id: "extensions", listTools: () => runtime.listTools() }],
+        toolFilters: [runtime.filterTools],
+        gates: { compaction: runtime.compactionGate },
+        // Stable array reference — `setup` (openSession) fills it before any run assembles.
+        injectors: runtime.listInjectors(),
+        hooks: {
+            beforeRun: async (ctx) => runtime.beforeRun(ctx, ctx.input),
+            beforeStep: async (ctx) => runtime.beforeStep(ctx, ctx.context, ctx.system),
+            afterStep: async (ctx) => runtime.afterStep(ctx, ctx.context, ctx.usage, ctx.stopReason),
+            shouldContinueAfterStop: async (ctx) => runtime.runSettled(ctx, ctx.usage, ctx.stopReason),
+            beforeModelRequest: async (ctx) => runtime.beforeModelRequest(ctx, ctx.request, ctx.context),
+            afterModelResponse: async (ctx) => runtime.afterModelResponse(ctx, ctx.request, ctx.response, ctx.context),
+            prepareToolExecution: async (ctx) => runtime.beforeToolCall(ctx, ctx.toolCall.name, ctx.toolCall.id, ctx.tool, ctx.args),
+            authorizeToolExecution: async (ctx) => runtime.authorizeToolCall(ctx, ctx.toolCall.name, ctx.toolCall.id, ctx.tool, ctx.args, ctx.plan),
+            finalizeToolResult: async (ctx) => runtime.afterToolResult(ctx, ctx.toolCall.name, ctx.toolCall.id, ctx.tool, ctx.args, ctx.result),
+        },
+        openSession: (ctx) => runtime.open(ctx),
+        closeSession: () => runtime.close(),
+        start: (ctx) => runtime.attachRun(ctx),
+        stop: () => runtime.detachRun(),
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/extensions/loader.d.ts

@@ -0,0 +1,121 @@
+import type { ExtensionDefinition } from "./types.ts";
+/** The slice of a session the loader swaps extensions on — `HarnessSession` satisfies it. */
+export interface ExtensionAttachTarget {
+    attachExtension(definition: ExtensionDefinition): Promise<void>;
+    detachExtension(extensionId: string): Promise<void>;
+}
+/**
+ * File-extension loader — the shell that turns a extension directory into extension VALUES for
+ * `attachExtension`. The framework core stays file-blind: everything here ends in a plain
+ * `ExtensionDefinition`, handed over the same channel host-authored extensions use.
+ *
+ * Layout: one folder per extension under `directory`, holding a `manifest.json` plus a bundled
+ * entry file (dependencies baked in by the author at publish time — no install step here).
+ *
+ * Trust model — loading is consent, and consent is MANUAL:
+ * - `load()` / `reload()` are explicit host actions; performing one approves the extension at
+ *   its current file mtime, recorded in `.approvals.json` beside the extensions.
+ * - `loadApproved()` (startup) only honors extensions whose entry is byte-for-byte the one
+ *   approved (mtime match). A changed or new extension is reported, never silently loaded —
+ *   an agent with write access must not be able to plant code that runs on next open.
+ *
+ * Reload mechanics: native `import()` with a `?v=<mtime>` suffix — a changed file gets a
+ * fresh module, an unchanged one hits the cache. Old module instances stay resident until
+ * process exit; that is the accepted cost of not restarting.
+ */
+/** This framework's version — what a manifest's `engine` is checked against. */
+export declare const FRAMEWORK_VERSION: string;
+/** Semver ordering for plain `x.y.z[-pre]` strings (a prerelease sorts below its release). */
+export declare function compareVersions(a: string, b: string): number;
+/**
+ * What must be known about an extension BEFORE its code is imported — find it (`id`), import
+ * it (`entry`, gated by `engine`), show it (`version`, `name`, `description`) — and nothing more. What the
+ * extension provides (`create`) and consumes (`uses`) lives on the definition it exports, the
+ * same on both channels. Only `id` is validated; unknown fields pass through untouched, so a
+ * manifest written for a newer loader still loads here.
+ */
+export interface ExtensionManifest {
+    readonly id: string;
+    readonly version?: string;
+    /** Entry file relative to the extension folder. Default: "index.js". */
+    readonly entry?: string;
+    /** The lowest framework version this bundle was built for (`x.y.z[-pre]`). Checked BEFORE the
+     *  import: an older host lists the extension as `error` and refuses to load it, instead of
+     *  importing code written against an API it does not have. */
+    readonly engine?: string;
+    /** Display name for listings (falls back to `id` in UIs). */
+    readonly name?: string;
+    /** One line for listings. */
+    readonly description?: string;
+}
+export type ExtensionFileState = 
+/** Approved at the current mtime and produced a definition this loader holds. */
+"loaded"
+/** Approved at the current mtime but not imported yet (call `loadApproved` or `load`). */
+ | "approved"
+/** Never approved. Loads only through an explicit `load()`. */
+ | "new"
+/** Approved before, but the entry file changed since. Loads only through `reload()`. */
+ | "changed"
+/** Folder present but unusable (bad manifest, missing entry). */
+ | "error";
+export interface ExtensionFileStatus {
+    readonly id: string;
+    readonly dir: string;
+    readonly state: ExtensionFileState;
+    readonly version?: string;
+    readonly engine?: string;
+    readonly name?: string;
+    readonly description?: string;
+    readonly error?: string;
+}
+export declare class ExtensionLoader {
+    private readonly directory;
+    private readonly approvalsPath;
+    /** Live definitions by extension id — the values a host hands to `attachExtension`. */
+    private readonly loaded;
+    constructor(options: {
+        readonly directory: string;
+    });
+    /** The parsed manifest of one extension, by id. */
+    manifest(id: string): Promise<ExtensionManifest>;
+    /** The folder a extension lives in — where an extension keeps its data files. */
+    manifestDir(id: string): Promise<string>;
+    /** Every extension folder under the directory, with its trust/load state. */
+    list(): Promise<ExtensionFileStatus[]>;
+    /**
+     * Import one extension and approve it as it stands. The call itself is the consent — reserve
+     * it for user-initiated actions, never for something an agent triggers on its own.
+     */
+    load(id: string): Promise<ExtensionDefinition>;
+    /** Re-import after an edit and roll the approval forward to the file as it is now. */
+    reload(id: string): Promise<ExtensionDefinition>;
+    /** Forget a extension: drop the held definition and revoke its approval. */
+    unload(id: string): Promise<void>;
+    /**
+     * Startup path: import every extension still byte-identical to what was approved. Changed and
+     * new extensions are skipped and reported so the host can surface them for a manual decision.
+     */
+    loadApproved(): Promise<{
+        loaded: ExtensionDefinition[];
+        skipped: ExtensionFileStatus[];
+    }>;
+    /** The definitions currently held. On the standalone-loader path these reach sessions through
+     *  `attachExtension`/`reloadInto`; a harness built with `extensionDir` registers them itself
+     *  (`harness.extensions.load`), which is the path that also runs `create` halves. */
+    definitions(): ExtensionDefinition[];
+    /** Convenience: reload a extension and swap it on a live session (detach old, attach new). */
+    reloadInto(session: ExtensionAttachTarget, id: string): Promise<ExtensionDefinition>;
+    private readExtensionDirs;
+    private scan;
+    private find;
+    private stateOf;
+    private importDefinition;
+    private approve;
+    private readApprovals;
+    private writeApprovals;
+}
+export declare function createExtensionLoader(options: {
+    readonly directory: string;
+}): ExtensionLoader;
+//# sourceMappingURL=loader.d.ts.map