Skip to content

chralt98/bleavit-foresight

v1.0.0Apache-2.0

Prepare forecast contracts for research, decision-making, and prediction markets by drafting focused questions, clarifying conditions, identifying resolution sources, and setting evidence-based criteria.

Event Contract Builder

Event Contract Builder is the open-source npm package and plugin interface for Bleavit Foresight, a ChatGPT plugin for creating forecast specifications. The package name remains event-contract-builder; its public schemas and client-visible interface are the ones used by Foresight.

The plugin drafts forecast question units, precise definitions, independent resolution sources, resolution criteria, historical context, and optional recent news. Each stage remains pending until the user explicitly approves it. Probability monitoring is planned; it is not part of the current workflow.

Third-party workflow attributions and license notices are listed in THIRD_PARTY_LICENSES.md.

Use the Foresight TypeScript package

Install the package from npm:

npm install event-contract-builder

The package root exports Foresight schemas, types, structural validation, client-visible tool descriptors, server instructions, and canonical stage preparation materials. The same API is also available from the event-contract-builder/foresight subpath.

import {
  ForecastQuestionUnit,
  foresightTools,
  type ForecastQuestionUnitT,
} from "event-contract-builder";

const draft: ForecastQuestionUnitT = {
  question: "Will CPI year-over-year inflation exceed 3 percent in June 2027?",
};

const validatedDraft = ForecastQuestionUnit.parse(draft);
const submitQuestionTool =
  foresightTools.propose_forecast_specification_stage_changes;

console.log(validatedDraft.question);
console.log(submitQuestionTool.title);

The npm package describes and validates the public interface. It does not include tool handlers, workflow state, or the hosted service. Approved specifications are retrieved through the public MCP interface.

Forecast workflow

The workflow is: draft and approve one forecast question unit, define terms, choose resolution sources, define resolution criteria, add background information, and optionally add recent news.

Question drafting in Bleavit Foresight is informed by Metaculus’s question-writing guidance.

Instruction ownership is deliberately split to avoid duplicate maintenance:

  • src/foresight/instructions.md owns cross-stage state, language, rendering, approval, and export conventions.
  • Each skills/*/SKILL.md is a short workflow entry point.
  • Each skill reference owns that stage's semantic rules and detailed format.
  • Stage preparation bundles canonical skill materials for the server prerequisite; shared instructions own preparation routing.
  • src/foresight/tools.ts exposes concise tool intent and machine-enforced schemas; it does not restate skill procedures.

Change a rule at its owning layer rather than copying it into another one.

Hosted service and repository boundary

This repository contains the open-source Foresight package, plugin assets, six skills, and client-visible MCP interface. The hosted Bleavit Foresight service provides MCP execution, workflow state, rendering, and future monitoring services. Those operational components are not included here. See the repository boundary for details.

The public package builds and tests independently:

bun install
bun run test
bun run check

The plugin ID is bleavit-foresight; the npm package remains event-contract-builder. The plugin display name is Bleavit Foresight. The open-source repository remains usable for inspecting, adapting, and implementing the published interface; service access and operational components are provided separately.

Develop with the local plugin

The repository-linked plugin connects to the production service by default. For local development, run bun run refresh:plugin -- --local to install the connection from mcp.local.json (http://localhost:8787/mcp). Run bun run start:server in the sibling bleavit-foresight checkout; see that repository's development instructions for checkout watching and Worker integration.

To use the deployed staging service, run bun run refresh:plugin -- --staging. This installs the connection from mcp.staging.json (https://api.staging.foresight.bleavit.com/mcp) with OAuth registration at the staging auth endpoint. Deploy the staging workers from the sibling bleavit-foresight checkout first; this command only changes the MCP connection in the locally installed plugin.

The repository-linked plugin uses the local app mapping from .app.json. To create that mapping for this checkout, copy the example and replace the placeholder with the app's ID:

cp .app.example.json .app.json

.app.json is ignored by Git and contains your environment-specific app ID. The tracked .mcp.json and mcp.json use the production endpoint with server-discovered OAuth. Local refresh omits portable per-server extensions, which Codex Desktop 0.163 rejects. Public packaging retains the explicit OAuth configuration from mcp.production.json. A normal bun run refresh:plugin installs the connection from mcp.production.json; --production remains an explicit alias for the default. --local, --staging, and --production are mutually exclusive. Refresh changes the installed copy without rewriting the source MCP configs. The distributable plugin omits the local app mapping and uses the production configuration described below.

Refresh the repository-linked plugin

After changing skills or plugin metadata, refresh the copy installed from your personal marketplace:

bun run refresh:plugin

The command defaults to ~/.agents/plugins/marketplace.json, checks that its local source points to this checkout, and installs the updated plugin. If you use a different marketplace, pass its marketplace.json path explicitly. To check the personal marketplace link without reinstalling:

bun run refresh:plugin --check

Refresh updates the installed plugin and prunes development files from its cache. Start a new Codex task to load refreshed skills. After changing MCP tool descriptions or schemas, refresh the app connection as well. The refresh uses a unique <package.json version>+codex.<timestamp> version in the local Codex cache only; the source manifests retain the public plugin SemVer used for submission.

Package the plugin

bun run package:plugin

This creates out/bleavit-foresight.zip and an unpacked plugin directory from an explicit asset allowlist. The archive includes the skills, manifest, MCP configuration and license notices, including THIRD_PARTY_LICENSES.md. It excludes the library build, development files and local app mapping. Its manifest omits the local apps reference. By default, its MCP configuration uses the endpoint in mcp.production.json for both packaged MCP configs; override it for another environment with bun run package:plugin -- --mcp-url https://your-endpoint.example/mcp. Set PLUGIN_DEMO_RECORDING_URL in the project .env file or packaging process environment to add a private review demo URL to the generated manifest without storing it in the repository source. Use a plain HTTPS URL. This command does not publish anything.

Product website

The static product site lives in site/ and is intended for Cloudflare Pages at https://foresight.bleavit.com. The MCP Worker uses the separate host https://api.foresight.bleavit.com/mcp. Keep the product overview and public support and policy pages in the site; do not include Worker secrets or D1 configuration there.

Disclaimer

See DISCLAIMER.md for important information about the legal and regulatory status of forecast specifications produced with this tooling.

License

Copyright © 2026 Christopher Maximilian Altmann. Licensed under the Apache License, Version 2.0.

The package exports the site’s shared visual tokens and icon through event-contract-builder/appearance/tokens.css and event-contract-builder/appearance/foresight-icon.png. Their canonical sources remain in site/tokens.css and site/assets/.