Use this package when you need to create, validate, parse, or document OpenTag protocol objects without depending on any provider SDK or runtime service.

Install

pnpm add @opentag/core

Exports

OpenTagEventSchema, OpenTagRunSchema, OpenTagRunResultSchema: Zod schemas for protocol objects.
OpenTagEvent, OpenTagRun, OpenTagRunResult: TypeScript types inferred from the schemas.
CompletionContract, CompletionAssessment, HumanEscalation: additive completion-governance protocol objects that keep executor outcome separate from accepted work completion.
RunnerDirectoryEntry, RoutingDecision, AcceptedProgressMetrics: additive schemas for current runner readiness, explainable placement, and evidence-attributed progress by runner or executor.
FactoryRecipeSnapshot, Workstream, WorkstreamAdmissionBatchReceipt, WorkstreamMetrics, WorkstreamEvaluation: immutable factory grouping, replay-safe batch receipt, and accepted-outcome evaluation contracts.
WorkstreamContinuationPolicy, WorkstreamContinuationDecision: an opt-in recipe policy and explainable eligibility result for bounded evidence-driven WorkThread continuation.
parseOpenTagMention: extracts an @opentag command from workspace text.
commandFromRawText: maps raw command text to a normalized intent.
OpenTagJsonSchemas: JSON Schema definitions for systems that do not use TypeScript or Zod.

Example

import { OpenTagEventSchema, parseOpenTagMention } from "@opentag/core";

const command = parseOpenTagMention("@opentag fix this flaky test");
if (!command.matched) {
  throw new Error("No OpenTag command found");
}

const event = OpenTagEventSchema.parse({
  id: "evt_1",
  source: "github",
  sourceEventId: "comment_1",
  receivedAt: new Date().toISOString(),
  actor: { provider: "github", providerUserId: "42", handle: "octocat" },
  target: { mention: "@opentag", agentId: "opentag" },
  command: { rawText: command.rawText, intent: command.intent, args: command.args },
  context: [],
  permissions: [{ scope: "issue:comment", reason: "reply to source thread" }],
  callback: { provider: "github", uri: "https://api.github.com/repos/acme/demo/issues/1/comments" },
  metadata: { owner: "acme", repo: "demo" }
});