@clue-ai/cli 0.0.6 → 0.0.8

package/src/semantic-agent-runner.mjs

@@ -0,0 +1,157 @@
+export const SEMANTIC_AGENT_RUNNER_VERSION = "semantic-agent-runner-v1";
+
+export const SEMANTIC_AGENT_ROLE_IDS = {
+  routeInventory: "route_inventory",
+  reuseJudge: "semantic_reuse_judge",
+  routeSemanticGenerator: "route_semantic_generator",
+  semanticSelector: "semantic_selector",
+  semanticAuditor: "semantic_auditor",
+  snapshotFinalizer: "snapshot_finalizer",
+};
+
+const requiredRoleIds = new Set(Object.values(SEMANTIC_AGENT_ROLE_IDS));
+
+export const semanticAgentSkillBundle = () => ({
+  runner_version: SEMANTIC_AGENT_RUNNER_VERSION,
+  execution_model: "ci_semantic_agent_runner",
+  ci_entrypoint: "clue-ai semantic-gen",
+  rules: [
+    "GitHub Actions runs only the CLI; the CLI owns route coverage, AI role orchestration, schema validation, and upload.",
+    "Mechanically scan every route before any AI call.",
+    "Use AI only for semantic judgment: reuse decision, route semantics, and semantic field selection.",
+    "Never use AI to decide whether a discovered route can be skipped.",
+    "Fail closed when the previous snapshot cannot be loaded, unless explicit full regeneration is enabled.",
+    "Persist only schema-validated, privacy-safe semantic snapshot payloads.",
+  ],
+  roles: [
+    {
+      id: SEMANTIC_AGENT_ROLE_IDS.routeInventory,
+      kind: "mechanical",
+      responsibility:
+        "Discover every backend route and produce deterministic operation_source_key values before AI execution.",
+      ai_allowed: false,
+      output_contract: "deterministic_route_inventory",
+    },
+    {
+      id: SEMANTIC_AGENT_ROLE_IDS.reuseJudge,
+      kind: "ai",
+      responsibility:
+        "Judge whether a changed route can safely keep its previous privacy-safe semantics.",
+      ai_allowed: true,
+      output_contract: "return_reuse_decision",
+      failure_policy: "needs_review",
+    },
+    {
+      id: SEMANTIC_AGENT_ROLE_IDS.routeSemanticGenerator,
+      kind: "ai",
+      responsibility:
+        "Generate privacy-safe route semantic candidates for new or changed routes only.",
+      ai_allowed: true,
+      output_contract: "return_route_semantics",
+      failure_policy: "fallback_unknown_route_semantics",
+    },
+    {
+      id: SEMANTIC_AGENT_ROLE_IDS.semanticSelector,
+      kind: "ai",
+      responsibility:
+        "Select adopted semantic fields from deterministic and AI candidates without inventing ids, hashes, paths, or raw code.",
+      ai_allowed: true,
+      output_contract: "return_semantic_selection",
+      failure_policy: "fail_snapshot_generation",
+    },
+    {
+      id: SEMANTIC_AGENT_ROLE_IDS.semanticAuditor,
+      kind: "mechanical",
+      responsibility:
+        "Verify route coverage, privacy boundaries, generation contract, and snapshot schema before upload.",
+      ai_allowed: false,
+      output_contract: "deterministic_audit_result",
+    },
+    {
+      id: SEMANTIC_AGENT_ROLE_IDS.snapshotFinalizer,
+      kind: "mechanical",
+      responsibility:
+        "Finalize content-based snapshot version, idempotency key, and Clue API upload payload.",
+      ai_allowed: false,
+      output_contract: "semantic_snapshot_request",
+    },
+  ],
+});
+
+export const validateSemanticAgentSkillBundle = (bundle) => {
+  if (!bundle || typeof bundle !== "object") {
+    throw new Error("semantic agent skill bundle must be an object");
+  }
+  if (bundle.runner_version !== SEMANTIC_AGENT_RUNNER_VERSION) {
+    throw new Error(
+      `semantic agent skill bundle runner_version must be ${SEMANTIC_AGENT_RUNNER_VERSION}`,
+    );
+  }
+  if (bundle.execution_model !== "ci_semantic_agent_runner") {
+    throw new Error(
+      "semantic agent skill bundle execution_model must be ci_semantic_agent_runner",
+    );
+  }
+  if (!Array.isArray(bundle.roles)) {
+    throw new Error("semantic agent skill bundle roles must be an array");
+  }
+  const roleIds = new Set();
+  for (const role of bundle.roles) {
+    if (!role || typeof role !== "object") {
+      throw new Error("semantic agent skill bundle contains an invalid role");
+    }
+    if (typeof role.id !== "string" || !requiredRoleIds.has(role.id)) {
+      throw new Error(`semantic agent skill bundle contains unknown role`);
+    }
+    if (roleIds.has(role.id)) {
+      throw new Error(`semantic agent skill bundle contains duplicate role`);
+    }
+    roleIds.add(role.id);
+    if (role.kind !== "ai" && role.kind !== "mechanical") {
+      throw new Error(`semantic agent role ${role.id} has invalid kind`);
+    }
+    if (
+      typeof role.responsibility !== "string" ||
+      role.responsibility.trim() === ""
+    ) {
+      throw new Error(
+        `semantic agent role ${role.id} must describe its responsibility`,
+      );
+    }
+  }
+  const missingRoles = [...requiredRoleIds].filter((roleId) => !roleIds.has(roleId));
+  if (missingRoles.length > 0) {
+    throw new Error(
+      `semantic agent skill bundle missing roles: ${missingRoles.join(",")}`,
+    );
+  }
+  return bundle;
+};
+
+export const semanticAgentRole = ({ bundle, roleId }) => {
+  const validated = validateSemanticAgentSkillBundle(bundle);
+  const role = validated.roles.find((entry) => entry.id === roleId);
+  if (!role) {
+    throw new Error(`semantic agent role is not available: ${roleId}`);
+  }
+  return role;
+};
+
+export const semanticAgentPromptEnvelope = ({ bundle, roleId }) => {
+  const role = semanticAgentRole({ bundle, roleId });
+  return {
+    agent_runner: {
+      runner_version: bundle.runner_version,
+      execution_model: bundle.execution_model,
+      ci_entrypoint: bundle.ci_entrypoint,
+    },
+    agent_role: {
+      id: role.id,
+      kind: role.kind,
+      responsibility: role.responsibility,
+      output_contract: role.output_contract,
+      failure_policy: role.failure_policy ?? null,
+    },
+    coordination_rules: bundle.rules,
+  };
+};

package/src/semantic-ai-config.mjs

@@ -0,0 +1,17 @@
+export const CLUE_CLIENT_CI_SEMANTIC_AI_MODE = "client_ci";
+export const CLUE_CLIENT_CI_SEMANTIC_AI_MODEL_SOURCE = "customer_ci_secret";
+
+export const clueClientCiSemanticAiRuntime = ({
+  provider,
+  model,
+  roleIds,
+  runnerVersion,
+}) => ({
+  mode: CLUE_CLIENT_CI_SEMANTIC_AI_MODE,
+  provider,
+  model,
+  model_source: CLUE_CLIENT_CI_SEMANTIC_AI_MODEL_SOURCE,
+  runner_version: runnerVersion,
+  role_ids: roleIds,
+  temperature: 0,
+});