@standardagents/spec 0.40.12 → 0.41.0

package/dist/index.js

@@ -283,104 +283,404 @@ function defineEffect(description, argsOrHandler, maybeHandler) {
   ];
 }
 
-// src/agents.ts
-function defineAgent(options) {
-  const validateSessionBinding = (sideLabel, sessionKey) => {
-    const side = options[sideLabel];
-    if (!side) return;
-    const sessionBinding = side[sessionKey];
-    if (typeof sessionBinding === "object" && sessionBinding !== null && !Array.isArray(sessionBinding)) {
-      if (!("name" in sessionBinding) || typeof sessionBinding.name !== "string" || !sessionBinding.name) {
-        throw new Error(`${sideLabel}.${sessionKey}.name is required when ${sideLabel}.${sessionKey} uses object form`);
-      }
-    }
-  };
-  if (!options.name) {
-    throw new Error("Agent name is required");
+// src/handlers.ts
+var HANDLER_SYMBOL = Symbol.for("standardagents.handler");
+function defineHandler(options) {
+  if (!options || typeof options !== "object") {
+    throw new Error("defineHandler requires an options object");
   }
-  if (options.name.includes("/")) {
-    throw new Error(`Agent name cannot contain '/'. Reserved for namespace qualification.`);
+  if (typeof options.execute !== "function") {
+    throw new Error("Handler execute function is required");
   }
-  if (!options.sideA) {
-    throw new Error("Agent sideA configuration is required");
+  if (options.description !== void 0 && typeof options.description !== "string") {
+    throw new Error("Handler description must be a string when provided");
   }
-  if (!options.sideA.prompt) {
-    throw new Error("Agent sideA.prompt is required");
+  return {
+    ...options,
+    [HANDLER_SYMBOL]: true
+  };
+}
+function isHandler(value) {
+  return typeof value === "object" && value !== null && HANDLER_SYMBOL in value && value[HANDLER_SYMBOL] === true;
+}
+
+// src/validation.ts
+var DEFINITION_ISSUE_CODES = [
+  "agent_name_missing",
+  "agent_name_invalid",
+  "agent_side_missing",
+  "agent_side_invalid",
+  "agent_side_backing_missing",
+  "agent_side_backing_conflict",
+  "agent_side_option_invalid_for_backing",
+  "agent_subagents_on_human_side",
+  "agent_both_sides_human",
+  "agent_legacy_type",
+  "agent_session_binding_legacy_string",
+  "agent_session_binding_invalid",
+  "agent_stop_tool_response_property_missing",
+  "agent_max_steps_invalid",
+  "agent_max_session_turns_invalid",
+  "agent_tool_description_missing",
+  "agent_parent_hooks_invalid",
+  "agent_tenvs_deprecated",
+  "subagent_agent_missing",
+  "subagent_relationship_invalid",
+  "subagent_relationship_duplicate",
+  "subagent_relationship_reserved_name",
+  "subagent_max_instances_invalid",
+  "subagent_legacy_name",
+  "subagent_legacy_resumable",
+  "subagent_legacy_receives_messages"
+];
+var RESERVED_RELATIONSHIP_NAMES = [
+  "subagents",
+  "subagent_create",
+  "subagent_message"
+];
+var MIGRATION_URL = "https://standardagentspec.com/0.2.0/getting-started/changelog";
+var RESERVED_NAMES = new Set(
+  RESERVED_RELATIONSHIP_NAMES
+);
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+var BACKING_KEYS = ["human", "prompt", "handler"];
+var PROMPT_ONLY_SIDE_KEYS = [
+  "stopOnResponse",
+  "stopTool",
+  "stopToolResponseProperty",
+  "maxSteps",
+  "sessionStop",
+  "sessionFail",
+  "sessionStatus"
+];
+function backingOf(side) {
+  const present = BACKING_KEYS.filter((key) => side[key] !== void 0);
+  return present.length === 1 ? present[0] : null;
+}
+function validateAgentDefinition(def) {
+  const issues = [];
+  const error = (code, path, message) => {
+    issues.push({ code, severity: "error", message, path });
+  };
+  const warning = (code, path, message) => {
+    issues.push({ code, severity: "warning", message, path });
+  };
+  if (!isRecord(def)) {
+    error("agent_side_invalid", "", "Agent definition must be an object");
+    return issues;
+  }
+  if (typeof def.name !== "string" || !def.name) {
+    error("agent_name_missing", "name", "Agent name is required");
+  } else if (def.name.includes("/")) {
+    error(
+      "agent_name_invalid",
+      "name",
+      `Agent name cannot contain '/'. Reserved for namespace qualification.`
+    );
+  }
+  if (def.type !== void 0) {
+    error(
+      "agent_legacy_type",
+      "type",
+      `'type' was removed in 0.2.0 \u2014 there is no agent type. Delete it and declare both sides explicitly: 'ai_human' becomes sideB: { human: true }; 'dual_ai' is two prompt-backed sides. ${MIGRATION_URL}`
+    );
   }
-  const type = options.type ?? "ai_human";
-  if (type === "dual_ai") {
-    if (!options.sideB) {
-      throw new Error("Agent sideB configuration is required for dual_ai type");
+  const relationshipOwners = /* @__PURE__ */ new Map();
+  for (const sideKey of ["sideA", "sideB"]) {
+    const side = def[sideKey];
+    if (side === void 0) {
+      error(
+        "agent_side_missing",
+        sideKey,
+        `${sideKey} is required \u2014 both sides are always explicit. A chat agent's human side is ${sideKey}: { human: true }.`
+      );
+      continue;
     }
-    if (!options.sideB.prompt) {
-      throw new Error("Agent sideB.prompt is required for dual_ai type");
+    if (!isRecord(side)) {
+      error("agent_side_invalid", sideKey, `${sideKey} must be an object`);
+      continue;
     }
-  }
-  if (options.exposeAsTool && !options.toolDescription) {
-    throw new Error("toolDescription is required when exposeAsTool is true");
-  }
-  if (options.sideA.stopTool && !options.sideA.stopToolResponseProperty) {
-    throw new Error("sideA.stopToolResponseProperty is required when sideA.stopTool is set");
-  }
-  if (options.sideB?.stopTool && !options.sideB.stopToolResponseProperty) {
-    throw new Error("sideB.stopToolResponseProperty is required when sideB.stopTool is set");
-  }
-  if (options.sideA.maxSteps !== void 0 && options.sideA.maxSteps <= 0) {
-    throw new Error("sideA.maxSteps must be a positive number");
-  }
-  if (options.sideB?.maxSteps !== void 0 && options.sideB.maxSteps <= 0) {
-    throw new Error("sideB.maxSteps must be a positive number");
-  }
-  if (options.maxSessionTurns !== void 0 && options.maxSessionTurns !== null && options.maxSessionTurns <= 0) {
-    throw new Error("maxSessionTurns must be a positive number");
-  }
-  if (!["ai_human", "dual_ai"].includes(type)) {
-    throw new Error(`Invalid type '${type}'. Must be one of: ai_human, dual_ai`);
-  }
-  if (options.parentHooks !== void 0) {
-    if (!Array.isArray(options.parentHooks)) {
-      throw new Error("parentHooks must be an array");
+    const backing = backingOf(side);
+    if (backing === null) {
+      const present = BACKING_KEYS.filter((key) => side[key] !== void 0);
+      if (present.length === 0) {
+        error(
+          "agent_side_backing_missing",
+          sideKey,
+          `${sideKey} must be backed by exactly one of 'human', 'prompt', or 'handler'`
+        );
+      } else {
+        error(
+          "agent_side_backing_conflict",
+          sideKey,
+          `${sideKey} declares more than one backing (${present.join(", ")}); a side is backed by exactly one of 'human', 'prompt', or 'handler'`
+        );
+      }
+      continue;
+    }
+    if (backing === "human" && side.human !== true) {
+      error(
+        "agent_side_invalid",
+        `${sideKey}.human`,
+        `${sideKey}.human must be exactly true`
+      );
+    }
+    if (backing === "prompt" && (typeof side.prompt !== "string" || !side.prompt)) {
+      error(
+        "agent_side_invalid",
+        `${sideKey}.prompt`,
+        `${sideKey}.prompt must be a non-empty prompt name`
+      );
     }
-    if (type !== "dual_ai") {
-      throw new Error("parentHooks may only be declared by dual_ai agents");
+    if (backing === "handler" && (typeof side.handler !== "string" || !side.handler)) {
+      error(
+        "agent_side_invalid",
+        `${sideKey}.handler`,
+        `${sideKey}.handler must be a non-empty handler name`
+      );
     }
-    if (!options.exposeAsTool) {
-      throw new Error("parentHooks requires exposeAsTool: true");
+    if (backing !== "prompt") {
+      for (const key of PROMPT_ONLY_SIDE_KEYS) {
+        if (side[key] !== void 0) {
+          error(
+            "agent_side_option_invalid_for_backing",
+            `${sideKey}.${key}`,
+            backing === "human" ? `'${key}' is not legal on a human-backed side` : `'${key}' is not legal on a handler-backed side \u2014 a handler turn has no steps to cap and ends when execute returns; end sessions via state.stopSession()`
+          );
+        }
+      }
     }
-    const seenParentHooks = /* @__PURE__ */ new Set();
-    for (const requirement of options.parentHooks) {
-      if (!requirement || typeof requirement !== "object") {
-        throw new Error("parentHooks entries must be objects");
+    if (backing === "human" && side.subagents !== void 0) {
+      error(
+        "agent_subagents_on_human_side",
+        `${sideKey}.subagents`,
+        "A human-backed side cannot own subagent relationships \u2014 nothing there can invoke them. Declare them on the sibling side."
+      );
+    }
+    if (backing === "prompt") {
+      if (side.stopTool !== void 0 && side.stopToolResponseProperty === void 0) {
+        error(
+          "agent_stop_tool_response_property_missing",
+          `${sideKey}.stopToolResponseProperty`,
+          `${sideKey}.stopToolResponseProperty is required when ${sideKey}.stopTool is set`
+        );
       }
-      if (!requirement.hook || typeof requirement.hook !== "string") {
-        throw new Error("parentHooks[].hook is required");
+      if (side.maxSteps !== void 0 && (typeof side.maxSteps !== "number" || side.maxSteps <= 0)) {
+        error(
+          "agent_max_steps_invalid",
+          `${sideKey}.maxSteps`,
+          `${sideKey}.maxSteps must be a positive number`
+        );
       }
-      if (typeof requirement.reason !== "string" || !requirement.reason.trim()) {
-        throw new Error(`parentHooks reason is required for hook '${requirement.hook}'`);
+      for (const bindingKey of ["sessionStop", "sessionFail", "sessionStatus"]) {
+        const binding = side[bindingKey];
+        if (binding === void 0) continue;
+        if (typeof binding === "string") {
+          error(
+            "agent_session_binding_legacy_string",
+            `${sideKey}.${bindingKey}`,
+            `The bare-string session binding was removed in 0.2.0 \u2014 use the object form: ${bindingKey}: { name: '${binding}' }. ${MIGRATION_URL}`
+          );
+          continue;
+        }
+        if (!isRecord(binding) || typeof binding.name !== "string" || !binding.name) {
+          error(
+            "agent_session_binding_invalid",
+            `${sideKey}.${bindingKey}.name`,
+            `${sideKey}.${bindingKey}.name is required and must be a tool name`
+          );
+        }
       }
-      if (requirement.stage !== void 0 && requirement.stage !== "before_parent" && requirement.stage !== "after_parent") {
-        throw new Error(
-          `Invalid parentHooks stage '${requirement.stage}' for hook '${requirement.hook}'`
+    }
+    if (backing !== "human" && side.subagents !== void 0) {
+      if (!Array.isArray(side.subagents)) {
+        error(
+          "subagent_relationship_invalid",
+          `${sideKey}.subagents`,
+          `${sideKey}.subagents must be an array of relationships`
         );
+      } else {
+        side.subagents.forEach((relationship, index) => {
+          const path = `${sideKey}.subagents[${index}]`;
+          if (!isRecord(relationship)) {
+            error(
+              "subagent_relationship_invalid",
+              path,
+              "Each subagent relationship must be an object"
+            );
+            return;
+          }
+          if (relationship.name !== void 0) {
+            error(
+              "subagent_legacy_name",
+              `${path}.name`,
+              `'name' was removed in 0.2.0 \u2014 the relationship name is 'as' (defaulting to the agent name) and the target agent is 'agent'. ${MIGRATION_URL}`
+            );
+          }
+          if (relationship.resumable !== void 0) {
+            error(
+              "subagent_legacy_resumable",
+              `${path}.resumable`,
+              `'resumable' was removed in 0.2.0 \u2014 every child instance is a persistent thread. Move maxInstances and parentCommunication to the relationship top level and delete receives_messages. ${MIGRATION_URL}`
+            );
+          }
+          if (relationship.receives_messages !== void 0) {
+            error(
+              "subagent_legacy_receives_messages",
+              `${path}.receives_messages`,
+              `'receives_messages' was removed in 0.2.0 \u2014 child traffic lands on the side that owns the relationship. Declare the relationship on the side that should receive the messages. ${MIGRATION_URL}`
+            );
+          }
+          if (typeof relationship.agent !== "string" || !relationship.agent) {
+            error(
+              "subagent_agent_missing",
+              `${path}.agent`,
+              `'agent' is required and must name the agent definition to instantiate`
+            );
+            return;
+          }
+          if (relationship.as !== void 0 && (typeof relationship.as !== "string" || !relationship.as)) {
+            error(
+              "subagent_relationship_invalid",
+              `${path}.as`,
+              `'as' must be a non-empty relationship name when provided`
+            );
+            return;
+          }
+          if (relationship.maxInstances !== void 0 && (typeof relationship.maxInstances !== "number" || relationship.maxInstances <= 0)) {
+            error(
+              "subagent_max_instances_invalid",
+              `${path}.maxInstances`,
+              `'maxInstances' must be a positive number when provided`
+            );
+          }
+          const relationshipName = typeof relationship.as === "string" && relationship.as ? relationship.as : relationship.agent;
+          if (RESERVED_NAMES.has(relationshipName)) {
+            error(
+              "subagent_relationship_reserved_name",
+              `${path}.as`,
+              `Relationship name '${relationshipName}' is reserved for the injected lifecycle tools (${RESERVED_RELATIONSHIP_NAMES.join(", ")}). Choose another 'as' name.`
+            );
+          }
+          const existingOwner = relationshipOwners.get(relationshipName);
+          if (existingOwner !== void 0) {
+            error(
+              "subagent_relationship_duplicate",
+              `${path}.as`,
+              existingOwner === sideKey ? `Relationship name '${relationshipName}' is declared twice on ${sideKey}. Give the second declaration a distinct 'as' alias.` : `Relationship name '${relationshipName}' is already owned by ${existingOwner} \u2014 a relationship name may appear on at most one side of an agent.`
+            );
+          } else {
+            relationshipOwners.set(relationshipName, sideKey);
+          }
+        });
       }
-      if (seenParentHooks.has(requirement.hook)) {
-        throw new Error(`Duplicate parentHooks hook '${requirement.hook}'`);
+    }
+  }
+  const sideA = isRecord(def.sideA) ? def.sideA : void 0;
+  const sideB = isRecord(def.sideB) ? def.sideB : void 0;
+  if (sideA !== void 0 && sideB !== void 0 && backingOf(sideA) === "human" && backingOf(sideB) === "human") {
+    error(
+      "agent_both_sides_human",
+      "sideB",
+      "Both sides human is reserved in this version \u2014 runtimes reject it. Back at least one side with a prompt or handler."
+    );
+  }
+  if (def.maxSessionTurns !== void 0 && def.maxSessionTurns !== null && (typeof def.maxSessionTurns !== "number" || def.maxSessionTurns <= 0)) {
+    error(
+      "agent_max_session_turns_invalid",
+      "maxSessionTurns",
+      "maxSessionTurns must be a positive number"
+    );
+  }
+  if (def.exposeAsTool === true && !def.toolDescription) {
+    error(
+      "agent_tool_description_missing",
+      "toolDescription",
+      "toolDescription is required when exposeAsTool is true"
+    );
+  }
+  if (def.tenvs !== void 0) {
+    warning(
+      "agent_tenvs_deprecated",
+      "tenvs",
+      `'tenvs' is deprecated \u2014 use 'env' instead`
+    );
+  }
+  if (def.parentHooks !== void 0) {
+    if (!Array.isArray(def.parentHooks)) {
+      error(
+        "agent_parent_hooks_invalid",
+        "parentHooks",
+        "parentHooks must be an array"
+      );
+    } else {
+      if (!def.exposeAsTool) {
+        error(
+          "agent_parent_hooks_invalid",
+          "parentHooks",
+          "parentHooks requires exposeAsTool: true \u2014 only a composable agent can require hooks on a parent"
+        );
       }
-      seenParentHooks.add(requirement.hook);
+      const seen = /* @__PURE__ */ new Set();
+      def.parentHooks.forEach((requirement, index) => {
+        const path = `parentHooks[${index}]`;
+        if (!isRecord(requirement)) {
+          error(
+            "agent_parent_hooks_invalid",
+            path,
+            "parentHooks entries must be objects"
+          );
+          return;
+        }
+        if (typeof requirement.hook !== "string" || !requirement.hook) {
+          error(
+            "agent_parent_hooks_invalid",
+            `${path}.hook`,
+            "parentHooks[].hook is required"
+          );
+          return;
+        }
+        if (typeof requirement.reason !== "string" || !requirement.reason.trim()) {
+          error(
+            "agent_parent_hooks_invalid",
+            `${path}.reason`,
+            `parentHooks reason is required for hook '${requirement.hook}'`
+          );
+        }
+        if (requirement.stage !== void 0 && requirement.stage !== "before_parent" && requirement.stage !== "after_parent") {
+          error(
+            "agent_parent_hooks_invalid",
+            `${path}.stage`,
+            `Invalid parentHooks stage '${String(requirement.stage)}' for hook '${requirement.hook}'`
+          );
+        }
+        if (seen.has(requirement.hook)) {
+          error(
+            "agent_parent_hooks_invalid",
+            `${path}.hook`,
+            `Duplicate parentHooks hook '${requirement.hook}'`
+          );
+        }
+        seen.add(requirement.hook);
+      });
     }
   }
-  validateSessionBinding("sideA", "sessionStop");
-  validateSessionBinding("sideA", "sessionFail");
-  validateSessionBinding("sideA", "sessionStatus");
-  if (options.sideB) {
-    validateSessionBinding("sideB", "sessionStop");
-    validateSessionBinding("sideB", "sessionFail");
-    validateSessionBinding("sideB", "sessionStatus");
+  return issues;
+}
+
+// src/agents.ts
+function defineAgent(options) {
+  const errors = validateAgentDefinition(options).filter(
+    (issue) => issue.severity === "error"
+  );
+  if (errors.length > 0) {
+    throw new Error(
+      errors.map((issue) => `${issue.path}: ${issue.message}`).join("\n")
+    );
   }
-  return {
-    ...options,
-    type
-  };
+  return options;
 }
 
 // src/threads.ts
@@ -482,9 +782,16 @@ function isVisibleInNamespace(metadata, namespace, isEntryPoint = false) {
   const isOwnPackage = hasPkg && metadata.__package.packageId === namespace.packageId;
   return isOwnPackage || hasPkg && isEntryPoint;
 }
+
+// src/index.ts
+var SPEC_VERSION = "0.2.0";
 export {
+  DEFINITION_ISSUE_CODES,
   ENDPOINT_ACCESS_SYMBOL,
+  HANDLER_SYMBOL,
   ProviderError,
+  RESERVED_RELATIONSHIP_NAMES,
+  SPEC_VERSION,
   THREAD_ENDPOINT_SYMBOL,
   THREAD_STREAM_REASONING_PARAM,
   USER_ENDPOINT_SYMBOL,
@@ -492,6 +799,7 @@ export {
   defineAgent,
   defineController,
   defineEffect,
+  defineHandler,
   defineHook,
   defineModel,
   definePrompt,
@@ -500,6 +808,7 @@ export {
   defineTool,
   defineUserEndpoint,
   getEndpointAccess,
+  isHandler,
   isPacked,
   isThreadEndpoint,
   isUserEndpoint,
@@ -508,6 +817,7 @@ export {
   providerConst,
   providerEnv,
   providerValue,
+  validateAgentDefinition,
   validateToolName
 };
 //# sourceMappingURL=index.js.map