@agentsgot/agent-kit 0.0.0-stage → 1.0.0

package/vendor/shared/src/schemas/domain.ts

@@ -0,0 +1,187 @@
+import { z } from "zod";
+
+import {
+  AcceptanceGrade,
+  AcceptanceGradeSchema,
+  AllocationModeSchema,
+  ArbitrationRoundSchema,
+  TaskTemplateSchema,
+  TierSchema,
+} from "./enums.js";
+
+export const DecimalIntegerSchema = z.string().regex(/^(0|[1-9]\d*)$/u);
+export const PositiveDecimalIntegerSchema = z.string().regex(/^[1-9]\d*$/u);
+export const DecimalStringSchema = z.string().regex(/^(0|[1-9]\d*)(\.\d+)?$/u);
+export const IsoDateTimeSchema = z.iso.datetime({ offset: true });
+export const AddressSchema = z.string().regex(/^0x[0-9a-fA-F]{40}$/u);
+export const Hex32Schema = z.string().regex(/^0x[0-9a-fA-F]{64}$/u);
+
+export const MachineCheckSchema = z.object({
+  kind: z.string().trim().min(1).max(64),
+  commandOrSchema: z.string().trim().min(1).max(4_096),
+  expected: z.string().max(4_096),
+});
+
+export const CriterionSchema = z
+  .object({
+    id: z.string().trim().min(1).max(128),
+    description: z.string().trim().min(1).max(4_096),
+    grade: AcceptanceGradeSchema,
+    weightBps: z.number().int().min(0).max(10_000),
+    machineCheck: MachineCheckSchema.optional(),
+  })
+  .superRefine((criterion, context) => {
+    if (criterion.grade === AcceptanceGrade.A && criterion.machineCheck === undefined) {
+      context.addIssue({
+        code: "custom",
+        path: ["machineCheck"],
+        message: "Grade A requires a machine check",
+      });
+    }
+  });
+
+export const TaskInputSchema = z.object({
+  kind: z.enum(["REPO", "FILE", "URL", "TEXT"]),
+  ref: z.string().trim().min(1).max(8_192),
+});
+
+export const TaskSpecSchema = z
+  .object({
+    version: z.enum(["AGENTGRID_TASK_SPEC_V3", "AGENTGRID_TASK_SPEC_V4"]),
+    title: z.string().trim().min(1).max(200),
+    summary: z.string().trim().min(1).max(8_000),
+    template: TaskTemplateSchema,
+    deliverables: z.array(z.string().trim().min(1).max(2_000)).min(1),
+    outOfScope: z.array(z.string().trim().min(1).max(2_000)),
+    constraints: z.array(z.string().trim().min(1).max(2_000)),
+    inputs: z.array(TaskInputSchema),
+    criteria: z.array(CriterionSchema).min(1),
+    estimatedHours: z.number().positive(),
+    startTier: TierSchema,
+    maxTier: TierSchema,
+    runDays: z.number().int().positive(),
+    allocationMode: AllocationModeSchema,
+    topK: z.number().int().positive().optional(),
+    /** 0 means unlimited; a custom cap fits the protocol's uint16 field. */
+    maxParticipants: z.number().int().min(0).max(65_535).optional(),
+    passingThreshold: z.number().int().min(50).max(90).default(60),
+    criticReportHash: Hex32Schema.optional(),
+  })
+  .superRefine((specification, context) => {
+    if (
+      new Set(specification.criteria.map(({ id }) => id)).size !== specification.criteria.length
+    ) {
+      context.addIssue({
+        code: "custom",
+        path: ["criteria"],
+        message: "Criterion IDs must be unique",
+      });
+    }
+    if (specification.criteria.reduce((sum, item) => sum + item.weightBps, 0) !== 10_000) {
+      context.addIssue({
+        code: "custom",
+        path: ["criteria"],
+        message: "Criterion weights must total 10000 bps",
+      });
+    }
+    if (specification.allocationMode === "TOP_K" && specification.topK === undefined) {
+      context.addIssue({
+        code: "custom",
+        path: ["topK"],
+        message: "TopK allocation requires topK",
+      });
+    }
+    if (specification.version === "AGENTGRID_TASK_SPEC_V4") {
+      if (specification.allocationMode !== "PRO_RATA") {
+        context.addIssue({
+          code: "custom",
+          path: ["allocationMode"],
+          message: "V4 tasks use proportional allocation",
+        });
+      }
+      if (specification.topK !== undefined) {
+        context.addIssue({
+          code: "custom",
+          path: ["topK"],
+          message: "V4 tasks do not use Top K",
+        });
+      }
+      if (specification.maxParticipants === undefined) {
+        context.addIssue({
+          code: "custom",
+          path: ["maxParticipants"],
+          message: "V4 tasks require a participant limit",
+        });
+      }
+    }
+  });
+
+export const RuleCheckResultSchema = z.object({
+  id: z.string().min(1),
+  level: z.enum(["ok", "warn", "block"]),
+  message: z.string().min(1),
+  fields: z.array(z.string()).default([]),
+  params: z.record(z.string(), z.string()).optional(),
+});
+
+export const DisputeSchema = z.object({
+  id: z.string().min(1),
+  taskId: z.string().min(1),
+  trigger: z.enum(["REJECTION", "TEST_CONTESTED", "MAINTENANCE_DEFECT"]),
+  round: ArbitrationRoundSchema,
+  panelSize: z.union([z.literal(3), z.literal(5), z.literal(9), z.literal(11), z.literal(21)]),
+  criterionIds: z.array(z.string().min(1)).min(1),
+  phase: z.enum(["DRAWING", "CONFIRM", "COMMIT", "REVEAL", "TALLIED", "EXECUTED"]),
+  caseFee: DecimalIntegerSchema,
+  lockPerJuror: DecimalIntegerSchema,
+  outcome: z
+    .object({
+      perCriterion: z.record(z.string(), z.boolean()),
+      result: z.enum(["PUBLISHER_WINS", "EXECUTOR_WINS", "PARTIAL"]),
+    })
+    .optional(),
+});
+
+export const VoteSchema = z.object({
+  disputeId: z.string().min(1),
+  jurorId: z.string().min(1),
+  commitHash: Hex32Schema,
+  revealed: z.record(z.string(), z.boolean()).optional(),
+  reasonHash: Hex32Schema.optional(),
+});
+
+export const VestingTrancheSchema = z.object({
+  taskId: z.string().min(1),
+  beneficiary: AddressSchema,
+  kind: z.enum(["DEDUCTION", "EMISSION"]),
+  amount: PositiveDecimalIntegerSchema,
+  releaseAt: IsoDateTimeSchema,
+  status: z.enum(["LOCKED", "CLAIMABLE", "CLAIMED", "CLAWED_BACK"]),
+});
+
+/** Economic model v3 daily emission snapshot (§4.7). */
+export const EmissionDaySchema = z.object({
+  epoch: z.number().int().nonnegative(),
+  treasuryBalance: DecimalIntegerSchema,
+  dailyEmission: DecimalIntegerSchema,
+  platformAmount: DecimalIntegerSchema,
+  executorAmount: DecimalIntegerSchema,
+  testerAmount: DecimalIntegerSchema,
+  arbitratorAmount: DecimalIntegerSchema,
+  burnedAmount: DecimalIntegerSchema.default("0"),
+  /** Optional Merkle root binding accrued exec/test leaves for the epoch. */
+  allocationRoot: Hex32Schema.optional(),
+  totalTaskWeight: DecimalIntegerSchema.optional(),
+  activeTaskCount: z.number().int().nonnegative().optional(),
+  computedAt: IsoDateTimeSchema,
+});
+
+export type MachineCheck = z.infer<typeof MachineCheckSchema>;
+export type Criterion = z.infer<typeof CriterionSchema>;
+export type TaskInput = z.infer<typeof TaskInputSchema>;
+export type TaskSpec = z.infer<typeof TaskSpecSchema>;
+export type RuleCheckResult = z.infer<typeof RuleCheckResultSchema>;
+export type Dispute = z.infer<typeof DisputeSchema>;
+export type Vote = z.infer<typeof VoteSchema>;
+export type VestingTranche = z.infer<typeof VestingTrancheSchema>;
+export type EmissionDay = z.infer<typeof EmissionDaySchema>;

package/vendor/shared/src/schemas/draft.ts

@@ -0,0 +1,141 @@
+import { z } from "zod";
+import {
+  AddressSchema,
+  CriterionSchema,
+  DecimalIntegerSchema,
+  IsoDateTimeSchema,
+  TaskInputSchema,
+  type TaskSpec,
+  TaskSpecSchema,
+} from "./domain.js";
+import { AllocationModeSchema, TaskTemplateSchema, TierSchema } from "./enums.js";
+
+export const DraftFieldSourceSchema = z.enum(["user", "ai", "rule"]);
+export const DraftFieldConfirmationSchema = z.enum(["unconfirmed", "confirmed", "suggested"]);
+
+export function draftFieldSchema<T extends z.ZodType>(valueSchema: T) {
+  return z.object({
+    value: valueSchema.nullable(),
+    source: DraftFieldSourceSchema,
+    confirmation: DraftFieldConfirmationSchema,
+    updatedAt: IsoDateTimeSchema,
+  });
+}
+
+export const DraftCriterionSchema = draftFieldSchema(CriterionSchema);
+
+const RuleCostSchema = z.object({
+  reserve: DecimalIntegerSchema,
+  dailyFee: DecimalIntegerSchema,
+});
+
+export const TaskDraftFieldsSchema = z.object({
+  title: draftFieldSchema(z.string().trim().min(1).max(200)),
+  summary: draftFieldSchema(z.string().trim().min(1).max(8_000)),
+  template: draftFieldSchema(TaskTemplateSchema),
+  deliverables: draftFieldSchema(z.array(z.string().trim().min(1).max(2_000)).min(1)),
+  outOfScope: draftFieldSchema(z.array(z.string().trim().min(1).max(2_000))),
+  constraints: draftFieldSchema(z.array(z.string().trim().min(1).max(2_000))),
+  inputs: draftFieldSchema(z.array(TaskInputSchema)),
+  criteria: draftFieldSchema(z.array(DraftCriterionSchema).min(1)),
+  estimatedHours: draftFieldSchema(z.number().positive()),
+  startTier: draftFieldSchema(TierSchema),
+  maxTier: draftFieldSchema(TierSchema),
+  runDays: draftFieldSchema(z.number().int().positive()),
+  allocationMode: draftFieldSchema(AllocationModeSchema),
+  topK: draftFieldSchema(z.number().int().positive()),
+  /** 0 means unlimited; a custom cap fits the protocol's uint16 field. */
+  maxParticipants: draftFieldSchema(z.number().int().min(0).max(65_535)),
+  passingThreshold: draftFieldSchema(z.number().int().min(50).max(90)),
+  minimumTier: draftFieldSchema(TierSchema),
+  cost: draftFieldSchema(RuleCostSchema),
+});
+
+export const DraftSuggestionSchema = z.object({
+  field: z.string().min(1),
+  value: z.unknown(),
+  createdAt: IsoDateTimeSchema,
+});
+
+export const TaskDraftSchema = z.object({
+  id: z.string().min(1),
+  sessionId: z.string().min(1),
+  publisher: AddressSchema,
+  version: z.number().int().nonnegative(),
+  fields: TaskDraftFieldsSchema,
+  summarizedUpToMessageId: z.string().nullable(),
+  lastSummarizedAt: IsoDateTimeSchema.nullable(),
+  pendingSuggestions: z.array(DraftSuggestionSchema),
+  status: z.enum(["EDITING", "FROZEN", "PUBLISHED", "EXPIRED"]),
+});
+
+export type DraftField<T> = {
+  value: T | null;
+  source: z.infer<typeof DraftFieldSourceSchema>;
+  confirmation: z.infer<typeof DraftFieldConfirmationSchema>;
+  updatedAt: string;
+};
+export type DraftCriterion = z.infer<typeof DraftCriterionSchema>;
+export type TaskDraftFields = z.infer<typeof TaskDraftFieldsSchema>;
+export type TaskDraft = z.infer<typeof TaskDraftSchema>;
+export type DraftSuggestion = z.infer<typeof DraftSuggestionSchema>;
+
+const editableFields = [
+  "title",
+  "summary",
+  "template",
+  "deliverables",
+  "outOfScope",
+  "constraints",
+  "inputs",
+  "criteria",
+  "estimatedHours",
+  "startTier",
+  "maxTier",
+  "runDays",
+  "maxParticipants",
+  "passingThreshold",
+] as const;
+
+export function finalizeDraft(input: TaskDraft): TaskSpec {
+  const draft = TaskDraftSchema.parse(input);
+  const missing: string[] = editableFields.filter((name) => {
+    const field = draft.fields[name];
+    return field.value === null || field.confirmation !== "confirmed";
+  });
+  for (const name of ["minimumTier", "cost", "allocationMode"] as const) {
+    const field = draft.fields[name];
+    if (field.value === null || field.source !== "rule") missing.push(name);
+  }
+  const draftCriteria = draft.fields.criteria.value;
+  if (
+    draftCriteria?.some(
+      (criterion) => criterion.value === null || criterion.confirmation !== "confirmed",
+    ) === true
+  ) {
+    missing.push("criteria");
+  }
+  if (missing.length > 0) {
+    throw new Error(`Draft fields are incomplete or unconfirmed: ${missing.join(", ")}`);
+  }
+
+  const fields = draft.fields;
+  return TaskSpecSchema.parse({
+    version: "AGENTGRID_TASK_SPEC_V4",
+    title: fields.title.value,
+    summary: fields.summary.value,
+    template: fields.template.value,
+    deliverables: fields.deliverables.value,
+    outOfScope: fields.outOfScope.value,
+    constraints: fields.constraints.value,
+    inputs: fields.inputs.value,
+    criteria: fields.criteria.value?.map((criterion) => criterion.value),
+    estimatedHours: fields.estimatedHours.value,
+    startTier: fields.startTier.value,
+    maxTier: fields.maxTier.value,
+    runDays: fields.runDays.value,
+    allocationMode: fields.allocationMode.value,
+    maxParticipants: fields.maxParticipants.value,
+    passingThreshold: fields.passingThreshold.value,
+  });
+}

package/vendor/shared/src/schemas/enums.ts

@@ -0,0 +1,73 @@
+import { z } from "zod";
+
+export const Role = {
+  Publisher: "PUBLISHER",
+  Executor: "EXECUTOR",
+  Tester: "TESTER",
+  Reviewer: "REVIEWER",
+  Arbitrator: "ARBITRATOR",
+} as const;
+export const Tier = {
+  T1: "T1",
+  T2: "T2",
+  T3: "T3",
+  T4: "T4",
+  T5: "T5",
+} as const;
+export const AcceptanceGrade = { A: "A", B: "B", C: "C" } as const;
+export const AllocationMode = {
+  WinnerTakesAll: "WINNER_TAKES_ALL",
+  TopK: "TOP_K",
+  ProRata: "PRO_RATA",
+} as const;
+export const TaskTemplate = {
+  CodeFix: "CODE_FIX",
+  DataProcessing: "DATA_PROCESSING",
+  Translation: "TRANSLATION",
+  Research: "RESEARCH",
+  Custom: "CUSTOM",
+} as const;
+export const TaskStatus = {
+  Published: "PUBLISHED",
+  Running: "RUNNING",
+  Grace: "GRACE",
+  Closed: "CLOSED",
+  Testing: "TESTING",
+  Reviewing: "REVIEWING",
+  ResultPosted: "RESULT_POSTED",
+  Accepted: "ACCEPTED",
+  Disputed: "DISPUTED",
+  Appealed: "APPEALED",
+  Maintenance: "MAINTENANCE",
+  Completed: "COMPLETED",
+  Cancelled: "CANCELLED",
+  Expired: "EXPIRED",
+  NoSubmission: "NO_SUBMISSION",
+  Insufficient: "INSUFFICIENT",
+  Failed: "FAILED",
+} as const;
+export const ValidatorStatus = {
+  Active: "ACTIVE",
+  Grace: "GRACE",
+  Inactive: "INACTIVE",
+  CoolingDown: "COOLING_DOWN",
+} as const;
+export const ArbitrationRound = { First: "FIRST", Final: "FINAL" } as const;
+
+export const RoleSchema = z.enum(Role);
+export const TierSchema = z.enum(Tier);
+export const AcceptanceGradeSchema = z.enum(AcceptanceGrade);
+export const AllocationModeSchema = z.enum(AllocationMode);
+export const TaskTemplateSchema = z.enum(TaskTemplate);
+export const TaskStatusSchema = z.enum(TaskStatus);
+export const ValidatorStatusSchema = z.enum(ValidatorStatus);
+export const ArbitrationRoundSchema = z.enum(ArbitrationRound);
+
+export type Role = z.infer<typeof RoleSchema>;
+export type Tier = z.infer<typeof TierSchema>;
+export type AcceptanceGrade = z.infer<typeof AcceptanceGradeSchema>;
+export type AllocationMode = z.infer<typeof AllocationModeSchema>;
+export type TaskTemplate = z.infer<typeof TaskTemplateSchema>;
+export type TaskStatus = z.infer<typeof TaskStatusSchema>;
+export type ValidatorStatus = z.infer<typeof ValidatorStatusSchema>;
+export type ArbitrationRound = z.infer<typeof ArbitrationRoundSchema>;

package/vendor/shared/src/schemas/index.ts

@@ -0,0 +1,3 @@
+export * from "./domain.js";
+export * from "./draft.js";
+export * from "./enums.js";

package/vendor/shared/src/units.ts

@@ -0,0 +1,43 @@
+/** 01-RULES §0.3: 1 AGT = 10^18 wei. Rule parameters are human AGT; contracts, HTTP and storage use wei. */
+export const AGT_DECIMALS = 18;
+export const WEI_PER_AGT = 10n ** 18n;
+
+const AGT_DECIMAL = /^(0|[1-9]\d*)(\.\d{1,18})?$/u;
+
+/** Parses a non-negative AGT decimal string (`"0.6"`, `"10"`) into wei without floating point. */
+export function parseAgtToWei(value: string): bigint {
+  const text = value.trim();
+  if (!AGT_DECIMAL.test(text)) throw new RangeError(`invalid AGT amount: ${value}`);
+  const [whole = "0", fraction = ""] = text.split(".");
+  return BigInt(whole) * WEI_PER_AGT + BigInt(fraction.padEnd(AGT_DECIMALS, "0"));
+}
+
+/** Converts a fixed AGT rule parameter from params.json (for example `0.5`) into wei, exactly once. */
+export function agtToWei(value: number): bigint {
+  if (!Number.isFinite(value) || value < 0) throw new RangeError(`invalid AGT amount: ${value}`);
+  return parseAgtToWei(plainDecimal(String(value)));
+}
+
+/** Expands the shortest round-trip form (`"1e-7"`, `"2e+21"`) into plain decimal digits. */
+function plainDecimal(text: string): string {
+  const match = /^(\d+)(?:\.(\d+))?e([+-]\d+)$/u.exec(text);
+  if (!match) return text;
+  const [, whole = "", fraction = "", exponentText = "0"] = match;
+  const digits = whole + fraction;
+  const point = whole.length + Number(exponentText);
+  if (point <= 0) return `0.${"0".repeat(-point)}${digits}`;
+  if (point >= digits.length) return digits + "0".repeat(point - digits.length);
+  return `${digits.slice(0, point)}.${digits.slice(point)}`;
+}
+
+/** Formats wei as a plain AGT decimal without unit or grouping (`600000000000000000n` → `"0.6"`). */
+export function formatWeiAsAgt(wei: bigint): string {
+  const negative = wei < 0n;
+  const absolute = negative ? -wei : wei;
+  const whole = absolute / WEI_PER_AGT;
+  const fraction = (absolute % WEI_PER_AGT)
+    .toString()
+    .padStart(AGT_DECIMALS, "0")
+    .replace(/0+$/u, "");
+  return `${negative ? "-" : ""}${whole}${fraction ? `.${fraction}` : ""}`;
+}

package/vendor/shared/test/emission-schedule.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  BPS,
+  HOUR,
+  WAD,
+  arbitrationEmitted,
+  buildSchedule,
+  cumulativeReleased,
+  cumulativeShares,
+  firstHour,
+  hourShares,
+  pow2Neg,
+  powWad,
+} from "../src/emission-schedule.js";
+
+const B0 = 800_000_000n * WAD;
+const HALF_LIFE = 913n;
+
+function sampleSchedule(startTime = 1_700_000_000n) {
+  return buildSchedule({
+    startTime,
+    initialBalance: B0,
+    halfLifeDays: HALF_LIFE,
+    platformBps: 1000n,
+    execBps: 6500n,
+    testBps: 1500n,
+  });
+}
+
+describe("emission-schedule", () => {
+  it("pow2Neg is in (0, WAD)", () => {
+    const q = pow2Neg(HALF_LIFE * 24n);
+    expect(q).toBeGreaterThan(0n);
+    expect(q).toBeLessThan(WAD);
+  });
+
+  it("powWad(q,0)=WAD and decreases with k", () => {
+    const q = pow2Neg(HALF_LIFE * 24n);
+    expect(powWad(q, 0n)).toBe(WAD);
+    expect(powWad(q, 1n)).toBe(q);
+    expect(powWad(q, 2n)).toBeLessThan(q);
+  });
+
+  it("R(t0)=0 and R grows after activation", () => {
+    const s = sampleSchedule();
+    expect(cumulativeReleased(s, s.startTime)).toBe(0n);
+    expect(cumulativeReleased(s, s.startTime + 1n)).toBeGreaterThan(0n);
+    expect(cumulativeReleased(s, s.startTime + HOUR)).toBeGreaterThan(
+      cumulativeReleased(s, s.startTime + 1n),
+    );
+  });
+
+  it("activation hour is partial", () => {
+    const s = sampleSchedule(1_700_000_000n + 1800n);
+    const h = firstHour(s);
+    const shares = hourShares(s, h);
+    const fullNext = hourShares(s, h + 1n);
+    expect(shares.emission).toBeGreaterThan(0n);
+    expect(shares.emission).toBeLessThan(fullNext.emission);
+  });
+
+  it("telescopes: sum of hour shares equals cumulative delta", () => {
+    const s = sampleSchedule();
+    const from = firstHour(s);
+    const to = from + 47n;
+    let sum = 0n;
+    let plat = 0n;
+    let exec = 0n;
+    let test = 0n;
+    let arb = 0n;
+    for (let h = from; h <= to; h++) {
+      const sh = hourShares(s, h);
+      sum += sh.emission;
+      plat += sh.platform;
+      exec += sh.exec;
+      test += sh.test;
+      arb += sh.arb;
+    }
+    const end = (to + 1n) * HOUR;
+    const c = cumulativeShares(s, end);
+    expect(sum).toBe(c.released);
+    expect(plat).toBe(c.platform);
+    expect(exec).toBe(c.exec);
+    expect(test).toBe(c.test);
+    expect(arb).toBe(c.arb);
+    expect(plat + exec + test + arb).toBe(sum);
+  });
+
+  it("never exceeds B0 and approaches it over long horizons", () => {
+    const s = sampleSchedule();
+    const fiftyYears = s.startTime + 50n * 365n * 24n * HOUR;
+    const r = cumulativeReleased(s, fiftyYears);
+    expect(r).toBeLessThanOrEqual(B0);
+    expect(r).toBeGreaterThan((B0 * 95n) / 100n);
+  });
+
+  it("arbitrationEmitted matches cumulative arb delta", () => {
+    const s = sampleSchedule();
+    const t1 = s.startTime + 1000n;
+    const t2 = s.startTime + 10_000n;
+    expect(arbitrationEmitted(s, t1, t2)).toBe(
+      cumulativeShares(s, t2).arb - cumulativeShares(s, t1).arb,
+    );
+  });
+
+  it("bps shares use floor and arb is remainder", () => {
+    const s = sampleSchedule();
+    const c = cumulativeShares(s, s.startTime + HOUR);
+    expect(c.platform).toBe((c.released * 1000n) / BPS);
+    expect(c.exec).toBe((c.released * 6500n) / BPS);
+    expect(c.test).toBe((c.released * 1500n) / BPS);
+    expect(c.arb).toBe(c.released - c.platform - c.exec - c.test);
+  });
+});