@stigmer/react 0.0.36 → 0.0.40

package/src/library/serialize-resource-yaml.ts

@@ -0,0 +1,407 @@
+import { stringify as stringifyYaml } from "yaml";
+import type { Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import type {
+  AgentSpec,
+  McpServerUsage,
+  SubAgent,
+  McpAccess,
+  ToolApprovalOverride,
+} from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
+import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import type {
+  McpServerSpec,
+  StdioServerConfig,
+  HttpServerConfig,
+  ToolApprovalPolicy,
+} from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/spec_pb";
+import type { ApiResourceReference } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
+import type { EnvironmentSpec } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/spec_pb";
+
+/**
+ * Serializes a proto `Agent` into the canonical Stigmer YAML format.
+ *
+ * This is the inverse of {@link parseResourceYaml} — the serialized YAML
+ * is round-trip compatible and can be fed back through `parseResourceYaml`
+ * to produce a valid `AgentInput`.
+ *
+ * Only emits `apiVersion`, `kind`, `metadata`, and `spec`. The `status`
+ * field is system-managed and never included in the YAML output.
+ *
+ * Uses snake_case field names in the YAML to match the proto canonical form,
+ * which is the format expected by both the backend and `parseResourceYaml`.
+ *
+ * @param agent - The proto `Agent` resource to serialize.
+ * @returns A YAML string suitable for editing and re-applying.
+ *
+ * @example
+ * ```ts
+ * import { serializeAgentYaml } from "@stigmer/react";
+ *
+ * const yaml = serializeAgentYaml(agent);
+ * const file = new File([yaml], "my-agent.yaml", { type: "text/yaml" });
+ * ```
+ *
+ * @see {@link parseResourceYaml} for the inverse operation
+ */
+export function serializeAgentYaml(agent: Agent): string {
+  const doc: Record<string, unknown> = {
+    apiVersion: agent.apiVersion || "agentic.stigmer.ai/v1",
+    kind: agent.kind || "Agent",
+    metadata: buildMetadata(agent.metadata),
+    spec: buildAgentSpec(agent.spec),
+  };
+
+  return stringifyYaml(doc, { lineWidth: 0, blockQuote: "literal" });
+}
+
+/**
+ * Serializes a proto `McpServer` into the canonical Stigmer YAML format.
+ *
+ * This is the inverse of {@link parseResourceYaml} for McpServer resources.
+ * Same round-trip guarantee and snake_case convention as {@link serializeAgentYaml}.
+ *
+ * @param mcpServer - The proto `McpServer` resource to serialize.
+ * @returns A YAML string suitable for editing and re-applying.
+ *
+ * @example
+ * ```ts
+ * import { serializeMcpServerYaml } from "@stigmer/react";
+ *
+ * const yaml = serializeMcpServerYaml(mcpServer);
+ * const file = new File([yaml], "my-server.yaml", { type: "text/yaml" });
+ * ```
+ *
+ * @see {@link parseResourceYaml} for the inverse operation
+ */
+export function serializeMcpServerYaml(mcpServer: McpServer): string {
+  const doc: Record<string, unknown> = {
+    apiVersion: mcpServer.apiVersion || "agentic.stigmer.ai/v1",
+    kind: mcpServer.kind || "McpServer",
+    metadata: buildMetadata(mcpServer.metadata),
+    spec: buildMcpServerSpec(mcpServer.spec),
+  };
+
+  return stringifyYaml(doc, { lineWidth: 0, blockQuote: "literal" });
+}
+
+// ---------------------------------------------------------------------------
+// Metadata
+// ---------------------------------------------------------------------------
+
+function buildMetadata(
+  metadata: Agent["metadata"] | McpServer["metadata"],
+): Record<string, unknown> {
+  if (!metadata) return {};
+
+  const result: Record<string, unknown> = {
+    name: metadata.name,
+  };
+
+  if (metadata.org) {
+    result.org = metadata.org;
+  }
+
+  if (metadata.slug && metadata.slug !== metadata.name) {
+    result.slug = metadata.slug;
+  }
+
+  if (hasEntries(metadata.labels)) {
+    result.labels = { ...metadata.labels };
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Agent spec
+// ---------------------------------------------------------------------------
+
+function buildAgentSpec(
+  spec: AgentSpec | undefined,
+): Record<string, unknown> {
+  if (!spec) return {};
+
+  const result: Record<string, unknown> = {};
+
+  if (spec.description) {
+    result.description = spec.description;
+  }
+
+  if (spec.iconUrl) {
+    result.icon_url = spec.iconUrl;
+  }
+
+  if (spec.instructions) {
+    result.instructions = spec.instructions;
+  }
+
+  if (spec.mcpServerUsages.length > 0) {
+    result.mcp_server_usages = spec.mcpServerUsages.map(serializeMcpServerUsage);
+  }
+
+  if (spec.skillRefs.length > 0) {
+    result.skill_refs = spec.skillRefs.map(serializeResourceRef);
+  }
+
+  if (spec.subAgents.length > 0) {
+    result.sub_agents = spec.subAgents.map(serializeSubAgent);
+  }
+
+  if (spec.envSpec) {
+    const envSpec = serializeEnvSpec(spec.envSpec);
+    if (envSpec) {
+      result.env_spec = envSpec;
+    }
+  }
+
+  return result;
+}
+
+function serializeMcpServerUsage(
+  usage: McpServerUsage,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+
+  if (usage.mcpServerRef) {
+    result.mcp_server_ref = serializeResourceRef(usage.mcpServerRef);
+  }
+
+  if (usage.enabledTools.length > 0) {
+    result.enabled_tools = [...usage.enabledTools];
+  }
+
+  if (usage.toolApprovalOverrides.length > 0) {
+    result.tool_approval_overrides =
+      usage.toolApprovalOverrides.map(serializeToolApprovalOverride);
+  }
+
+  return result;
+}
+
+function serializeToolApprovalOverride(
+  override: ToolApprovalOverride,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {
+    tool_name: override.toolName,
+    requires_approval: override.requiresApproval,
+  };
+
+  if (override.message) {
+    result.message = override.message;
+  }
+
+  return result;
+}
+
+function serializeSubAgent(sub: SubAgent): Record<string, unknown> {
+  const result: Record<string, unknown> = {
+    name: sub.name,
+  };
+
+  if (sub.description) {
+    result.description = sub.description;
+  }
+
+  if (sub.instructions) {
+    result.instructions = sub.instructions;
+  }
+
+  if (sub.modelOverride) {
+    result.model_override = sub.modelOverride;
+  }
+
+  if (sub.mcpAccess.length > 0) {
+    result.mcp_access = sub.mcpAccess.map(serializeMcpAccess);
+  }
+
+  if (sub.skillRefs.length > 0) {
+    result.skill_refs = sub.skillRefs.map(serializeResourceRef);
+  }
+
+  return result;
+}
+
+function serializeMcpAccess(access: McpAccess): Record<string, unknown> {
+  const result: Record<string, unknown> = {
+    mcp_server: access.mcpServer,
+  };
+
+  if (access.enabledTools.length > 0) {
+    result.enabled_tools = [...access.enabledTools];
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// McpServer spec
+// ---------------------------------------------------------------------------
+
+function buildMcpServerSpec(
+  spec: McpServerSpec | undefined,
+): Record<string, unknown> {
+  if (!spec) return {};
+
+  const result: Record<string, unknown> = {};
+
+  if (spec.description) {
+    result.description = spec.description;
+  }
+
+  if (spec.iconUrl) {
+    result.icon_url = spec.iconUrl;
+  }
+
+  if (spec.tags.length > 0) {
+    result.tags = [...spec.tags];
+  }
+
+  if (spec.serverType.case === "stdio") {
+    result.stdio = serializeStdioConfig(spec.serverType.value);
+  } else if (spec.serverType.case === "http") {
+    result.http = serializeHttpConfig(spec.serverType.value);
+  }
+
+  if (spec.defaultEnabledTools.length > 0) {
+    result.default_enabled_tools = [...spec.defaultEnabledTools];
+  }
+
+  if (spec.defaultToolApprovals.length > 0) {
+    result.default_tool_approvals =
+      spec.defaultToolApprovals.map(serializeToolApprovalPolicy);
+  }
+
+  if (spec.envSpec) {
+    const envSpec = serializeEnvSpec(spec.envSpec);
+    if (envSpec) {
+      result.env_spec = envSpec;
+    }
+  }
+
+  return result;
+}
+
+function serializeStdioConfig(
+  config: StdioServerConfig,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {
+    command: config.command,
+  };
+
+  if (config.args.length > 0) {
+    result.args = [...config.args];
+  }
+
+  if (config.workingDir) {
+    result.working_dir = config.workingDir;
+  }
+
+  return result;
+}
+
+function serializeHttpConfig(
+  config: HttpServerConfig,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {
+    url: config.url,
+  };
+
+  if (hasEntries(config.headers)) {
+    result.headers = { ...config.headers };
+  }
+
+  if (hasEntries(config.queryParams)) {
+    result.query_params = { ...config.queryParams };
+  }
+
+  if (config.timeoutSeconds > 0) {
+    result.timeout_seconds = config.timeoutSeconds;
+  }
+
+  return result;
+}
+
+function serializeToolApprovalPolicy(
+  policy: ToolApprovalPolicy,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {
+    tool_name: policy.toolName,
+  };
+
+  if (policy.message) {
+    result.message = policy.message;
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Shared serializers
+// ---------------------------------------------------------------------------
+
+function serializeResourceRef(
+  ref: ApiResourceReference,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+
+  if (ref.org) {
+    result.org = ref.org;
+  }
+
+  if (ref.kind) {
+    result.kind = ref.kind;
+  }
+
+  result.slug = ref.slug;
+
+  if (ref.version) {
+    result.version = ref.version;
+  }
+
+  return result;
+}
+
+function serializeEnvSpec(
+  envSpec: EnvironmentSpec,
+): Record<string, unknown> | undefined {
+  if (!hasEntries(envSpec.data)) return undefined;
+
+  const data: Record<string, Record<string, unknown>> = {};
+
+  for (const [key, val] of Object.entries(envSpec.data)) {
+    const entry: Record<string, unknown> = {};
+
+    if (val.value) {
+      entry.value = val.value;
+    }
+
+    if (val.isSecret) {
+      entry.is_secret = val.isSecret;
+    }
+
+    if (val.description) {
+      entry.description = val.description;
+    }
+
+    data[key] = entry;
+  }
+
+  const result: Record<string, unknown> = {};
+
+  if (envSpec.description) {
+    result.description = envSpec.description;
+  }
+
+  result.data = data;
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Utilities
+// ---------------------------------------------------------------------------
+
+function hasEntries(obj: Record<string, unknown> | undefined): boolean {
+  if (!obj) return false;
+  return Object.keys(obj).length > 0;
+}

package/src/library/useApplyResource.ts

@@ -0,0 +1,211 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import { create } from "@bufbuild/protobuf";
+import { PushSkillFromExecutionArtifactRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/io_pb";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+import { parseResourceYaml } from "./parse-resource-yaml";
+
+/**
+ * Result returned after successfully applying a resource to an organization.
+ *
+ * Contains the minimum metadata needed to display a success message and
+ * link to the resource in the Library (e.g., `/library/agents`).
+ */
+export interface ApplyResourceResult {
+  /** The resource kind that was applied. */
+  readonly kind: "Agent" | "McpServer" | "Skill";
+  /** The resource name (from response metadata). */
+  readonly name: string;
+  /** The organization the resource was applied to. */
+  readonly org: string;
+  /** The URL-friendly slug (from response metadata). */
+  readonly slug: string;
+}
+
+/**
+ * Parameters for pushing a skill package from an execution artifact.
+ *
+ * The server reads the directory artifact (ZIP) from execution storage
+ * and pushes it as a skill — no ZIP download reaches the browser.
+ */
+export interface PushSkillParams {
+  /** Organization that will own the skill. */
+  readonly org: string;
+  /** ID of the execution that produced the artifact (format: `aex_{ulid}`). */
+  readonly executionId: string;
+  /** Storage key of the directory artifact. Must start with `artifacts/{executionId}/`. */
+  readonly storageKey: string;
+  /** Optional version tag (e.g., `"stable"`, `"v1.0"`). */
+  readonly tag?: string;
+}
+
+export interface UseApplyResourceReturn {
+  /**
+   * Apply a Stigmer resource YAML (Agent or McpServer) to an organization.
+   *
+   * Parses the YAML content, converts it to the appropriate SDK input type,
+   * and calls `stigmer.agent.apply()` or `stigmer.mcpServer.apply()` based
+   * on the detected `kind`.
+   *
+   * The `org` parameter overrides `metadata.org` in the YAML — matching
+   * the "Apply to [my-org]" UX intent.
+   *
+   * @throws Re-throws the original error after setting `error` state, so
+   *   callers can optionally catch for flow control.
+   */
+  readonly applyYamlResource: (
+    content: string,
+    org: string,
+  ) => Promise<ApplyResourceResult>;
+
+  /**
+   * Push a skill package from an execution artifact to an organization.
+   *
+   * Uses the server-side `pushFromExecutionArtifact` RPC — the server reads
+   * the ZIP from execution storage and pushes it as a skill. No ZIP download
+   * reaches the browser.
+   *
+   * @throws Re-throws the original error after setting `error` state.
+   */
+  readonly pushSkillPackage: (
+    params: PushSkillParams,
+  ) => Promise<ApplyResourceResult>;
+
+  /** `true` while an apply or push operation is in-flight. */
+  readonly isApplying: boolean;
+
+  /** Error from the last failed operation, or `null` when healthy. */
+  readonly error: Error | null;
+
+  /** Clear the error state (e.g., when the user dismisses an error message). */
+  readonly clearError: () => void;
+}
+
+/**
+ * Behavior hook for applying detected Stigmer resources to an organization.
+ *
+ * Bridges the detection layer ({@link detectStigmerResource},
+ * {@link useDetectSkillPackage}) to the apply action — the user clicks
+ * "Apply to [org]" and the resource is created or updated.
+ *
+ * Handles two parallel apply paths:
+ *
+ * 1. **YAML resources** (Agent, McpServer): `applyYamlResource(content, org)`
+ *    parses the YAML, converts snake_case fields to SDK input types, and
+ *    calls the appropriate `apply()` method.
+ *
+ * 2. **Skill packages** (directory artifacts): `pushSkillPackage(params)`
+ *    delegates to the server-side `pushFromExecutionArtifact` RPC.
+ *
+ * Follows the established mutation hook pattern: `isApplying` + `error` +
+ * `clearError`. The result is returned from the promise (not stored in
+ * hook state) — consistent with {@link useCreateOrganization} and other
+ * SDK mutation hooks.
+ *
+ * @example
+ * ```tsx
+ * const { applyYamlResource, pushSkillPackage, isApplying, error, clearError } =
+ *   useApplyResource();
+ * const [result, setResult] = useState<ApplyResourceResult | null>(null);
+ *
+ * const handleApply = async () => {
+ *   clearError();
+ *   try {
+ *     if (yamlDetection.detected) {
+ *       setResult(await applyYamlResource(content!, activeOrg));
+ *     } else if (skillDetection.detected) {
+ *       setResult(await pushSkillPackage({
+ *         org: activeOrg,
+ *         executionId,
+ *         storageKey: artifact.storageKey,
+ *       }));
+ *     }
+ *   } catch {
+ *     // error state is set by the hook
+ *   }
+ * };
+ * ```
+ *
+ * @see {@link parseResourceYaml} for the pure YAML-to-input conversion
+ * @see {@link detectStigmerResource} for YAML resource detection
+ * @see {@link useDetectSkillPackage} for skill package detection
+ */
+export function useApplyResource(): UseApplyResourceReturn {
+  const stigmer = useStigmer();
+  const [isApplying, setIsApplying] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const applyYamlResource = useCallback(
+    async (content: string, org: string): Promise<ApplyResourceResult> => {
+      setIsApplying(true);
+      setError(null);
+
+      try {
+        const parsed = parseResourceYaml(content, org);
+
+        switch (parsed.kind) {
+          case "Agent": {
+            const agent = await stigmer.agent.apply(parsed.input);
+            return {
+              kind: "Agent",
+              name: agent.metadata?.name ?? parsed.input.name,
+              org: agent.metadata?.org ?? org,
+              slug: agent.metadata?.slug ?? parsed.input.name,
+            };
+          }
+          case "McpServer": {
+            const mcpServer = await stigmer.mcpServer.apply(parsed.input);
+            return {
+              kind: "McpServer",
+              name: mcpServer.metadata?.name ?? parsed.input.name,
+              org: mcpServer.metadata?.org ?? org,
+              slug: mcpServer.metadata?.slug ?? parsed.input.name,
+            };
+          }
+        }
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsApplying(false);
+      }
+    },
+    [stigmer],
+  );
+
+  const pushSkillPackage = useCallback(
+    async (params: PushSkillParams): Promise<ApplyResourceResult> => {
+      setIsApplying(true);
+      setError(null);
+
+      try {
+        const request = create(PushSkillFromExecutionArtifactRequestSchema, {
+          org: params.org,
+          executionId: params.executionId,
+          storageKey: params.storageKey,
+          tag: params.tag ?? "",
+        });
+
+        const skill = await stigmer.skill.pushFromExecutionArtifact(request);
+        return {
+          kind: "Skill",
+          name: skill.metadata?.name ?? "",
+          org: skill.metadata?.org ?? params.org,
+          slug: skill.metadata?.slug ?? "",
+        };
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsApplying(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return { applyYamlResource, pushSkillPackage, isApplying, error, clearError };
+}

package/src/library/useDetectSkillPackage.ts

@@ -0,0 +1,91 @@
+"use client";
+
+import { useMemo } from "react";
+import type { ExecutionArtifact } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/artifact_pb";
+import { useArtifactContent } from "../execution/useArtifactContent";
+import {
+  detectSkillPackage,
+  isSkillPackage,
+  type SkillPackageDetection,
+} from "./detect-skill-package";
+
+const NOT_DETECTED: SkillPackageDetection = { detected: false } as const;
+
+export interface UseDetectSkillPackageReturn {
+  /** The detection result — check `detection.detected` to narrow the type. */
+  readonly detection: SkillPackageDetection;
+
+  /**
+   * `true` while the SKILL.md content is being fetched from the archive.
+   * Only relevant when the artifact is a skill package — `false` immediately
+   * for non-skill artifacts.
+   */
+  readonly isLoading: boolean;
+
+  /** Error message from the SKILL.md fetch, or `null` when healthy. */
+  readonly error: string | null;
+}
+
+/**
+ * Detects whether an execution artifact is a skill package and extracts
+ * its metadata from SKILL.md.
+ *
+ * Combines the synchronous `isSkillPackage()` check (via `entries`) with
+ * a lazy content fetch of the SKILL.md file from the ZIP archive. The
+ * SKILL.md content is fetched via the `getArtifactContent` RPC with
+ * `entry_path`, so no ZIP download reaches the browser.
+ *
+ * Pass `null` for either parameter to skip detection entirely.
+ *
+ * Detection only triggers a network call when the artifact looks like a
+ * skill package (`kind === DIRECTORY` with `SKILL.md` in `entries`).
+ * For all other artifacts, returns `{ detected: false }` immediately.
+ *
+ * @param artifact - The execution artifact to inspect, or `null` to skip.
+ * @param executionId - Execution that produced the artifact, or `null` to skip.
+ *
+ * @example
+ * ```tsx
+ * const { detection, isLoading } = useDetectSkillPackage(artifact, executionId);
+ *
+ * if (isLoading) return <Spinner />;
+ *
+ * if (detection.detected) {
+ *   return (
+ *     <div>
+ *       <Badge>Skill Package</Badge>
+ *       <span>{detection.skillName}</span>
+ *       <span>{detection.fileCount} files</span>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link isSkillPackage} for the synchronous check (no content needed)
+ * @see {@link detectSkillPackage} for the pure function (non-React usage)
+ */
+export function useDetectSkillPackage(
+  artifact: ExecutionArtifact | null,
+  executionId: string | null,
+): UseDetectSkillPackageReturn {
+  const isPackage = artifact ? isSkillPackage(artifact) : false;
+
+  const { content, isLoading, error } = useArtifactContent(
+    isPackage && executionId ? executionId : null,
+    isPackage && artifact ? artifact.storageKey : null,
+    isPackage ? "SKILL.md" : null,
+  );
+
+  const detection = useMemo<SkillPackageDetection>(() => {
+    if (!artifact || !isPackage || !content) {
+      return NOT_DETECTED;
+    }
+    return detectSkillPackage(artifact, content);
+  }, [artifact, isPackage, content]);
+
+  return {
+    detection,
+    isLoading: isPackage && isLoading,
+    error: isPackage ? error : null,
+  };
+}