@topolo/sdk 0.10.0 → 0.10.2

package/dist/index.cjs

@@ -44,6 +44,10 @@ __export(index_exports, {
   auditAllApplicationRequirements: () => auditAllApplicationRequirements,
   auditApplicationEntries: () => auditApplicationEntries,
   auditApplicationRequirements: () => auditApplicationRequirements,
+  compactActionCatalogEntry: () => compactActionCatalogEntry,
+  compactActionPlan: () => compactActionPlan,
+  compactActionValidation: () => compactActionValidation,
+  compactApplicationAudit: () => compactApplicationAudit,
   createTopolo: () => createTopolo,
   createTopoloWidgetError: () => createTopoloWidgetError,
   createTopoloWidgetResponse: () => createTopoloWidgetResponse,
@@ -3999,6 +4003,54 @@ function mergeSignals(a, b) {
   return controller.signal;
 }
 
+// src/agent-output.ts
+function compactActionCatalogEntry(action) {
+  const required = Array.isArray(action.inputSchema["required"]) ? action.inputSchema["required"].filter((value) => typeof value === "string") : [];
+  const examples = action.agentContract?.examples ?? [];
+  return {
+    actionId: action.actionId,
+    title: action.title,
+    description: action.description,
+    method: action.method,
+    readOnly: action.readOnly,
+    requiresConfirmation: action.requiresConfirmation,
+    agentAccess: action.agentAccess ?? (action.requiresConfirmation ? "confirm" : action.readOnly ? "auto" : "confirm"),
+    requiredPermission: action.requiredPermission,
+    requiredInput: required,
+    resourceType: action.agentContract?.resource?.kind ?? null,
+    exampleInput: examples[0]?.input ?? null,
+    docsUrl: action.agentContract?.docsUrl ?? null
+  };
+}
+function compactActionValidation(actionId, validation) {
+  return { actionId, valid: validation.valid, errors: validation.errors };
+}
+function compactActionPlan(plan) {
+  return {
+    actionId: plan.action.actionId,
+    valid: plan.validation.valid,
+    errors: plan.validation.errors,
+    executable: plan.executable,
+    confirmationRequired: plan.confirmationRequired,
+    confirmationProvided: plan.confirmationProvided,
+    request: plan.request,
+    verification: plan.verification,
+    rollbackActionId: plan.rollbackActionId,
+    nextActionIds: plan.nextActionIds
+  };
+}
+function compactApplicationAudit(report) {
+  return {
+    version: report.version,
+    applications: report.applications.map((audit) => ({
+      applicationId: audit.application.id,
+      applicationName: audit.application.name,
+      score: audit.score
+    })),
+    migrationQueueCount: report.migrationQueue.length
+  };
+}
+
 // src/action-catalog-digest.ts
 var ACTION_CATALOG_DIGEST_ALGORITHM = "sha256-v1";
 function canonicalPermission(value, appId) {
@@ -4212,25 +4264,92 @@ function derivedOutputSchema(action) {
     ...provenance
   };
 }
-function sampleForSchema(schema, depth = 0) {
-  if (!isRecord4(schema) || depth > 5) return null;
+function patternedString(pattern, hint) {
+  const candidates = [
+    hint.toLowerCase().includes("email") ? "agent@topolo.app" : null,
+    hint.toLowerCase().includes("url") || hint.toLowerCase().includes("uri") ? "https://topolo.app" : null,
+    hint.toLowerCase().includes("app") && hint.toLowerCase().includes("id") ? "app_topolo_example" : null,
+    hint.toLowerCase().includes("file") ? "sample.ply" : null,
+    hint.toLowerCase().includes("slug") ? "/sample" : null,
+    hint.toLowerCase().includes("year") ? "2026" : null,
+    hint.toLowerCase().includes("date") || hint.toLowerCase().endsWith("at") ? "2026-01-15T12:00:00Z" : null,
+    hint.toLowerCase().includes("period") || hint.toLowerCase().includes("month") ? "2026-01" : null,
+    hint.toLowerCase().includes("event") || hint.toLowerCase().includes("type") ? "resource.created" : null,
+    "app_topolo_example",
+    "2026-01-15T12:00:00Z",
+    "sample.ply",
+    "/sample",
+    "2026-01-15",
+    "2026-01",
+    "2026",
+    "resource.created",
+    "sample-value",
+    "sample_value",
+    "sample"
+  ].filter(Boolean);
+  try {
+    const expression = new RegExp(pattern);
+    return candidates.find((candidate) => expression.test(candidate)) ?? "sample";
+  } catch {
+    return "sample";
+  }
+}
+function sampleString(schema, hint) {
+  if (schema.format === "email") return "agent@topolo.app";
+  if (schema.format === "uri" || schema.format === "url") return "https://topolo.app";
+  if (schema.format === "date-time") return patternedString(schema.pattern || "", hint) || "2026-01-15T12:00:00Z";
+  const words = String(hint || "value").replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/[_-]+/g, " ").toLowerCase();
+  let value = typeof schema.pattern === "string" ? patternedString(schema.pattern, hint) : /(^|\s)id$/.test(words) ? `${slugify(words.replace(/\sid$/, "") || "resource")}_01` : words.includes("date") ? "2026-01-15" : words.includes("period") || words.includes("month") ? "2026-01" : words.includes("year") ? "2026" : `Sample ${words}`;
+  const minimum = Number.isInteger(schema.minLength) ? schema.minLength : 0;
+  const maximum = Number.isInteger(schema.maxLength) ? schema.maxLength : null;
+  if (value.length < minimum) value = value.padEnd(minimum, "x");
+  if (maximum !== null && value.length > maximum) value = value.slice(0, maximum);
+  return value;
+}
+function localReference(rootSchema, reference) {
+  if (!isRecord4(rootSchema) || typeof reference !== "string" || !reference.startsWith("#/")) return null;
+  return reference.slice(2).split("/").reduce((value, segment) => {
+    const key = segment.replaceAll("~1", "/").replaceAll("~0", "~");
+    return isRecord4(value) ? value[key] : void 0;
+  }, rootSchema);
+}
+function representativeNumber(schema, hint) {
+  const integer = schema.type === "integer";
+  const words = String(hint || "").replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/[_-]+/g, " ").toLowerCase();
+  const preferred = /\b(?:percent|percentage|ratio|rate)\b/.test(words) ? 0.5 : /\b(?:amount|balance|cent|cents|minor)\b/.test(words) ? 1e3 : words.includes("year") ? 2026 : 1;
+  const exclusiveOffset = (value2) => Math.max(Number.EPSILON * Math.max(1, Math.abs(value2)) * 2, Number.MIN_VALUE);
+  const lower = typeof schema.exclusiveMinimum === "number" ? integer ? Math.floor(schema.exclusiveMinimum) + 1 : schema.exclusiveMinimum + exclusiveOffset(schema.exclusiveMinimum) : typeof schema.minimum === "number" ? integer ? Math.ceil(schema.minimum) : schema.minimum : -Infinity;
+  const upper = typeof schema.exclusiveMaximum === "number" ? integer ? Math.ceil(schema.exclusiveMaximum) - 1 : schema.exclusiveMaximum - exclusiveOffset(schema.exclusiveMaximum) : typeof schema.maximum === "number" ? integer ? Math.floor(schema.maximum) : schema.maximum : Infinity;
+  const value = Math.min(Math.max(preferred, lower), upper);
+  return integer ? Math.round(value) : value;
+}
+function sampleForSchema(schema, depth = 0, hint = "value", rootSchema = schema) {
+  if (!isRecord4(schema) || depth > 20) return null;
+  const referenced = localReference(rootSchema, schema.$ref);
+  if (isRecord4(referenced)) return sampleForSchema(referenced, depth + 1, hint, rootSchema);
   if (schema.const !== void 0) return schema.const;
   if (Array.isArray(schema.enum) && schema.enum.length > 0) return schema.enum[0];
-  if (Array.isArray(schema.oneOf) && schema.oneOf.length > 0) return sampleForSchema(schema.oneOf[0], depth + 1);
-  if (Array.isArray(schema.anyOf) && schema.anyOf.length > 0) return sampleForSchema(schema.anyOf[0], depth + 1);
-  if (schema.type === "array") return [];
+  if (Array.isArray(schema.oneOf) && schema.oneOf.length > 0) return sampleForSchema(schema.oneOf[0], depth + 1, hint, rootSchema);
+  if (Array.isArray(schema.anyOf) && schema.anyOf.length > 0) return sampleForSchema(schema.anyOf[0], depth + 1, hint, rootSchema);
+  if (Array.isArray(schema.type)) {
+    return sampleForSchema({ ...schema, type: schema.type.find((type) => type !== "null") ?? schema.type[0] }, depth + 1, hint, rootSchema);
+  }
+  if (schema.type === "array") {
+    const minimum = Number.isInteger(schema.minItems) ? schema.minItems : 0;
+    const maximum = Number.isInteger(schema.maxItems) ? schema.maxItems : null;
+    const count = maximum === 0 ? 0 : minimum > 0 ? minimum : depth >= 4 ? 0 : 1;
+    return Array.from({ length: count }, () => sampleForSchema(schema.items, depth + 1, singularize(hint), rootSchema));
+  }
   if (schema.type === "boolean") return false;
-  if (schema.type === "integer" || schema.type === "number") return schema.minimum ?? 0;
-  if (schema.type === "string") {
-    if (schema.format === "email") return "agent@example.com";
-    if (schema.format === "uri" || schema.format === "url") return "https://example.com";
-    return schema.minLength > 1 ? "example".padEnd(schema.minLength, "x") : "example";
+  if (schema.type === "integer" || schema.type === "number") {
+    return representativeNumber(schema, hint);
   }
+  if (schema.type === "string") return sampleString(schema, hint);
   if (schema.type === "null") return null;
   if (schema.type === "object" || isRecord4(schema.properties)) {
     const properties = isRecord4(schema.properties) ? schema.properties : {};
     const required = new Set(Array.isArray(schema.required) ? schema.required : []);
-    const entries = Object.entries(properties).filter(([key]) => required.has(key)).map(([key, child]) => [key, sampleForSchema(child, depth + 1)]);
+    const entries = Object.entries(properties).filter(([key]) => required.has(key)).map(([key, child]) => [key, sampleForSchema(child, depth + 1, key, rootSchema)]);
     return Object.fromEntries(entries);
   }
   return null;
@@ -4306,7 +4425,11 @@ function enrichActionContract(manifest, action, allActions = manifest.actions ||
   const recovery = isRecord4(existing.recovery) ? existing.recovery : recoveryFor(action, allActions, appId);
   const rollbackActionId = typeof existing.rollbackActionId === "string" && existing.rollbackActionId.trim() ? existing.rollbackActionId.trim() : recovery.mode === "compensating_action" ? recovery.actionId : void 0;
   const inputExample = sampleForSchema(action.inputSchema);
-  const examples = Array.isArray(existing.examples) && existing.examples.length > 0 ? existing.examples : [{ input: inputExample ?? {}, expected: `A response matching the published outputSchema for ${action.name}.` }];
+  const expectedExample = readOnly ? `A successful response conforming to outputSchema; verify the returned ${resource.replaceAll("_", " ")} belongs to the selected resource context.` : `A successful response conforming to outputSchema; re-read the affected ${resource.replaceAll("_", " ")} to verify the intended change.`;
+  const examples = Array.isArray(existing.examples) && existing.examples.length > 0 ? existing.examples.map((example) => isRecord4(example) && Object.hasOwn(example, "input") ? { ...example, expected: typeof example.expected === "string" && example.expected.trim() ? example.expected : expectedExample } : { input: example, expected: expectedExample }) : [{
+    input: inputExample ?? {},
+    expected: expectedExample
+  }];
   const docsUrl = `https://docs.topolo.app/reference/actions?service=${encodeURIComponent(service)}&action=${encodeURIComponent(action.name)}`;
   const existingDocsUrl = typeof existing.docsUrl === "string" && existing.docsUrl.trim() ? existing.docsUrl.trim() : void 0;
   return {
@@ -4952,6 +5075,10 @@ function createTopolo(options) {
   auditAllApplicationRequirements,
   auditApplicationEntries,
   auditApplicationRequirements,
+  compactActionCatalogEntry,
+  compactActionPlan,
+  compactActionValidation,
+  compactApplicationAudit,
   createTopolo,
   createTopoloWidgetError,
   createTopoloWidgetResponse,