@granular-software/sdk 0.4.40 → 0.4.42

package/dist/index.js

@@ -16079,7 +16079,275 @@ var Granular = class _Granular {
   }
 };
 
+// src/agent-harness-templates/action-presentation/0.1.0/manifest.json
+var manifest_default = {
+  id: "action-presentation",
+  version: "0.1.0",
+  status: "candidate",
+  owner: "granular",
+  createdAt: "2026-05-25T00:00:00.000Z",
+  changelog: "Candidate harness template focused on action-request detection and mutation result presentation. It exists to harden cases where the model answers with a terse completion such as Done instead of using tools and reporting the target/action/result.",
+  promptBuilder: "buildGranularAgentSystemPrompt:action-presentation",
+  continuationBuilder: "buildContinuationInstruction:action-presentation",
+  modelOutputInstruction: "agent-evals:modelOutputInstruction",
+  codeReviewPolicy: "reviewGeneratedJobCode",
+  defaultModel: "gpt-5.4",
+  modelMatrix: ["gpt-5.4"],
+  temperature: 0,
+  compatibility: {
+    minSdkVersion: "0.4.40",
+    capabilities: [
+      "executeCode",
+      "readEntities",
+      "workflowHelpers",
+      "savedData",
+      "showRecords"
+    ]
+  },
+  evalGates: {
+    requiredSuites: [
+      "agent-harness-hardening",
+      "agent-harness-runtime-e2e",
+      "agent-production-readiness-e2e"
+    ],
+    criticalBuckets: [
+      "relationship-traversal",
+      "cross-turn-reference",
+      "ambiguous-target-choice",
+      "confirmation-gated-mutation",
+      "denied-action-refusal",
+      "mutation-presentation"
+    ],
+    maxRegressionPct: 0,
+    minPassK: {
+      "critical-mutation": 0.9,
+      "permission-boundary": 1
+    }
+  }
+};
+
+// src/agent-harness-templates/experimental-compact/0.1.0/manifest.json
+var manifest_default2 = {
+  id: "experimental-compact",
+  version: "0.1.0",
+  status: "candidate",
+  owner: "granular",
+  createdAt: "2026-05-24T00:00:00.000Z",
+  changelog: "Candidate harness template used for champion/challenger testing. It adds a compact decision discipline section on top of the stable renderer.",
+  promptBuilder: "buildGranularAgentSystemPrompt:experimental-compact",
+  continuationBuilder: "buildContinuationInstruction:experimental-compact",
+  modelOutputInstruction: "agent-evals:modelOutputInstruction",
+  codeReviewPolicy: "reviewGeneratedJobCode",
+  defaultModel: "gpt-5.4",
+  modelMatrix: ["gpt-5.4"],
+  temperature: 0,
+  compatibility: {
+    minSdkVersion: "0.4.40",
+    capabilities: [
+      "executeCode",
+      "readEntities",
+      "workflowHelpers",
+      "savedData",
+      "showRecords"
+    ]
+  },
+  evalGates: {
+    requiredSuites: [
+      "agent-harness-hardening",
+      "agent-harness-runtime-e2e",
+      "agent-production-readiness-e2e"
+    ],
+    criticalBuckets: [
+      "relationship-traversal",
+      "cross-turn-reference",
+      "ambiguous-target-choice",
+      "confirmation-gated-mutation",
+      "denied-action-refusal",
+      "mutation-presentation"
+    ],
+    maxRegressionPct: 0,
+    minPassK: {
+      "critical-mutation": 0.9,
+      "permission-boundary": 1
+    }
+  }
+};
+
+// src/agent-harness-templates/stable/1.0.0/manifest.json
+var manifest_default3 = {
+  id: "stable",
+  version: "1.0.0",
+  status: "stable",
+  owner: "granular",
+  createdAt: "2026-05-24T00:00:00.000Z",
+  changelog: "Baseline template wrapping the existing Granular agent harness prompt, continuation instruction, output contract, and generated-job review policy.",
+  promptBuilder: "buildGranularAgentSystemPrompt",
+  continuationBuilder: "buildContinuationInstruction",
+  modelOutputInstruction: "agent-evals:modelOutputInstruction",
+  codeReviewPolicy: "reviewGeneratedJobCode",
+  defaultModel: "gpt-5.4",
+  modelMatrix: ["gpt-5.4"],
+  temperature: 0,
+  compatibility: {
+    minSdkVersion: "0.4.40",
+    capabilities: [
+      "executeCode",
+      "readEntities",
+      "workflowHelpers",
+      "savedData",
+      "showRecords"
+    ]
+  },
+  evalGates: {
+    requiredSuites: [
+      "agent-harness-hardening",
+      "agent-harness-runtime-e2e",
+      "agent-production-readiness-e2e"
+    ],
+    criticalBuckets: [
+      "relationship-traversal",
+      "cross-turn-reference",
+      "ambiguous-target-choice",
+      "confirmation-gated-mutation",
+      "denied-action-refusal",
+      "mutation-presentation"
+    ],
+    maxRegressionPct: 0,
+    minPassK: {
+      "critical-mutation": 0.9,
+      "permission-boundary": 1
+    }
+  }
+};
+
 // src/agent-harness.ts
+var HARNESS_TEMPLATE_STATUSES = [
+  "draft",
+  "candidate",
+  "release-candidate",
+  "stable",
+  "deprecated"
+];
+function requireRecord(value, context) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${context} must be an object.`);
+  }
+  return value;
+}
+function requiredString(record, key, context) {
+  const value = record[key];
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error(`${context}.${key} must be a non-empty string.`);
+  }
+  return value;
+}
+function requiredNumber(record, key, context) {
+  const value = record[key];
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new Error(`${context}.${key} must be a finite number.`);
+  }
+  return value;
+}
+function requiredStringArray(record, key, context) {
+  const value = record[key];
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || !item.trim())) {
+    throw new Error(`${context}.${key} must be an array of non-empty strings.`);
+  }
+  return [...value];
+}
+function requiredNumberRecord(record, key, context) {
+  const value = requireRecord(record[key], `${context}.${key}`);
+  const output = {};
+  for (const [entryKey, entryValue] of Object.entries(value)) {
+    if (typeof entryValue !== "number" || !Number.isFinite(entryValue) || entryValue < 0 || entryValue > 1) {
+      throw new Error(
+        `${context}.${key}.${entryKey} must be a number between 0 and 1.`
+      );
+    }
+    output[entryKey] = entryValue;
+  }
+  return output;
+}
+function validateHarnessTemplateManifest(value, context = "HarnessTemplateManifest") {
+  const record = requireRecord(value, context);
+  const status = requiredString(record, "status", context);
+  if (!HARNESS_TEMPLATE_STATUSES.includes(status)) {
+    throw new Error(
+      `${context}.status must be one of ${HARNESS_TEMPLATE_STATUSES.join(", ")}.`
+    );
+  }
+  const createdAt = requiredString(record, "createdAt", context);
+  if (Number.isNaN(Date.parse(createdAt))) {
+    throw new Error(`${context}.createdAt must be an ISO timestamp.`);
+  }
+  const compatibility = requireRecord(
+    record.compatibility,
+    `${context}.compatibility`
+  );
+  const evalGates = requireRecord(record.evalGates, `${context}.evalGates`);
+  const maxRegressionPct = requiredNumber(
+    evalGates,
+    "maxRegressionPct",
+    `${context}.evalGates`
+  );
+  if (maxRegressionPct < 0 || maxRegressionPct > 1) {
+    throw new Error(
+      `${context}.evalGates.maxRegressionPct must be between 0 and 1.`
+    );
+  }
+  return {
+    id: requiredString(record, "id", context),
+    version: requiredString(record, "version", context),
+    status,
+    owner: requiredString(record, "owner", context),
+    createdAt,
+    changelog: requiredString(record, "changelog", context),
+    promptBuilder: requiredString(record, "promptBuilder", context),
+    continuationBuilder: requiredString(record, "continuationBuilder", context),
+    modelOutputInstruction: requiredString(
+      record,
+      "modelOutputInstruction",
+      context
+    ),
+    codeReviewPolicy: requiredString(record, "codeReviewPolicy", context),
+    defaultModel: requiredString(record, "defaultModel", context),
+    modelMatrix: requiredStringArray(record, "modelMatrix", context),
+    temperature: requiredNumber(record, "temperature", context),
+    compatibility: {
+      minSdkVersion: requiredString(
+        compatibility,
+        "minSdkVersion",
+        `${context}.compatibility`
+      ),
+      capabilities: requiredStringArray(
+        compatibility,
+        "capabilities",
+        `${context}.compatibility`
+      )
+    },
+    evalGates: {
+      requiredSuites: requiredStringArray(
+        evalGates,
+        "requiredSuites",
+        `${context}.evalGates`
+      ),
+      criticalBuckets: requiredStringArray(
+        evalGates,
+        "criticalBuckets",
+        `${context}.evalGates`
+      ),
+      maxRegressionPct,
+      minPassK: requiredNumberRecord(
+        evalGates,
+        "minPassK",
+        `${context}.evalGates`
+      )
+    }
+  };
+}
+function defineHarnessTemplateManifest(value, context) {
+  return validateHarnessTemplateManifest(value, context);
+}
 var DEFAULT_IGNORED_REASONING_COMMENT_DIRECTIVES = [
   /^@ts-ignore\b/i,
   /^@ts-expect-error\b/i,
@@ -16182,6 +16450,16 @@ function uniqueStrings(values, maxCount) {
   }
   return output;
 }
+function stableStringify(value) {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((entry) => stableStringify(entry)).join(",")}]`;
+  }
+  const record = value;
+  return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`).join(",")}}`;
+}
 function renderConstBlock(name, value) {
   return `const ${name} = ${JSON.stringify(value, null, 2)} as const;`;
 }
@@ -18126,6 +18404,194 @@ ${knownFactsBlock}
 [Request]
 ${input.request?.trim() || "Use the latest user message in the conversation."}`;
 }
+var STABLE_AGENT_HARNESS_TEMPLATE_MANIFEST = defineHarnessTemplateManifest(
+  manifest_default3,
+  "stable@1.0.0 manifest"
+);
+function hashHarnessTemplateValue(value) {
+  return hashString(stableStringify(value)) || "00000000";
+}
+function renderStableHarnessPrompt(input) {
+  const prompt = buildGranularAgentSystemPrompt(input);
+  const templateHash = hashHarnessTemplateValue(
+    STABLE_AGENT_HARNESS_TEMPLATE_MANIFEST
+  );
+  return {
+    templateId: STABLE_AGENT_HARNESS_TEMPLATE_MANIFEST.id,
+    templateVersion: STABLE_AGENT_HARNESS_TEMPLATE_MANIFEST.version,
+    templateHash,
+    promptInstanceHash: hashHarnessTemplateValue({
+      templateHash,
+      input,
+      prompt
+    }),
+    prompt
+  };
+}
+function renderStableHarnessContinuation(resultPreview) {
+  const instruction = buildContinuationInstruction(resultPreview);
+  const templateHash = hashHarnessTemplateValue(
+    STABLE_AGENT_HARNESS_TEMPLATE_MANIFEST
+  );
+  return {
+    templateId: STABLE_AGENT_HARNESS_TEMPLATE_MANIFEST.id,
+    templateVersion: STABLE_AGENT_HARNESS_TEMPLATE_MANIFEST.version,
+    templateHash,
+    instruction
+  };
+}
+var STABLE_AGENT_HARNESS_TEMPLATE = {
+  manifest: STABLE_AGENT_HARNESS_TEMPLATE_MANIFEST,
+  renderPrompt: renderStableHarnessPrompt,
+  renderContinuation: renderStableHarnessContinuation
+};
+var EXPERIMENTAL_COMPACT_AGENT_HARNESS_TEMPLATE_MANIFEST = defineHarnessTemplateManifest(
+  manifest_default2,
+  "experimental-compact@0.1.0 manifest"
+);
+function renderExperimentalCompactHarnessPrompt(input) {
+  const prompt = `${buildGranularAgentSystemPrompt(input)}
+
+[Candidate Harness Delta: Compact Decision Discipline]
+- Prefer the smallest action that satisfies the current request.
+- When several records could match, ask one structured choice question before mutating.
+- Before any irreversible or outbound mutation, obtain explicit confirmation unless the policy surface already requires it.
+- Do not compensate for missing tools with raw network calls, synthetic records, or hidden side channels.
+- Keep the final user-facing reply focused on what was done, what was not done, and any remaining blocker.`;
+  const templateHash = hashHarnessTemplateValue(
+    EXPERIMENTAL_COMPACT_AGENT_HARNESS_TEMPLATE_MANIFEST
+  );
+  return {
+    templateId: EXPERIMENTAL_COMPACT_AGENT_HARNESS_TEMPLATE_MANIFEST.id,
+    templateVersion: EXPERIMENTAL_COMPACT_AGENT_HARNESS_TEMPLATE_MANIFEST.version,
+    templateHash,
+    promptInstanceHash: hashHarnessTemplateValue({
+      templateHash,
+      input,
+      prompt
+    }),
+    prompt
+  };
+}
+function renderExperimentalCompactHarnessContinuation(resultPreview) {
+  const instruction = `${buildContinuationInstruction(resultPreview)}
+
+Keep the continuation compact: either finish, ask the one blocking question, or run the next smallest safe action.`;
+  const templateHash = hashHarnessTemplateValue(
+    EXPERIMENTAL_COMPACT_AGENT_HARNESS_TEMPLATE_MANIFEST
+  );
+  return {
+    templateId: EXPERIMENTAL_COMPACT_AGENT_HARNESS_TEMPLATE_MANIFEST.id,
+    templateVersion: EXPERIMENTAL_COMPACT_AGENT_HARNESS_TEMPLATE_MANIFEST.version,
+    templateHash,
+    instruction
+  };
+}
+var EXPERIMENTAL_COMPACT_AGENT_HARNESS_TEMPLATE = {
+  manifest: EXPERIMENTAL_COMPACT_AGENT_HARNESS_TEMPLATE_MANIFEST,
+  renderPrompt: renderExperimentalCompactHarnessPrompt,
+  renderContinuation: renderExperimentalCompactHarnessContinuation
+};
+var ACTION_PRESENTATION_AGENT_HARNESS_TEMPLATE_MANIFEST = defineHarnessTemplateManifest(
+  manifest_default,
+  "action-presentation@0.1.0 manifest"
+);
+function renderActionPresentationHarnessPrompt(input) {
+  const prompt = `${buildGranularAgentSystemPrompt(input)}
+
+[Candidate Harness Delta: Action Request And Result Presentation]
+- Treat requests like "handle it", "take care of it", "send it", "update it", "fix it", "process it", or "do it" as action requests when the message names a business object, target, workflow, or mutation verb.
+- For action requests involving session data, generated files, records, effects, or workflows, do not use text-only completion. Generate and run code, ask the blocking human question, or clearly refuse if policy/tooling prevents the action.
+- Never answer only "Done", "OK", "Handled", or similar terse completion text for a mutation request. The final user-facing reply must name the action attempted, the grounded target or blocker, and the actual result.
+- After a mutation/effect call, base the reply on the returned action result and include a visible target label or identifier when one exists.
+- If no target can be grounded, say what was searched and what exact identifier or choice is needed; do not pretend the action completed.`;
+  const templateHash = hashHarnessTemplateValue(
+    ACTION_PRESENTATION_AGENT_HARNESS_TEMPLATE_MANIFEST
+  );
+  return {
+    templateId: ACTION_PRESENTATION_AGENT_HARNESS_TEMPLATE_MANIFEST.id,
+    templateVersion: ACTION_PRESENTATION_AGENT_HARNESS_TEMPLATE_MANIFEST.version,
+    templateHash,
+    promptInstanceHash: hashHarnessTemplateValue({
+      templateHash,
+      input,
+      prompt
+    }),
+    prompt
+  };
+}
+function renderActionPresentationHarnessContinuation(resultPreview) {
+  const instruction = `${buildContinuationInstruction(resultPreview)}
+
+Before finishing, check whether the latest user request asked for an action. If it did, do not finish with a bare completion token; either continue with the needed tool/code step, ask the blocking question, refuse with the policy reason, or report the grounded action result with the target label.`;
+  const templateHash = hashHarnessTemplateValue(
+    ACTION_PRESENTATION_AGENT_HARNESS_TEMPLATE_MANIFEST
+  );
+  return {
+    templateId: ACTION_PRESENTATION_AGENT_HARNESS_TEMPLATE_MANIFEST.id,
+    templateVersion: ACTION_PRESENTATION_AGENT_HARNESS_TEMPLATE_MANIFEST.version,
+    templateHash,
+    instruction
+  };
+}
+var ACTION_PRESENTATION_AGENT_HARNESS_TEMPLATE = {
+  manifest: ACTION_PRESENTATION_AGENT_HARNESS_TEMPLATE_MANIFEST,
+  renderPrompt: renderActionPresentationHarnessPrompt,
+  renderContinuation: renderActionPresentationHarnessContinuation
+};
+var AGENT_HARNESS_TEMPLATES = {
+  [STABLE_AGENT_HARNESS_TEMPLATE.manifest.id]: STABLE_AGENT_HARNESS_TEMPLATE,
+  [EXPERIMENTAL_COMPACT_AGENT_HARNESS_TEMPLATE.manifest.id]: EXPERIMENTAL_COMPACT_AGENT_HARNESS_TEMPLATE,
+  [ACTION_PRESENTATION_AGENT_HARNESS_TEMPLATE.manifest.id]: ACTION_PRESENTATION_AGENT_HARNESS_TEMPLATE
+};
+function listHarnessTemplates() {
+  return Object.values(AGENT_HARNESS_TEMPLATES).map((template) => ({
+    ...template.manifest,
+    compatibility: { ...template.manifest.compatibility },
+    evalGates: {
+      ...template.manifest.evalGates,
+      minPassK: { ...template.manifest.evalGates.minPassK }
+    }
+  }));
+}
+function resolveHarnessTemplate(templateId = "stable", options) {
+  const resolved = AGENT_HARNESS_TEMPLATES[templateId];
+  if (resolved) return resolved;
+  if (options?.strict) {
+    const known = Object.keys(AGENT_HARNESS_TEMPLATES).join(", ");
+    throw new Error(
+      `Unknown harness template "${templateId}". Known templates: ${known}`
+    );
+  }
+  return STABLE_AGENT_HARNESS_TEMPLATE;
+}
+function getDefaultHarnessTemplateId() {
+  if (typeof process !== "undefined") {
+    const configured = process.env.GRANULAR_AGENT_HARNESS_TEMPLATE || process.env.NEXT_PUBLIC_GRANULAR_AGENT_HARNESS_TEMPLATE;
+    if (configured?.trim()) return configured.trim();
+  }
+  return "stable";
+}
+function renderGranularAgentSystemPromptFromTemplate(input, options) {
+  const template = resolveHarnessTemplate(
+    options?.templateId || getDefaultHarnessTemplateId(),
+    { strict: options?.strict ?? true }
+  );
+  return template.renderPrompt(input);
+}
+function buildGranularAgentSystemPromptFromTemplate(input, options) {
+  return renderGranularAgentSystemPromptFromTemplate(input, options).prompt;
+}
+function renderContinuationInstructionFromTemplate(resultPreview, options) {
+  const template = resolveHarnessTemplate(
+    options?.templateId || getDefaultHarnessTemplateId(),
+    { strict: options?.strict ?? true }
+  );
+  return template.renderContinuation(resultPreview);
+}
+function buildContinuationInstructionFromTemplate(resultPreview, options) {
+  return renderContinuationInstructionFromTemplate(resultPreview, options).instruction;
+}
 
 // src/openai-usage.ts
 var OPENAI_PRICING_SOURCE_URL = "https://developers.openai.com/api/docs/models/gpt-5.4/";
@@ -18230,6 +18696,7 @@ exports.OntologyHandle = OntologyHandle;
 exports.Session = Session;
 exports.WSClient = WSClient;
 exports.buildContinuationInstruction = buildContinuationInstruction;
+exports.buildContinuationInstructionFromTemplate = buildContinuationInstructionFromTemplate;
 exports.buildGranularAgentCheckpointBlock = buildGranularAgentCheckpointBlock;
 exports.buildGranularAgentDomainBlock = buildGranularAgentDomainBlock;
 exports.buildGranularAgentFileBlock = buildGranularAgentFileBlock;
@@ -18239,6 +18706,7 @@ exports.buildGranularAgentReferentBlock = buildGranularAgentReferentBlock;
 exports.buildGranularAgentRuntimeImportsBlock = buildGranularAgentRuntimeImportsBlock;
 exports.buildGranularAgentSessionBlock = buildGranularAgentSessionBlock;
 exports.buildGranularAgentSystemPrompt = buildGranularAgentSystemPrompt;
+exports.buildGranularAgentSystemPromptFromTemplate = buildGranularAgentSystemPromptFromTemplate;
 exports.buildGranularAgentToolBlock = buildGranularAgentToolBlock;
 exports.buildGranularAgentWorkflowBlock = buildGranularAgentWorkflowBlock;
 exports.buildOpenAISpendEventId = buildOpenAISpendEventId;
@@ -18250,11 +18718,14 @@ exports.createHarnessVerifierSnapshot = createHarnessVerifierSnapshot;
 exports.evaluateContinuation = evaluateContinuation;
 exports.extractPromptTokens = extractPromptTokens;
 exports.getCurrentClosureId = getCurrentClosureId;
+exports.getDefaultHarnessTemplateId = getDefaultHarnessTemplateId;
 exports.getExclusivePromptTarget = getExclusivePromptTarget;
 exports.getOpenAIModelPricing = getOpenAIModelPricing;
 exports.hasOpenPrompt = hasOpenPrompt;
+exports.hashHarnessTemplateValue = hashHarnessTemplateValue;
 exports.invokeRegisteredEffect = invokeRegisteredEffect;
 exports.isLocalApiUrl = isLocalApiUrl;
+exports.listHarnessTemplates = listHarnessTemplates;
 exports.normalizeEffectBehaviors = normalizeEffectBehaviors;
 exports.normalizeOpenAIUsage = normalizeOpenAIUsage;
 exports.normalizePrompt = normalizePrompt;
@@ -18269,13 +18740,17 @@ exports.projectSessionFileSummary = projectSessionFileSummary;
 exports.projectWorkflowFocus = projectWorkflowFocus;
 exports.projectWorkflowSummary = projectWorkflowSummary;
 exports.recordOpenAIUsageSpend = recordOpenAIUsageSpend;
+exports.renderContinuationInstructionFromTemplate = renderContinuationInstructionFromTemplate;
+exports.renderGranularAgentSystemPromptFromTemplate = renderGranularAgentSystemPromptFromTemplate;
 exports.resolveApiUrl = resolveApiUrl;
 exports.resolveAuthTokenForApiUrl = resolveAuthTokenForApiUrl;
+exports.resolveHarnessTemplate = resolveHarnessTemplate;
 exports.resolveJobPresentation = resolveJobPresentation;
 exports.resolvePromptAnswer = resolvePromptAnswer;
 exports.reviewGeneratedJobCode = reviewGeneratedJobCode;
 exports.scorePromptChoiceMatch = scorePromptChoiceMatch;
 exports.stripGranularReasoningTrace = stripGranularReasoningTrace;
 exports.toGranularHttpBase = toGranularHttpBase;
+exports.validateHarnessTemplateManifest = validateHarnessTemplateManifest;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map