agentskeptic 1.3.0 → 2.0.0

package/schemas/registry-draft-response.schema.json

@@ -0,0 +1,89 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentskeptic.com/schemas/registry-draft-response.schema.json",
+  "title": "RegistryDraftResponseEnvelope",
+  "description": "Single SSOT envelope for assisted registry-draft (HTTP 200 success). Breaking change from deprecated v2.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "draft",
+    "assumptions",
+    "warnings",
+    "disclaimer",
+    "generation",
+    "quickIngestInput",
+    "readiness"
+  ],
+  "properties": {
+    "schemaVersion": { "type": "integer", "const": 3 },
+    "draft": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["tools"],
+      "properties": {
+        "tools": {
+          "$ref": "https://agentskeptic.com/schemas/tools-registry.schema.json"
+        }
+      }
+    },
+    "assumptions": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "warnings": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "disclaimer": { "type": "string", "minLength": 1 },
+    "generation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["backend", "model"],
+      "properties": {
+        "backend": { "type": "string", "enum": ["hosted_openai", "local_ollama"] },
+        "model": { "type": "string", "minLength": 1 }
+      }
+    },
+    "quickIngestInput": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["encoding", "body"],
+      "properties": {
+        "encoding": { "type": "string", "const": "utf8" },
+        "body": {
+          "type": "string",
+          "maxLength": 65536,
+          "description": "Deterministic NDJSON from normalized bootstrap pack (synthesizeQuickInputUtf8FromOpenAiV1)."
+        }
+      }
+    },
+    "readiness": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "reasons"],
+      "properties": {
+        "status": { "type": "string", "enum": ["ready", "review", "blocked"] },
+        "reasons": {
+          "type": "array",
+          "items": { "type": "string", "enum": ["REGISTRY_INVALID", "MERGE_FAILED", "MODEL_NON_JSON", "POINTERS_UNRESOLVED", "ASSUMPTIONS_PRESENT", "WARNINGS_PRESENT", "OK"] }
+        }
+      }
+    },
+    "diagnostics": {
+      "type": "array",
+      "description": "Optional structured hints; typically empty when readiness is ready or review.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["code", "message"],
+        "properties": {
+          "instancePath": { "type": "string" },
+          "code": { "type": "string" },
+          "message": { "type": "string" },
+          "suggestedFix": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/scripts/discovery-payload.lib.cjs

@@ -145,6 +145,8 @@ function buildDiscoveryPayload(root) {
   const llmsBlob = `https://github.com/${owner}/${repo}/blob/${DISCOVERY_LLM_BRANCH}/llms.txt`;
   const integratorGuideSsotRaw = `https://raw.githubusercontent.com/${owner}/${repo}/refs/heads/${DISCOVERY_LLM_BRANCH}/docs/integrate.md`;
   const openapiRaw = `https://raw.githubusercontent.com/${owner}/${repo}/refs/heads/${DISCOVERY_LLM_BRANCH}/schemas/openapi-commercial-v1.yaml`;
+  const contractManifestCanonical = `${canonicalOrigin}/contract/v1.json`;
+  const contractManifestRaw = `https://raw.githubusercontent.com/${owner}/${repo}/refs/heads/${DISCOVERY_LLM_BRANCH}/schemas/contract/v1.json`;
   const llms = /** @type {{ intentPhrases: string[]; notFor: string[]; relatedQueries: string[] }} */ (
     discovery.llms
   );
@@ -164,6 +166,8 @@ function buildDiscoveryPayload(root) {
       llmsRaw,
       llmsBlob,
       integratorGuideSsotRaw,
+      contractManifestCanonical,
+      contractManifestRaw,
     },
     appendix: {
       slug: String(discovery.slug),
@@ -255,6 +259,8 @@ function renderLlmsTextFromPayload(payload) {
     `- Source repository: ${links.repo}`,
     `- npm package: ${links.npm}`,
     `- llms.txt (repo raw): ${links.llmsRaw}`,
+    `- Verification Contract Manifest (canonical): ${links.contractManifestCanonical}`,
+    `- Verification Contract Manifest (repo raw): ${links.contractManifestRaw}`,
     "",
   ];
   const base = lines.join("\n");

package/scripts/emit-primary-marketing.cjs

@@ -29,8 +29,23 @@ const TOKENS = [
   "__DISTRIBUTION_NPM_URL__",
   "__OPENAPI_SELF_URL__",
   "__SERVERS_ORIGIN__",
+  "__CONTRACT_URL__",
+  "__CONTRACT_VERSION__",
+  "__CONTRACT_SHA__",
 ];
 
+const CONTRACT_MANIFEST_PATH = join(ROOT, "schemas", "contract", "v1.json");
+
+function loadContractManifestPin() {
+  const m = JSON.parse(readFileSync(CONTRACT_MANIFEST_PATH, "utf8"));
+  const head = m.history[m.history.length - 1];
+  return {
+    url: String(m.publicUrl),
+    version: String(head.manifestVersion),
+    manifestSha256: String(head.manifestSha256),
+  };
+}
+
 /**
  * @param {string} haystack
  * @param {string} needle
@@ -148,6 +163,8 @@ function writeAgentsMd(anchors, discovery) {
   const branch = dp.DISCOVERY_LLM_BRANCH;
   const llmsRaw = `https://raw.githubusercontent.com/${owner}/${repo}/refs/heads/${branch}/llms.txt`;
   const openapiRaw = `https://raw.githubusercontent.com/${owner}/${repo}/refs/heads/${branch}/schemas/openapi-commercial-v1.yaml`;
+  const contractRaw = `https://raw.githubusercontent.com/${owner}/${repo}/refs/heads/${branch}/schemas/contract/v1.json`;
+  const contractPin = loadContractManifestPin();
   const body = `# AGENTS
 
 Normative **public distribution** and anchor sync: [\`docs/public-distribution.md\`](docs/public-distribution.md) (same content as ${url}).
@@ -157,6 +174,8 @@ Normative **public distribution** and anchor sync: [\`docs/public-distribution.m
 - Committed \`llms.txt\` at repo root (same bytes as site \`/llms.txt\` after prebuild sync).
 - Raw GitHub \`llms.txt\`: ${llmsRaw}
 - OpenAPI YAML (repo raw): ${openapiRaw}
+- Verification Contract Manifest (canonical): ${contractPin.url}
+- Verification Contract Manifest (repo raw): ${contractRaw}
 - Acquisition page (canonical): ${acquisitionUrl}
 `;
   writeFileSync(join(ROOT, "AGENTS.md"), body, "utf8");
@@ -189,6 +208,8 @@ function syncPrimaryMarketing() {
   if (!productSemver) {
     throw new Error("emit-primary-marketing: package.json missing version (OpenAPI __PRODUCT_VERSION__)");
   }
+  const contractPin = loadContractManifestPin();
+
   let mid = template;
   mid = mid.replace(PRODUCT_VERSION_TOKEN, JSON.stringify(productSemver));
   mid = mid.replace("__IDENTITY_ONE_LINER__", escaped);
@@ -196,6 +217,9 @@ function syncPrimaryMarketing() {
   mid = mid.replace("__DISTRIBUTION_INTEGRATE_URL__", integrateUrl);
   mid = mid.replace("__DISTRIBUTION_REPO_URL__", anchors.gitRepositoryUrl);
   mid = mid.replace("__DISTRIBUTION_NPM_URL__", anchors.npmPackageUrl);
+  mid = mid.replace("__CONTRACT_URL__", contractPin.url);
+  mid = mid.replace("__CONTRACT_VERSION__", JSON.stringify(contractPin.version));
+  mid = mid.replace("__CONTRACT_SHA__", JSON.stringify(contractPin.manifestSha256));
 
   const repoYaml = mid
     .replace("__SERVERS_ORIGIN__", canonicalOrigin)
@@ -264,6 +288,7 @@ function syncPrimaryMarketing() {
     `- **Canonical site:** ${canonicalOrigin}`,
     `- **Integrate:** ${integrateUrl}`,
     `- **OpenAPI (canonical):** ${openapiSelfCanonical}`,
+    `- **Verification Contract Manifest:** ${contractPin.url}`,
     `- **llms.txt (agents, site):** ${canonicalOrigin}/llms.txt`,
     `- **llms.txt (repo, raw):** ${pl.llmsRaw}`,
     `- **llms.txt (repo, blob):** ${pl.llmsBlob}`,

package/schemas/registry-draft-response-v2.schema.json

@@ -1,52 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://agentskeptic.com/schemas/registry-draft-response-v2.schema.json",
-  "title": "RegistryDraftResponseEnvelopeV2",
-  "type": "object",
-  "additionalProperties": false,
-  "required": ["schemaVersion", "draft", "assumptions", "warnings", "disclaimer", "model", "quickIngestInput"],
-  "properties": {
-    "schemaVersion": { "type": "integer", "const": 2 },
-    "draft": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["tools"],
-      "properties": {
-        "tools": {
-          "$ref": "https://agentskeptic.com/schemas/tools-registry.schema.json"
-        }
-      }
-    },
-    "assumptions": {
-      "type": "array",
-      "items": { "type": "string" }
-    },
-    "warnings": {
-      "type": "array",
-      "items": { "type": "string" }
-    },
-    "disclaimer": { "type": "string", "minLength": 1 },
-    "model": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["provider", "model"],
-      "properties": {
-        "provider": { "type": "string", "const": "openai" },
-        "model": { "type": "string", "minLength": 1 }
-      }
-    },
-    "quickIngestInput": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["encoding", "body"],
-      "properties": {
-        "encoding": { "type": "string", "const": "utf8" },
-        "body": {
-          "type": "string",
-          "maxLength": 65536,
-          "description": "NDJSON in quick ingest form; same cap tier as HTTP request body for registry-draft."
-        }
-      }
-    }
-  }
-}