https://hypervize.tech/api/chronos

$0.01 Chronos fee
+ catalog price of every tool step that runs
+ token pricing for every model step

Authorization: Bearer hvz_live_…

// chronos-client.js
const BASE = "https://hypervize.tech/api/chronos";

/**
 * @param {string} apiKey  Hypervize key (hvz_…)
 */
export function createChronosClient(apiKey) {
  if (!apiKey) throw new Error("HVZ_KEY required");

  async function request(method, path, body) {
    const res = await fetch(`${BASE}${path}`, {
      method,
      headers: {
        Authorization: `Bearer ${apiKey}`,
        ...(body != null ? { "Content-Type": "application/json" } : {}),
      },
      body: body != null ? JSON.stringify(body) : undefined,
    });

    const data = await res.json().catch(() => ({}));
    if (!res.ok) {
      const err = new Error(
        data.error || data.message || `Chronos HTTP ${res.status}`,
      );
      err.status = res.status;
      err.code = data.code;
      err.body = data;
      throw err;
    }
    return data;
  }

  return {
    /** Create job + recipe from ordered events (preferred). */
    createJobFromEvents: (body) => request("POST", "/jobs", body),

    /** List jobs for this account. */
    listJobs: () => request("GET", "/jobs"),

    /** Job detail. */
    getJob: (jobId) => request("GET", `/jobs/${jobId}`),

    /** Update name, enabled, schedule, and/or timezone. */
    updateJob: (jobId, patch) => request("PATCH", `/jobs/${jobId}`, patch),

    /** Delete a job. */
    deleteJob: (jobId) => request("DELETE", `/jobs/${jobId}`),

    /** Billable immediate run. Returns { runId, status, error_summary? }. */
    runNow: (jobId) => request("POST", `/jobs/${jobId}/run-now`),

    /** Recent runs for a job (limit 1–50, default 20). */
    listRuns: (jobId, limit = 20) =>
      request("GET", `/jobs/${jobId}/runs?limit=${limit}`),

    /** Single run detail (step results, status, previews). */
    getRun: (runId) => request("GET", `/runs/${runId}`),

    /**
     * Preview capture (default) or persist a recipe without a schedule.
     * Body: { events } or { toolCalls }; set persist: true + name to save.
     */
    capture: (body) => request("POST", "/capture", body),

    listRecipes: () => request("GET", "/recipes"),

    /** Create recipe from explicit steps[]. */
    createRecipe: (body) => request("POST", "/recipes", body),

    /** Attach an existing recipe to a new schedule. */
    createJobFromRecipe: (body) => request("POST", "/jobs", body),
  };
}

export HVZ_KEY="hvz_live_…"

import { createChronosClient } from "./chronos-client.js";

const chronos = createChronosClient(process.env.HVZ_KEY);

import { createChronosClient } from "./chronos-client.js";

const chronos = createChronosClient(process.env.HVZ_KEY);

const { job, recipe, bindingSuggestions } = await chronos.createJobFromEvents({
  name: "weekday-digest",
  timezone: "America/Chicago",
  // omit enabled or set true; false keeps the job paused
  enabled: true,
  schedule: {
    kind: "weekly_times",
    days: ["MON", "TUE", "WED", "THU", "FRI"],
    time: "08:30", // local wall clock HH:mm (24h)
  },
  // Ordered steps — this is the entire recipe
  events: [
    {
      kind: "tool",
      // optional stable id (auto step_0, step_1, … if omitted)
      id: "cal",
      name: "pandora_list_calendar_events",
      arguments: {
        // Absolute ISO is rewritten → {{run.day_start_iso}} at capture time
        time_min: "2026-01-01T00:00:00.000Z",
        max_results: 25,
      },
    },
    {
      kind: "tool",
      id: "mail",
      name: "pandora_search_gmail",
      arguments: {
        query: "is:unread newer_than:1d",
        max_results: 10,
      },
    },
    {
      kind: "tool",
      id: "news",
      name: "vesper",
      arguments: {
        query: "top world and business news last 24 hours",
        num_results: 5,
        instructions: "List title, url, one-line summary for each.",
      },
    },
    {
      kind: "model",
      id: "compose",
      // Instruction for the model each fire; prior tool results are in context
      user_instruction:
        "Write a short HTML briefing for an executive: calendar, inbox, news. Be concise.",
    },
    {
      kind: "tool",
      id: "send",
      name: "herald",
      arguments: {
        format: "html",
        subject: "Digest — {{run.local_date}}",
        // Wire model output into delivery
        body: "{{steps.compose.result}}",
      },
    },
  ],
});

console.log("job id:", job.id);
console.log("recipe id:", recipe.id);
console.log("next_run_at:", job.next_run_at);
console.log("temporal rewrites:", bindingSuggestions);
// e.g. time_min → {{run.day_start_iso}}

// … after compose model step …
{
  kind: "tool",
  id: "file",
  name: "ledger",
  arguments: {
    action: "create",
    format: "pdf",
    title: "Digest — {{run.local_date}}",
    content: "{{steps.compose.result}}",
    filename: "digest.pdf",
  },
},
// Herald step: short email body; attach the Library file when you have its file_id
// (from a prior Chat capture or Ledger result). See Platform Tools → Ledger + Herald.

const { job } = await chronos.createJobFromEvents({
  name: "hourly-time-ping",
  timezone: "UTC",
  schedule: {
    kind: "cron",
    expr: "0 * * * *", // every hour at :00 — min interval is 15 minutes
  },
  toolCalls: [
    { name: "athena", arguments: {} },
    {
      name: "herald",
      arguments: {
        format: "text",
        subject: "Chronos ping {{run.local_date}}",
        body: "Athena says: {{steps.step_0.result}}",
      },
    },
  ],
});

await chronos.createJobFromEvents({
  // ...
  suggestTemporalBindings: false,
  events: [/* … */],
});

const preview = await chronos.capture({
  events: [
    {
      kind: "tool",
      name: "pandora_list_calendar_events",
      arguments: {
        time_min: "2026-07-17T05:00:00.000Z",
        max_results: 10,
      },
    },
    {
      kind: "model",
      user_instruction: "Summarize today's calendar in 5 bullets.",
    },
  ],
});

console.log(preview.steps);
console.log(preview.bindingSuggestions);
// { stepId, argKey, from, to }[]

const { recipe } = await chronos.capture({
  name: "calendar-summary-recipe",
  persist: true,
  events: [
    {
      kind: "tool",
      id: "cal",
      name: "pandora_list_calendar_events",
      arguments: { time_min: "2026-01-01T00:00:00.000Z" },
    },
    {
      kind: "model",
      id: "compose",
      user_instruction: "Summarize the calendar for email.",
    },
  ],
});

// Later: attach a schedule to an existing recipe
const { job } = await chronos.createJobFromRecipe({
  name: "morning calendar",
  recipeId: recipe.id,
  timezone: "America/New_York",
  schedule: {
    kind: "weekly_times",
    days: ["MON", "TUE", "WED", "THU", "FRI"],
    time: "07:00",
  },
});

// Fire immediately (billable — same fee + tools + tokens as a scheduled fire)
const result = await chronos.runNow(job.id);
console.log(result);
// {
//   runId: "…",
//   status: "succeeded" | "failed" | "skipped_stale" | …,
//   error_summary?: "…"
// }

// History
const { runs } = await chronos.listRuns(job.id, 10);
for (const r of runs) {
  console.log(r.id, r.status, r.scheduled_for, r.chronos_fee_cents);
}

// Detail (step previews, errors)
const { run } = await chronos.getRun(result.runId);
console.log(run.status);
console.log(run.step_results);
// [
//   { id, name, kind, status, duration_ms, error?, result_preview? },
//   …
// ]
console.log(run.error_summary);
console.log(run.html_body); // last step text artifact when present

async function waitForRun(chronos, runId, { timeoutMs = 120_000 } = {}) {
  const start = Date.now();
  while (Date.now() - start < timeoutMs) {
    const { run } = await chronos.getRun(runId);
    if (
      run.status === "succeeded" ||
      run.status === "failed" ||
      run.status === "skipped_stale"
    ) {
      return run;
    }
    await new Promise((r) => setTimeout(r, 2000));
  }
  throw new Error("Timed out waiting for Chronos run");
}

const { jobs } = await chronos.listJobs();
for (const j of jobs) {
  console.log(j.id, j.name, j.enabled, j.next_run_at, j.last_run_status);
}

const { job: detail } = await chronos.getJob(jobs[0].id);

// Pause
await chronos.updateJob(detail.id, { enabled: false });

// Resume + new time
await chronos.updateJob(detail.id, {
  enabled: true,
  timezone: "America/Los_Angeles",
  schedule: {
    kind: "weekly_times",
    days: ["MON", "WED", "FRI"],
    time: "09:15",
  },
});

// Rename
await chronos.updateJob(detail.id, { name: "Team briefing" });

// Delete (removes the job; recipe may remain if shared)
await chronos.deleteJob(detail.id);

/**
 * e2e-chronos.mjs
 *
 *   export HVZ_KEY=hvz_live_…
 *   node e2e-chronos.mjs
 */
import { createChronosClient } from "./chronos-client.js";

const chronos = createChronosClient(process.env.HVZ_KEY);

async function main() {
  // 1) Create
  const { job, bindingSuggestions } = await chronos.createJobFromEvents({
    name: `demo-${Date.now()}`,
    timezone: Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC",
    enabled: true,
    schedule: {
      kind: "weekly_times",
      days: ["MON", "TUE", "WED", "THU", "FRI", "SAT", "SUN"],
      time: "08:30",
    },
    events: [
      {
        kind: "tool",
        id: "time",
        name: "athena",
        arguments: {},
      },
      {
        kind: "model",
        id: "compose",
        user_instruction:
          "One short paragraph: what time is it according to the tool result? Plain text.",
      },
      {
        kind: "tool",
        id: "send",
        name: "herald",
        arguments: {
          format: "text",
          subject: "Chronos demo {{run.local_date}}",
          body: "{{steps.compose.result}}",
        },
      },
    ],
  });

  console.log("Created job", job.id);
  console.log("Bindings applied:", bindingSuggestions);

  // 2) Run immediately (does not wait for next_run_at)
  const { runId, status, error_summary } = await chronos.runNow(job.id);
  console.log("run-now:", { runId, status, error_summary });

  const { run } = await chronos.getRun(runId);
  console.log(
    "steps:",
    (run.step_results || []).map((s) => `${s.name}:${s.status}`).join(" → "),
  );

  // 3) Pause so it does not fire again while you experiment
  await chronos.updateJob(job.id, { enabled: false });
  console.log("Paused job", job.id);

  // 4) Optional cleanup
  // await chronos.deleteJob(job.id);
}

main().catch((e) => {
  console.error(e.status, e.code, e.message, e.body);
  process.exit(1);
});

{
  kind: "weekly_times",
  days: ["MON", "TUE", "WED", "THU", "FRI"], // also SAT, SUN
  time: "08:30", // HH:mm 24h in the job timezone
}

{ kind: "cron", expr: "30 8 * * 1-5" }

try {
  await chronos.runNow(jobId);
} catch (e) {
  console.error(e.status, e.code, e.message);
  // e.body may include structured fields from the API
}