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.mdowns cross-stage state, language, rendering, approval, and export conventions.- Each
skills/*/SKILL.mdis 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.tsexposes 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/.